aboutsummaryrefslogtreecommitdiff
path: root/xbattext.ms
diff options
context:
space:
mode:
Diffstat (limited to 'xbattext.ms')
-rw-r--r--xbattext.ms100
1 files changed, 92 insertions, 8 deletions
diff --git a/xbattext.ms b/xbattext.ms
index 34b5f62..06c1269 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -1,5 +1,4 @@
.so /home/john/prj/re/re.tmac
-.nr St 6n
.TL
.BI xbattext ,
an X11 battery monitor for NetBSD
@@ -26,7 +25,7 @@ This document is a commented version of the
source code.
It is generated with
.I re ,
-a reference-based literate programming system available at the address
+a reference-based literate programming system available at the WWW address
http://git.\:ankarstrom.se/re/.
.AE
.Re xbattext.c:/^#include/
@@ -40,13 +39,16 @@ for us.
.PP
.I machine/apmvar.h
is needed in order to inspect the battery status on NetBSD.
-.Re xbattext.c:/^struct _res/
+.Re xbattext.c:/^\/\* interval in seconds/
+.LP
+By default, the battery status is checked every ten seconds.
+.Re xbattext.c:/^struct res/
.LP
Two structures are created to access the application's resources:
.I res ,
which will hold the values of the resources, and
.I res_opts ,
-which defines how those resources should be accessed.
+which defines how those resources should be retrieved.
.PP
The
.I res
@@ -64,8 +66,14 @@ http://lesstif.sourceforge.net/doc/super-ux/g1ae03e/part1/chap9.html.
.FE
.Re xbattext.c:/"alertFontList"/
\&
-.Re xbattext.c:/"chargeForeground"/
+.Re xbattext.c:/^\/\* application state/
.LP
+There is not space to explain the function of all variables
+used by the program,
+but some of them deserve a special mention:
+.PP
+.ps -1p
+.vs -1p
.I wargs
is used by
.I XtSetArg ,
@@ -74,6 +82,8 @@ which stores arguments in it, and
which sets new values for a widget
according to the arguments stored in it.
.PP
+.ps -1p
+.vs -1p
.I alert
and
.I charge
@@ -82,7 +92,81 @@ whenever
.I xbattext
detects that the battery is low or
that the AC adapter is plugged in.
+.Re xbattext.c:/XtVaAppInitialize(/
+.LP
+Many Xt functions have two variants:
+a non-variadic variant, which uses
+.I XtSetArg
+to collect arguments,
+and a variadic variant, marked by the
+.I Va
+component of its name.
.PP
-.I timer
-contains the identifier for the current timer.
-.Re xbattext.c:/^main/
+.I toplevel
+contains the
+.Q main
+widget that contains all actual widgets.
+.Re xbattext.c:/open("\/dev\/apm"/
+.LP
+The battery level is queried through
+.I ioctl
+requests to
+.I /dev/apm .
+The file descriptor is closed by the kernel when the program exits.
+.Re xbattext.c:/^ \/\* load application resources/
+.LP
+As mentioned earlier,
+.I XtGetApplicationResources
+uses the
+.I XtResource
+list defined above to fill the
+.I res
+structure with the corresponding resources.
+.bp
+.Re xbattext.c:/^ \/\* create motif label/
+.LP
+The battery level is displayed in a Motif label widget.
+It starts out containing an empty string.
+.Re xbattext.c:/^ update(/
+.LP
+Before starting the main event loop, the
+.I update
+function is called, which registers a timeout that will run
+independently of the event loop.\**
+.FS
+For more information about timeouts, see
+http://motifdeveloper.com/tips/tip16.html.
+.FE
+.Re xbattext.c:/^\/\* update battery status and (re-)add timer/
+.LP
+The
+.I update
+function, which is called at the end of each timeout,
+is responsible for checking the battery status and
+updating the label.
+.PP
+The first argument is a pointer to a value set by the user
+when the timeout is registered.
+The second argument contains a pointer to the timeout ID.
+Neither argument is used in this program.
+.Re xbattext.c:/^ \/\* get battery info/
+.LP
+As mentioned earlier,
+the battery status is retrieved through an
+.I ioctl
+request,
+.CW APM_IOC_GETPOWER .
+It returns an
+.I apm_power_info
+structure (which must be zeroed first).
+.Re xbattext.c:/^ \/\* put battery status into label/
+.LP
+The battery percentage, contained in the
+.I battery_life
+member, is written to an
+.I XmString ,
+which is a special type of string used by Motif.
+It is associated with tag,
+which contains information about the visual characteristics of the text.
+To begin with, the string is set to use the default tag.
+.Re xbattext.c:/^ i = 0;/