Clients are housed in files with the extension ".tcl". They might do anything at all, though what they in fact mainly do is to produce buttons or displays and to run and to schedule tasks. Clients can be very complex (like the Jots client, which is a notecard manager), or very simple.
There is a commented example of a very simple button-producing client called "Example" in the file tcl/Example.tcl in the tkgoodstuff library directory. You might start with it.
This document is not as complete as it should be, but I think it's at least mostly correct, and hopefully it's better than nothing. Still, your best bet may be to look at the actual code for various clients.
Let's assume you are writing a client named "Foo". Your Foo.tcl file is "sourced" by tkgoodstuff when it reads the configuration file (or when Foo is added in the preferences manager). If you have defined a procedure "FooDoOnLoad", it is called then, as is "FooDeclare", if it exists ("FooDeclare" is called also when Foo is added in the preferences manager). "FooDeclare" should contain all your calls to TKGDeclare (for declaring preferences items). TKGDeclare is described below.
When the panel is being drawn (or redrawn following, e.g., a screen-edge move), the procedure "FooCreateWindow" is called if it exists. Ordinarily "FooCreateWindow" will make a call to TKGMakeButton or TKGLabelBox to produce a button or display window in the panel at the appropriate place. After all panels have been drawn, the procedure "FooStart", if it exists, will be called. During a screenedge move, the procedure "FooSuspend" will be called, if it exists, the client window will be ungridded, and then when the panel is redrawn "FooCreateWindow" and "FooStart" will be called.
A "tkgbutton" is a button with either text, an icon, or both on its face. This command can be used either to create a button (but see TKGMakeButton) or to configure an existing button. If TKGButton is used to create a button, the button is not placed in the tkgoodstuff panel until TKGGrid is invoked. The syntax is as follows:
TKGButton name arguments
The name is an arbitrary name for the window (containing only characters suitable for variables). The other arguments are all optional (most also take "modified" forms; see the "-mode" switch for more about this):
To set values for a mode, use modified switches like the following:
TKGButton Talk -foreground(notalk) red \
-exec(notalk) {mesg y}
(Unmodified switches set the values for the current mode.) The parameters of the button are stored in a global array. If the name is "BarBar", the pathname of the created window will be stored in the global variable BarBar-params(window), the current mode in BarBar-params(mode). Mode-sensitive parameters are stored as follows: e.g., the text is stored in BarBar-params(text,normal) (supposing the button is in the normal mode, as it is by default). (In fact this is the "textvariable" for the button; setting it changes the button text directly.) There are no "unmodified" parameters for mode-sensitive parameters. For instance BarBar-params(text) does not exist.
TKGButton is a wrapper around the widget commands "tkgbutton" and "tkgmenubutton"(part of libtkg).
TKGMakeButton name . . .
Creates the indicated button, assigns it an approriate pathname, and packs it into the tkgoodstuff panel (at the position appropriate to the current stacking context). If the name is "Foo", the pathname is stored in the variable Foo-params(pathname). Takes the same arguments as TKGButton (which it calls, in fact), except that it is silly to give a "-pathname" switch to TKGMakeButton.
Creates a "label box" is a window with text on its face. The arguments are as follows:
TKGLabelBox name [-label "label text"]
(The square braces indicate that the argument is optional. If no label text is supplied, you get an empty frame, which is what Clock and Load use.)
The name is an arbitrary name for the window (containing only characters suitable for variables). If the name is "BarBar", the pathname of the created window will be stored in the global variable BarBar_window.
The text is a text string that will be displayed in the window. The window containing (just) this text has the pathname BarBar_window.label.msg. The textvariable for the label is BarBar-lbparams(text)
TKGGrid pathname
Packs the indicated window into the current tkgoodstuff panel (at the position appropriate to the current stacking context).
Two commands are provided for adding to the popup menu:
adds a cascade menu entry in the main popup menu. It is invoked as follows:
TKGPopupAddClient clientname
Suppose your clientname is FooBar. Then, this command generates a cascade menu entry labelled "FOOBAR:", and a corresponding (empty) menu with the pathname .tkgpopup.foobar, which is the menu to which you should add items in your client code.
adds an item to the main popup menu at the end of the client-added section. The arguments are any arguments that would come after ".menuname add" in a normal addition of an item to a menu.
You can schedule a Tcl command for periodic execution as follows:
TKGPeriodic name period offset command
You should try not to do anything periodically in this way that will take a lot of time to finish processing (e.g., don't have a periodically-called procedure wait for something before returning), since this will screw up the user interface responsiveness and other periodic processes. If you have to do something time-consuming, you should exec a shell script in the background with bgexec (see the BLT documentation) and trace the bgexec variable to get its output (for an example see Ical_fetch in Ical.tcl).
To cancel a scheduled periodic command, use:
TKGPeriodicCancel name
This will cancel any command that was scheduled by the same name with TKGPeriodic.
TKGDialog name [ -wmtitle string ] [ -title string ] \
[-image imagefilename] [-message string] [-text string] \
[-titlebg color] [-titlefg color] [-bitmapfg color] \
[-buttons buttonlist] [-nodismiss]
All the options in brackets are optional. This command pops up a dialog box with pathname ".name". The -wmtitle string is what will be put in the window manager title bar. The -title string is put in the dialog box title frame (up top, in a large font). The icon from the file named by the -imagefilename identifier is also put in the title frame. The -message string is put in a framed message widget under the title frame, if any. The -text widget is put in a scrollable text widget under the title frame, if any (and message frame, if any). The color options are as follows: -titlebg is the background of the title frame; -titlefg is the foreground of the title string; and -bitmapfg is the foreground color of the icon (if it is a bitmap; otherwise this switch does nothing). The button list is a list of button items, where a button item is a list of three items: a (lowercase) name for the button (the button's pathname will be ".name.buttons.buttonname"), a string of text to put on the button, and the command that the button will execute when pressed (usually this should include "destroy .name"). Unless you include the argument "-nodismiss", there will also be a button labelled "Dismiss" which destroys the dialog. The buttons are placed at the bottom of the dialog, left to right in the order of your list, with the default "Dismiss" button at the right.
TKGNotice "Notice text."
Posts a simple notice dialog with a dismiss button.
TKGError "Error text." ?exit?
Posts an error dialog with a dismiss button, a stack-trace button, and a preferences manager button. If "exit" is present, tkgoodstuff will be suspended and will exit when dismissed.
ColorConfig pathname foregroundcolor backgroundcolor
This command sets the foreground and background colors of the window whose pathname you indicate, as well as the colors of its descendants, to the colors you name. Using "-" in place of the name of a color leaves that feature unchanged.
RecursiveBind pathname sequence command
This command binds the sequence to the indicated command in the window whose pathname you indicate as well as in all of its descendants.
TKGDeclare variable value [-typelist {type1 type2 ...}] \
[-vartype boolean/radio/optionMenu/text/entry] \
[-textsize WxH] \
[-radiolist {{"Label 1" value1} {"Label 2" value2} ...}\
[-optionlist {value1 value2 ...}]\
[-label "Preferences Manager Label text"] \
[-help "Preferences Manager Help text"]
This command sets the indicated variable to value unless the variable already has a value (due, e.g., to the user's preferences settings), in which case that value is retained. (This is how a client should set those of its global variable that you want users to be able to set in the preferences manager.) The other switches govern how the variable is treated in the preferences manager.
SetImage name filname
This command creates an image named name, reading it from the file filename, and returns the image type (e.g., "bitmap", "photo").
DEBUG string
This command writes the string to the internal log, and, if TKGLogging is 1, also to the log file.