►i3status
1 Introduction
2 Function Reference
start-status
system-time
cpu-time
battery-charge
mail
mpd
5.3.5

i3status

1 Introduction

This package makes it easy to create your own status bar for the i3 window manager. It provides functions you may use to populate your status bar as well as functions for providing your status bar to i3. It’s very likely that you’ll want items in your status bar that aren’t available in this package, it’s my hope that this will be enough to get you started."

The i3 window manager status bar works like this: i3 will start the status bar process, this process will output a continuous stream of JSON data and this data will be used to populate the status bar. This package includes a sample shell script that i3 may invoke to start the status bar.

#!/usr/local/bin/racket
#lang racket
 
;;
;; Provides a stream of continuous i3bar protocol compatible data that may be
;; used to populate the status bar area in the i3 window manager.
;;
(require (planet cmiles74/i3status:1:3))
 
(start-status (lambda () (list (mpd)             ;; music player daemon status
                               (mail)            ;; notmuch inbox status
                               (battery-charge)  ;; current battery charge
                               (cpu-time)        ;; CPU load over the last 250ms
                               (system-time))))  ;; current system time
 

The stanza above requires this library and then starts a new status bar process and passes it a function that produces the content for the status bar. The start-status function will invoke that content function once every second, updating the i3 status bar.

Each content function returns a hash-map, the keys of which correspond to the keys the JSON structure that makes up the i3bar input protocol.

The solarized theme is provided and used by default. If you’d like to use your own, simply pass a map of colors to the status functions.

#hash((blue     . "#268bd2")
      (yellow   . "#b58900")
      (red      . "#dc322f")
      (magenta  . "#d33682"))

2 Function Reference

The following reference documents the exported functions in the "main.rkt" file.

 (require "main.rkt")

In practice, you’ll want to require the Planet package.

(require (planet cmiles74/i3status:1:0))

procedure

(start-status status-fn #:delay delay) → json-string

  status-fn : proc
  delay : number
Starts a process that will provide status bar data to i3. The status-fn should return a list of hash-map, each hash-map containing the content of a status bar item. The status-fn will be invoked once every second to provide updated data to the status bar.

The delay parameter specifies the number of seconds to wait before providing another batch of status data. The default is one second and fractional values may be provided.

procedure

(system-time #:full-format full-format    
  #:short-format short-format) → hash
  full-format : format-string
  short-format : format-string
Returns a map of of status content that displays the current system time. The map will contain two values, one representing the full text and one with short text, i3 will use the short text if it doesn’t have enough room for the full version.

The full-format parameter can be used to provide your own date->string format string, likewise the short-format accepts a date->string format string for the short version.

procedure

(cpu-time #:color-scheme color-scheme    
  #:delay delay) → hash
  color-scheme : scheme-hash
  delay : number
Returns a hash-map of of status content that displays the current CPU usage.

The #:delay parameter can be used to set the time between collection of the two CPU load values, by default the delay is set to 0.25s. The #:color-scheme parameter accepts a map containing a customized color scheme.

procedure

(battery-charge #:color-scheme color-scheme    
  #:battery-path battery-path) → hash
  color-scheme : scheme-hash
  battery-path : file-path
Returns a hash-map of of status content that displays the current battery status.

The battery-path parameter can be used to set the path on the filesystem used to read the battery status, by default this is set to "/sys/class/power_supply/BAT0". The color-scheme parameter accepts a map containing a customized color scheme.

procedure

(mail #:color-scheme color-scheme    
  #:unread-query unread-query    
  #:read-query read-query) → hash
  color-scheme : scheme-hash
  unread-query : query-string
  read-query : query-string
Returns a hash-map of of status content that displays the number of read and unread messages in the current user’s Notmuch mailbox.

The unread-query and the read-query parameters may be used to set the queries used by Notmuch to report the number of read and unread messages. By default, they are set to "tag:inbox" and "tag:inbox and tag:unread", respectively. The color-scheme parameter accepts a map containing a customized color scheme.

procedure

(mpd #:color-scheme color-scheme) → hash

  color-scheme : scheme-hash
Returns a hash-map of of status content that displays track currently being played by MPD. If no track is playing, this content item will not be displayed.

The color-scheme parameter accepts a map containing a customized color scheme.