[Back to TkGoodStuff] TkGoodStuffrc

Configuring TkGoodStuff with the ~/.tkgoodstuffrc file

Table of Contents (this document)

General Format

A tkgoodstuff configuration file is actually a piece of tcl code which uses commands defined by tkgoodstuff. If you don't know tcl, don't worry: the syntax you need to understand is simple. If you do know tcl, you will better be able to do fancy things.

The only lines in most configuration files are:

The order of occurence of the Client and other element-adding commands (together with the stacking commands) determines where in your panel any buttons or other frames produced by the client will appear.

Setting Variables

Setting variables explicitly is easy: your line contains the word "set", the variable, and the value you are assigning.
set TKG_orientation vertical
set TKG_nobeep 1
If you want to assign a value that contains spaces or tabs, you need to enclose it in double-quotes or in curly-brackets:
set Biff_frm_command "frm markcrim"
set Biff_frm_command {frm markcrim}
To figure out how special characters and variables are treated inside and outside of double-quotes and braces, consult the (very brief and precise but not an easy read) Tcl man page, avaiable at http://www.sco.com/Technology/tcl/man/tcl_man/Tcl.n.html, or which you probably can read as follows:
man n Tcl
One common issue is this: If you want to assign one variable a value containing the value of another (unless you are doing something fancy), use double-quotes rather than curly brackets to enclose the new value:
set user markcrim
set password getreal
set Biff_frm_command "frm $user"
set PopImap_command "mypopclientscript.sh $user $password"
Another common need is to look at environment variables. You can do this by using the $env array. To set your own variable thehome to the user's home directory, you can do this:
set thehome $env(HOME)
(See also Variables that Configure tkgoodstuff.)

Invoking and Configuring a Client

Clients are sub-programs, some of which produce buttons or other frames in your button panel (like Clock and Biff). To include one (in this case, Clock), you need a line like the following:
 Client Clock 
You configure a client by setting variables (see the documentation for the particular client for a list of the available variables). It makes no difference where in the configuration file you set client variables (e.g., before or after the Client line).

Adding a Button

You can easily add a button to display an icon and/or a bit of text, which runs a command when pressed. You need to choose: You add the button like this:
AddButton Weather -text Weather -unixcmd "rxvt -e telnet downwind.sprl.umich.edu 3000"
AddButton News -imagefile /usr/include/X11/bitmaps/news.xbm -unixcmd xrn
AddButton XV -imagefile $images/xlogo16 -text "Graphics\nProgram" -unixcmd xv
The first of these buttons displays only the label "Weather", the second displays only an icon, and the third displays both an icon and a (two-line) label.

The AddButton command requires a name for the button as its first argument. The other arguments are all optional:

  • -imagefile filename
    The button will display the icon contained in the named file
  • -text textstring
    The button will display the text indicated.
  • -unixcmd unix command
    The button, when pressed, will lauch the indicated unix command. Note: Tcl substitution is performed on the command string at execution. One thing this allows is inclusion of the current X selection in your unix command. For instance, you can run netscape on the URL currently selected thus:
    -unixcmd {netscape [string trim[selection get]]}
    
  • -tclcmd tcl command
    The button, when pressed, will perform the indicated tcl command. (This is useful only for those who know Tcl.)
  • -imageside left, right, top, or bottom
    This sets the side of the button taken by the icon, when your button has both an icon and text. "top" by default.
  • -staydown 1 or 0
    If 1 (which is the default), the button will stay down and inoperative after you press it until the launched unix command terminates. This is so you can see that you're already running that command. If 0, the button pops back up after launching the command, ready to launch the command again. This switch does not affect tcl command buttons.
  • -foreground color
  • -background color
  • -activeforeground color
  • -activebackground color
    These set the colors on the button (the "active" colors are the colors of the button when the mouse pointer passes over it).
  • There are more options that are unlikely to be needed in a configuration file. But if the listed options seem limiting, check out the documentation on writing clients for a few more options.

    Adding a Label Box

    To add a box containing a bit of text (which differs from a button in look, in color, and in that it doesn't run any command), you need to choose: You add the label box like this:
    AddLabelBox NetUtils "Favorite\nNetwork Utilities"
    

    Stacking

    The variable "TKG_orientation" governs the main orientation of you panel; it may be set to either "horizontal" or (as it is set by default) "vertical". If you simply add elements (with Client, AddButton, and AddLabelBox), these elements will be stacked all in a row left-to-right (if horizontal) or top-to-bottom (if vertical). This probably is what you want in an always-on-top desktop button bar. However you may want a fancier panel, with several rows or with several bundles of related buttons and label-boxes of different sizes, as in this example:
    To explain the stacking commands it is easiest just to explain how this example was created (you can view the config file by clicking on the image). We start horizontally (TKG_orientation is set to horizontal). We will put together two things horizontally, both of them vertical stacks. So we start with the command:
    SubStack vertical
    
    This vertical substack starts with the Clock client:
    Client Clock
    
    The next element in the substack is a labelbox:
    AddLabelBox utilities "Utilities"
    
    Then we want three buttons side-by-side, so we start a new substack:
    SubStack horizontal
     
    Then we define the three buttons with AddButton commands, and close off the substack with:
    EndSubStack
     
    This puts us back in the construction of our first (vertical) substack, which so far contains the Clock, the Utilities label, and the substack we have just finished. The last thing in this vertical substack will be another horizontal substack, this one with a colored border four pixels wide:
    SubStack horizontal 4 red
    
    Two AddButton commands create the buttons in this bordered substack, which we then end with "EndSubStack". Now we're done with the vertical substack, so we end it with another "EndSubStack". This puts us back in the orignal (horizontal) orientation, outside of all substacks. So the next item we define will go to the right of the big vertical substack we have just defined. This item will be an even bigger vertical substack, which contains a label box, a horizontal substack (which contains a button and a vertical substack of three buttons) and a (gold-bordered) vertical substack, which contains a label box and a horizontal substack (which contains three buttons and a vertical substack containing three buttons). I hope that makes the working of the stacking apparatus clear. If not, play around with it and you'll figure it out.

    Sep 14, 1995. Mark Crimmins markcrim@umich.edu

    [Back to TkGoodStuff]