From 4bd48e3a5ec63d5a242727631a236730cffc8e30 Mon Sep 17 00:00:00 2001 From: "John Ankarstr\\xf6m" Date: Fri, 4 Jun 2021 13:24:38 +0200 Subject: xbattext.ms: Finish documentation re-organization --- xbattext.c | 5 ++++ xbattext.ms | 85 +++++++++++++++++++++++++++++++++++-------------------------- 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 . -- cgit v1.2.3