aboutsummaryrefslogtreecommitdiff
path: root/xbattext.ms
diff options
context:
space:
mode:
Diffstat (limited to 'xbattext.ms')
-rw-r--r--xbattext.ms156
1 files changed, 105 insertions, 51 deletions
diff --git a/xbattext.ms b/xbattext.ms
index 44cdde8..39ffcdd 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -13,7 +13,7 @@ John Ankarström
.I xbattext
is a simple X11 program that displays, in text,
the current battery level.
-Its source code serves as a good introduction to X11 programnming.
+Its source code serves as a good introduction to X11 programming.
It is short, simple and easy to follow,
as it accounts only for a single system \(en NetBSD.
It makes use of both Xt (X toolkit intrinsics) and Xm (Motif),
@@ -36,64 +36,111 @@ If you want to see a screenshot of
.I xbattext ,
skip ahead to the last page.
.AE
+.SH
+.ce
+.sp -1v
+Definitions
+.sp 1v
.Re xbattext.c:/^#include/
.LP
+Most of the includes regard standard C features,
+but there are two special ones worth mentioning:
+.PP
.I Xm/Label.h
contains the definitions for Motif's label widget,
-which is used to display the text.
-That file, in turn, includes
-.I X11/Xlib.h
-for us.
+which is used to display the battery percentage.
+It includes the rest of the relevant X11 headers for us.
.PP
.I machine/apmvar.h
-has definitions needed in order to inspect the battery status on NetBSD.
+defines the
+.I apm_power_info
+structure,
+which is needed in order to inspect the battery status on NetBSD.
+It will be retrieved via an
+.I ioctl
+request, so
+.I sys/ioctl.h
+is included as well.
.Re xbattext.c:/^\/\* interval in seconds/
.LP
-By default, the battery status is checked every five seconds.
+The battery status is checked every five seconds by default.
.Re xbattext.c:/^\/\* low battery level/
.LP
-By default, the battery level is considered to be low
+The battery level is considered to be
+.Q low
if it is below 30 percent.
-.Re xbattext.c:/^struct res/
+.PP
+The user is encouraged to modify this and the previous constant
+according to his own preferences.
+.bp
+.Re xbattext.c:/^void update(/
+\&
+.Re xbattext.c:/^\/\* resources/
.LP
-Two structures are created to access the application's resources:
+Two structures are needed 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 retrieved.
-.PP
-The
+which de\%fines the manner in which the re\%sources should be assigned
+to the members of the
.I res
-structure is going to be filled by the function
-.I XtGetApp\%licationResources
-using the information defined in
-.I res_opts .\**
+strcture.\**
.FS
+.Q Resources
+are the settings set by the user in
+.I ~/.Xdefaults
+or
+.I ~/.Xresources .
For more information about resource management and the structure of the
.I XtResource
type, see
.nh
-http://lesstif.\:sourceforge.net/doc/super-ux/g1ae03e/part1/chap9.html.
+http://lesstif.sourceforge.net/doc/super-ux/g1ae03e/part1/\:chap9.html.
.hy
.FE
-.Re xbattext.c:/"alertFontList"/
-\&
+.PP
+At the beginning of the program's execution, the
+.I res
+structure is filled by the function
+.I XtGetApp\%licationResources
+according to the definitions in
+.I res_opts .
+.PP
+The
+.I Pixel
+type is an unsigned long value representing a color, like
+.I black
+or
+.I red3 .
+The
+.I XmFont\%List
+type
+technically represents a list of fonts,
+but for all intents and purposes,
+it will be used here only to represent a single font selection.
+.PP
+As you might guess from these resource definitions,
+.I xbattext
+allows the user to control the color and font of the battery display
+depending on the battery status.
.Re xbattext.c:/^\/\* state changes/
.LP
-The
-.I change
-variable represents the possible changes in battery state.
.I xbattext
-updates the font and color of the battery display
-whenever one of these state changes occur.
+inspects the state of the battery every five seconds.
+On every iteration, it updates the percentage displayed,
+but the font and color are changed only
+when it detects a relevant change in the battery's state.
+.PP
+When such a change is de\%tected,
+the
+.I change
+variable is set.
+Its possible values represent the range of relevant changes in battery state.
+The program then changes the color and font depending on the value of
+.I change .
+.bp
.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 an array used by
.I XtSet\%Arg ,
@@ -102,8 +149,6 @@ which stores arguments in it, and
which applies new settings to a given widget
according to the arguments stored in it.
.PP
-.ps -1p
-.vs -1p
The boolean values
.I alerting
and
@@ -113,20 +158,27 @@ whenever
.I xbattext
detects that the battery is low or
that the AC adapter is plugged in.
+.PP
+The other variables will be explained as we go along.
+.Rr
+.SH
+.ce
+Initial setup
+.sp 1v
+.Re xbattext.c:/\/\* program start/
+\&
.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.
+The application is initialized.
+.I top\%level
+is set, which will serve as the parent for all widgets.
.PP
-.I toplevel
-is the
-.Q main
-widget that contains all actual widgets.
+Note that many Xt functions have two variants:
+one that uses
+.I Xt\%SetArg
+to collect arguments,
+and a variadic variant, marked by
+.I Va .
.Re xbattext.c:/open("\/dev\/apm"/
.LP
The battery level is queried through
@@ -134,19 +186,16 @@ The battery level is queried through
requests to
.I /dev/apm .
The file descriptor is closed by the kernel when the program exits.
-.bp
.Re xbattext.c:/^ \/\* load application resources/
.LP
-As mentioned above,
.I XtGetApplicationResources
-uses the
-.I XtResour\%ce
-list defined earlier to fill the
+fills the
.I res
-structure with the corresponding resources.
+structure with the resources set in
+.I res_opts .
.Re xbattext.c:/^ \/\* create motif label/
.LP
-The battery level is displayed in a Motif label widget.
+The battery level will be displayed in a Motif label widget.
It starts out containing an empty string.
.Re xbattext.c:/^ update(/
.LP
@@ -158,6 +207,11 @@ independently of the event loop.\**
For more information about timeouts, see
http://motifdeveloper.com/tips/tip16.html.
.FE
+.Rr
+.SH
+.ce
+Operation
+.sp 1v
.Re xbattext.c:/^\/\* update battery status and (re-)add timer/
.LP
The