|author||John Ankarstr\xf6m <firstname.lastname@example.org>||2021-06-04 12:59:47 +0200|
|committer||John Ankarstr\xf6m <email@example.com>||2021-06-04 12:59:47 +0200|
xbattext.ms: Re-organize documentation
2 files changed, 107 insertions, 52 deletions
@@ -83,12 +83,13 @@ Widget toplevel, label;
+/* program start */
main(int argc, char* argv)
toplevel = XtVaAppInitialize(
diff --git a/xbattext.ms b/xbattext.ms
index 44cdde8..39ffcdd 100644
@@ -13,7 +13,7 @@ John Ankarström
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.
+Most of the includes regard standard C features,
+but there are two special ones worth mentioning:
contains the definitions for Motif's label widget,
-which is used to display the text.
-That file, in turn, includes
+which is used to display the battery percentage.
+It includes the rest of the relevant X11 headers for us.
-has definitions needed in order to inspect the battery status on NetBSD.
+which is needed in order to inspect the battery status on NetBSD.
+It will be retrieved via an
+is included as well.
.Re xbattext.c:/^\/\* interval in seconds/
-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/
-By default, the battery level is considered to be low
+The battery level is considered to be
if it is below 30 percent.
-.Re xbattext.c:/^struct res/
+The user is encouraged to modify this and the previous constant
+according to his own preferences.
+.Re xbattext.c:/^void update(/
+.Re xbattext.c:/^\/\* resources/
-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.
+which de\%fines the manner in which the re\%sources should be assigned
+to the members of the
-structure is going to be filled by the function
-using the information defined in
-.I res_opts .\**
+are the settings set by the user in
+.I ~/.Xresources .
For more information about resource management and the structure of the
+At the beginning of the program's execution, the
+structure is filled by the function
+according to the definitions in
+.I res_opts .
+type is an unsigned long value representing a color, like
+.I red3 .
+technically represents a list of fonts,
+but for all intents and purposes,
+it will be used here only to represent a single font selection.
+As you might guess from these resource definitions,
+allows the user to control the color and font of the battery display
+depending on the battery status.
.Re xbattext.c:/^\/\* state changes/
-variable represents the possible changes in battery state.
-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.
+When such a change is de\%tected,
+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 .
.Re xbattext.c:/^\/\* application state/
-There is not space to explain the function of all variables
-used by the program,
-but some of them deserve a special mention:
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.
The boolean values
@@ -113,20 +158,27 @@ whenever
detects that the battery is low or
that the AC adapter is plugged in.
+The other variables will be explained as we go along.
+.Re xbattext.c:/\/\* program start/
-Many Xt functions have two variants:
-a non-variadic variant, which uses
-to collect arguments,
-and a variadic variant, marked by the
-component of its name.
+The application is initialized.
+is set, which will serve as the parent for all widgets.
-widget that contains all actual widgets.
+Note that many Xt functions have two variants:
+one that uses
+to collect arguments,
+and a variadic variant, marked by
+.I Va .
The battery level is queried through
@@ -134,19 +186,16 @@ The battery level is queried through
.I /dev/apm .
The file descriptor is closed by the kernel when the program exits.
.Re xbattext.c:/^ \/\* load application resources/
-As mentioned above,
-list defined earlier to fill the
-structure with the corresponding resources.
+structure with the resources set in
+.I res_opts .
.Re xbattext.c:/^ \/\* create motif label/
-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(/
@@ -158,6 +207,11 @@ independently of the event loop.\**
For more information about timeouts, see
.Re xbattext.c:/^\/\* update battery status and (re-)add timer/