#lang scribble/manual @(require scribble/eval racket/file "main.rkt" (for-label "main.rkt" racket)) @title{i3status} @section{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. @(codeblock (file->string "i3status-start.sh")) 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 @racket[start-status] function will invoke that content function once every second, updating the i3 status bar. Each content function returns a @racket[hash-map], the keys of which correspond to the keys the JSON structure that makes up the @hyperlink["http://i3wm.org/docs/i3bar-protocol.html" "i3bar input protocol"]. The @hyperlink["http://ethanschoonover.com/solarized" "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. @codeblock|{ #hash((blue . "#268bd2") (yellow . "#b58900") (red . "#dc322f") (magenta . "#d33682")) }| @section{Function Reference} The following reference documents the exported functions in the "main.rkt" file. @defmodule["main.rkt"] In practice, you'll want to require the Planet package. @codeblock|{(require (planet cmiles74/i3status:1:0))}| @defproc[(start-status [status-fn proc] [#:delay delay number]) json-string]{ Starts a process that will provide status bar data to i3. The @racket[status-fn] should return a @racket[list] of @racket[hash-map], each @racket[hash-map] containing the content of a status bar item. The @racket[status-fn] will be invoked once every second to provide updated data to the status bar. The @racket[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.} @defproc[(system-time [#:full-format full-format format-string] [#:short-format short-format format-string]) hash]{ 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 @racket[full-format] parameter can be used to provide your own @racket[date->string] format string, likewise the @racket[short-format] accepts a @racket[date->string] format string for the short version.} @defproc[(cpu-time [#:color-scheme color-scheme scheme-hash] [#:delay delay number]) hash]{ Returns a hash-map of of status content that displays the current CPU usage. The @racket[#: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 @racket[#:color-scheme] parameter accepts a map containing a customized color scheme. } @defproc[(battery-charge [#:color-scheme color-scheme scheme-hash] [#:battery-path battery-path file-path]) hash]{ Returns a hash-map of of status content that displays the current battery status. The @racket[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 @racket[color-scheme] parameter accepts a map containing a customized color scheme.} @defproc[(mail [#:color-scheme color-scheme scheme-hash] [#:unread-query unread-query query-string] [#:read-query read-query query-string]) hash]{ Returns a hash-map of of status content that displays the number of read and unread messages in the current user's @hyperlink["http://notmuchmail.org/" "Notmuch"] mailbox. The @racket[unread-query] and the @racket[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 @racket[color-scheme] parameter accepts a map containing a customized color scheme.} @defproc[(mpd [#:color-scheme color-scheme scheme-hash]) 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 @racket[color-scheme] parameter accepts a map containing a customized color scheme.}