There is a commented example of a very simple 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 largely correct.
Basic Client Interface
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.
TKGButton
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 argumentsThe 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.)
TKGButton is a wrapper around the widget commands "tkgbutton" and
"tkgmenubutton"(part of libtkg).
TKGMakeButton
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.
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
TKGGrid pathnamePacks the indicated window into the current tkgoodstuff panel (at the position appropriate to the current stacking context).
TKGPopupAddClient clientnameSuppose 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.
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 nameThis 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 backgroundcolorThis 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 commandThis 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 filnameThis command creates an image named name, reading it from the file filename, and returns the image type (e.g., "bitmap", "photo").
DEBUG stringThis command writes the string to the internal log, and, if TKGLogging is 1, also to the log file.