From 909b6e7b5026e7d6fe3ef17f51e9680cfda18ed5 Mon Sep 17 00:00:00 2001 From: "John Ankarstr\\xf6m" Date: Fri, 4 Jun 2021 12:59:47 +0200 Subject: xbattext.ms: Re-organize documentation --- xbattext.c | 3 +- xbattext.ms | 156 ++++++++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 107 insertions(+), 52 deletions(-) diff --git a/xbattext.c b/xbattext.c index 36c093e..66e29fe 100644 --- a/xbattext.c +++ b/xbattext.c @@ -83,12 +83,13 @@ Widget toplevel, label; XmString xms; XtAppContext app_context; +/* program start */ int main(int argc, char* argv[]) { toplevel = XtVaAppInitialize( &app_context, - "XBat", + "xbattext", NULL, 0, &argc, argv, NULL, 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 -- cgit v1.2.3