aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--xbattext.c5
-rw-r--r--xbattext.ms85
2 files changed, 54 insertions, 36 deletions
diff --git a/xbattext.c b/xbattext.c
index 66e29fe..382aed1 100644
--- a/xbattext.c
+++ b/xbattext.c
@@ -2,6 +2,11 @@
* This is a simple X11 program that displays the battery percentage
* on NetBSD.
*
+ * If you are curious about how it works, you can download the commented
+ * version of the source code at the following address:
+ *
+ * http://img.ankarstrom.se/xbattext.pdf
+ *
* It should be compiled with the following flags:
*
* CFLAGS = -I/usr/X11R7/include -I/usr/pkg/include
diff --git a/xbattext.ms b/xbattext.ms
index 39ffcdd..e01225f 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -216,14 +216,16 @@ Operation
.LP
The
.I update
-function, which is also called at the end of each timeout,
-is responsible for checking the battery status and
-updating the label.
+both sets up the timer and is called at the end of each timeout.
+Along the way, it checks the battery status
+and updates the text displayed in the label widget.
.PP
-The first argument is a pointer to a value set by the user
+The first argument to
+.I update
+is a pointer to an arbitrary 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.
+The second argument contains a pointer to the timeout identifier.
+Neither argument is used here.
.Re xbattext.c:/^ \/\* get battery info/
.LP
As mentioned above,
@@ -249,12 +251,12 @@ We just use the default.
.LP
The
.I wargs
-array mentioned above starts to be filled with arguments
+array mentioned above now starts being filled with arguments
that determine the state of the label widget.
The number of arguments set is kept track of in the
.I i
variable.
-To begin with, the widget's label string is set to the
+To begin with, the label string is set to the
.I XmString
value defined earlier.
.Re xbattext.c:/^ \/\* check charging status/
@@ -269,16 +271,16 @@ bitmap when a change in
.I info.ac_\:state
is detected.
.PP
-Note that the value of
+(The value of
.I charging
-is used in order to prevent these font and color changes
-from unnecessarily being applied every timeout
-regardless of whether the charging status has changed.
+is checked and updated in order to prevent the font and color changes
+from unnecessarily being applied at every timeout
+regardless of whether the charging status has changed.)
+.bp
.Re xbattext.c:/^ \/\* check low battery/
.LP
The same applies when the program checks whether the battery level is below
-.CW ALERT ,
-which is set to 30 by default.
+.CW ALERT .
.Re xbattext.c:/^ \/\* prioritize/
.LP
Before the bits in
@@ -294,24 +296,38 @@ if the battery rises above the
.CW ALERT
threshold,
but the AC adapter is still plugged in.
+.PP
+(Remember that
+the
+.I change
+variable reflects a
+.B change
+in state.
+It does not reflect the
+.B state .)
.Re xbattext.c:/^ \/\* act on state changes/
.LP
After collecting and prioritizing the state changes,
-the foreground color and font of the label widget is set accordingly.
+the foreground color and font of the label widget are set accordingly.
.PP
Note that if a
.I Pixel
-(color) resource is not defined,
+resource is not defined,
.I XtGetApplicationResources
gives it the integer value zero,
-which also signifies the color black
-(thus, the program cannot differentiate
+which also signifies the color black.
+Thus, the program cannot tell the difference
between a missing value and a value of
-.I black ).
+.I black .
+.PP
Font lists, however, are set to null if undefined.
-If a font list resource is undefined,
+If the
+.I alert
+or
+.I charge
+font list is undefined,
.I xbattext
-uses the default font list instead.
+uses the main font list instead.
.Re xbattext.c:/^ case SET_CHARGE:/
\&
.Re xbattext.c:/^set:/
@@ -339,22 +355,23 @@ That is the totality of the
source
(almost; a long comment at the beginning of the file, explaining
what the program does and how it should be compiled, was excluded).
-Hopefully, it shows that graphical UNIX programming is nothing to be scared of.
+Hopefully, it shows that graphical UNIX programming is nothing to be afraid of.
While Xlib, Xt and Xm tend nowadays not to be considered
.Q "best practice" ,
they have a low barrier to entry,
-require little resources from the computer and
+require little resources of the computer and
are often installed by default on UNIX systems.
It is better to use worse practices to create
.I something
-than to use best practices and create nothing at all;
+than it is to use best practices and create nothing at all;
if those are the alternatives,
then perhaps best practices aren't.
.PP
-If, after reading the source code, you are still wondering
-why anyone would want a small window displaying the current battery level,
+If, after reading all this, you are still wondering
+why anyone would want a small window on their screen
+displaying the current battery level,
then you should get acquainted with the X11 window manager
-.I jwm \\*
+.I jwm \**
.FS
.I jwm
is available at https://joewing.net/projects/jwm/.
@@ -368,20 +385,16 @@ and its
.Q swallowing
feature,
which removes the border from a given X11 program and displays it in the tray.
-You can look at it as tray icons according to the UNIX philosophy.
-In my tray,
-.I xbattext
-sits right beside
-.I xclock
-and
-.I xload .
+You can regard it as tray icons according to the UNIX philosophy.
.sp 0.6v
.PSPIC tray.eps
.sp 0.2v
.ad c
.ps -1p
.B "Figure 1."
-.I xload ,
+In my tray,
.I xbattext
+sits right beside
+.I xclock
and
-.I xclock .
+.I xload .