#lang scribble/manual
@(require scribble/eval
	  "main.rkt"
	  (for-label "main.rkt" racket))

@title{i3status}

@section{Introduction}

This package provides makes it easy to create your own status bar for
the i3 window manager. It provide functions that you can 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|{
#!/usr/local/bin/racket
#lang racket

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

(start-status (lambda () (list (mpd)
	      	      	       (mail)
			       (battery-charge)
			       (cpu-time)
			       (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 @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"].

@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 procedure?])
		       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.}

@defproc[(system-time) hash-map]{

Returns a hash-map of of status content that displays the current system time.
}

@defproc[(cpu-time) hash-map]{

Returns a hash-map of of status content that displays the current CPU usage.
}

@defproc[(battery-charge) hash-map]{

Returns a hash-map of of status content that displays the current battery status.
}

@defproc[(mail) hash-map]{

Returns a hash-map of of status content that displays the number of read and
unread messages in the current user's notmuch mailbox.
}

@defproc[(mpd) hash-map]{

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.
}