1.3 Common Features of Widgets

A widget is a lisp symbol which has a function binding. The first argument is always a keyword and is called the option. The argument pattern for the remaining arguments depends on the option. The most common option is :configure in which case the remaining arguments are alternating keyword/value pairs, with the same keywords being permitted as at the creation of the widget.

A widget is created by means of a widget constructor, of which there are currently 15, each of them appearing as the title of a section in Widgets. They live in the "TK" package, and for the moment we will assume we have switched to this package. Thus for example button is such a widget constructor function. Of course this is lisp, and you can make your own widget constructors, but when you do so it is a good idea to follow the standard argument patterns that are outlined in this section.

(button '.hello)
==> .HELLO

creates a widget whose name is .hello. There is a parent child hierarchy among widgets which is implicit in the name used for the widget. This is much like the pathname structure on a Unix or Dos file system, except that '.' is used as the separator rather than a / or \. For this reason the widget instances are sometimes referred to as pathnames. A child of the parent widget .hello might be called .hello.joe, and a child of this last might be .hello.joe.bar. The parent of everyone is called . . Multiple top level windows are created using the toplevel command (see toplevel).

The widget constructor functions take keyword and value pairs, which allow you to specify attributes at the time of creation:

(button '.hello :text "Hello World" :width 20)
==>.HELLO

indicating that we want the text in the button window to be Hello World and the width of the window to be 20 characters wide. Other types of windows allow specification in centimeters 2c, or in inches (2i) or in millimeters 2m or in pixels 2. But text windows usually have their dimensions specified as multiples of a character width and height. This latter concept is called a grid.

Once the window has been created, if you want to change the text you do NOT do:

(button '.hello :text "Bye World" :width 20)

This would be in error, because the window .hello already exists. You would either have to first call

(destroy '.hello)

But usually you just want to change an attribute. .hello is actually a function, as we mentioned earlier, and it is this function that you use:

(.hello :configure :text "Bye World")

This would simply change the text, and not change where the window had been placed on the screen (if it had), or how it had been packed into the window hierarchy. Here the argument :configure is called an option, and it specifies which types of keywords can follow it. For example

(.hello :flash)

is also valid, but in this case the :text keyword is not permitted after flash. If it were, then it would mean something else besides what it means in the above. For example one might have defined

(.hello :flash :text "PUSH ME")

so here the same keyword :text would mean something else, eg to flash a subliminal message on the screen.

We often refer to calls to the widget functions as messages. One reason for this is that they actually turn into messages to the graphics process gcltksrv. To actually see these messages you can do

(debugging t).