Introduction to Tk

Tk is concise, powerful, easy to use, well known, and can be run everywhere using Inferno.

All the features of Tk are not included in Inferno. This section provides information about the differences between the Limbo/Tk implementation and Tk 4.0.

Programmers need only deal with the toplevel, namechan, and cmd functions. The mouse and keyboard functions are used by the window manager to deliver mouse and keyboard events into applications.

The Toplevel Function

The toplevel command takes a screen argument and a string containing further options, and it returns a handle that represents a top-level Tk widget. The handle is used as the first argument to the namechan and cmd functions described in this section. The options argument contains Tk option/value pairs, specified in the same manner as options to all Tk widgets. As well as the generic options, toplevel accepts the -x int, -y int and -debug bool options. The -x int and -y int options specify the upper left corner of the toplevel widget, where (0,0) is the top left corner of the screen. The -debug bool option causes a trace of all Tk commands to be printed when the boolean value is true. A typical call to toplevel looks like:

top := tk->toplevel(ctxt.screen, tkargs);

The Cmd Function

After a toplevel widget has been built, the cmd function is used to issue Tk commands. The first argument is the toplevel reference and the second argument is a string which looks a lot like a string that could be given to a Tcl command interpreter. However, the language accepted is not Tcl.

A typical call of the cmd function is:

range := tk->cmd(ed, ".b.t tag nextrange sel 1.0");

Command String Syntax

The command string may contain one or more single commands, separated by semicolons. A semicolon is a single-command separator if it is at 0-nesting level with respect to braces ( { } ) and brackets ( [ ] ), and it is not escaped by a backslash (\). There is also a superquote convention: at any point in the command string a single quote mark means that the entire rest of the string should be treated as one word.

A single command is divided into a number of words. Words are separated by one or more blanks and tabs.

A word beginning with an opening brace ( { ) continues until the balancing closing brace ( } ) is reached. The outer brace characters are stripped. A backslash can be used to escape a brace in this context.

A word beginning with an opening bracket ( [ ) continues until the balancing closing bracket ( ] ) is reached. The enclosed string is then evaluated as if it were a command string, and the resulting value is used as the contents of the word.

Single commands are executed in order until they are all done or an error is encountered. By convention, an error is signaled by a return value starting with an exclamation mark. The return value from cmd is the return value of the first error-producing command or else the return value of the final single command.

To execute a single command, the first word is examined. It can be one of the following:

One of the following widget creating commands:

frame label button checkbutton radiobutton menubutton menu listbox scrollbar text canvas entry scale

: The second word of each of these commands is the name of the widget to be created. The remaining words are option/value pairs.

A widget name (beginning with a period `.') that corresponds to an existing widget. The second word gives the name of a particular widget subcommand and the remaining words are arguments for the subcommand.
A pack, bind, focus, grab, puts, destroy, image, or update command. These are non-widget creating commands. Most are the same as documented for Tk 4.0. The bind command has some differences, and the image command is somewhat more limited.
The send command. This command is used to send a string from Tk along a Limbo channel to a Limbo process. The second word is the name of a Limbo channel (registered with namechan), and the rest of the words are to be sent along that channel.
The variable command. Limbo/Tk does not have general variables the way Tcl does; radio buttons are an exception. The variable command takes the name of a variable defined in a radio button as the second word, and the value of the variable is the result of the command. Also, there is one predefined variable whose value can be retrieved this way: the lasterror variable is set every time a Tk command returns an error. The value is the offending command (possibly truncated) followed by the error return value. The lasterror variable is cleared whenever it is retrieved using the variable command. This allows for a number of Tk commands to be executed without checking error returns each time. A call to the variable command with lasterror at strategic points can make sure that an unexpected error has not occurred.
The cursor command. This command takes a number of option/value pairs to control the appearance and placement of the cursor. Available options are: -x int and -y int, to change the cursor position to align its hotpoint at the given point (in screen coordinates); -bitmap filename or -image imagename to change the appearance of the cursor; and -default 1 to change back to the default appearance of the cursor.

The Namechan Function

The namechan function of the Tk module is used to set up communication between the Tk widgets and Limbo programs. The send command in the Tk world results in a string being sent along a Limbo channel. The namechan function is used to associate a Limbo chan of string with a name that can be used inside Tk. A typical call looks like:

c := chan of string; tk->namechan(top, c, "c"); The main use of named channels and the send command that uses them is to allow Limbo programs to be notified when Tk events happen. For example,

tk->cmd(top, ".m.file.menu add command -label Open..." + " -command {send c open}"); might be used to add an entry to a menu. Whenever the 'Open...' entry is selected, the string 'open' will be sent along the channel associated with name 'c'. The Limbo program should be waiting for such events, with code like:

s := <-c => case s { "open" => do_open(); ... } Because the language accepted by the cmd function has no user-defined functions, no control flow and very few variables, almost all applications need to have some of their logic in Limbo programs.

Interacting with the Window Manager

To make an application that runs well under the Limbo window manager, the programmer must do four things:

Load and initialize a Wmlib module
Call that module's titlebar function
Pack a widget called .Wm_t in the application
Listen on the channel returned by titlebar for window manager commands (such as exit), and either act on them or reflect them back to the Wmlib module using its titlectl function.

Widget Options

In Limbo/Tk, all widget creation commands and all of the cget widget commands accept a common set of generic options in addition to widget-specific options. Except as noted otherwise, the meanings are the same as the options for Tk 4.0. The allowable forms of things like color, dist, and font are a little different in Limbo/Tk. The generic options are as follows:

-activebackground color
-activeforeground color
-actwidth dist
-actheight dist

NOTE:

The -actwidth and -actheight variables are overridden by the packer, but are useful as arguments to cget to retrieve the actual width and height (inside the border) of a widget after packing.

-background color or -bg color
-borderwidth dist or -bd dist 
-font font 
-foreground color or -fg color 
-height dist (Requested height.)
-padx dist
-pady dist
-relief relief
-state normal or -state active or -state disabled

NOTE:

The -state variable is only relevant for some widgets (for example, entry widgets).

-selectbackground color
-selectborderwidth dist
-selectcolor color

NOTE:

The -selectcolor variable is the color of the box in selection menu items.

-selectforeground color -width dist (Requested width) The dist parameters are lengths, expressed as: optional minus sign, then one or more decimal digits (with possible embedded decimal point), then an optional units specifier. The unit specifiers are those of Tk 4.0 (c for centimeters, m for millimeters, i for inches and p for points) plus two additional ones: h for the height of widget's font, and w for the width of the zero in the widget's font.

In Tcl/Tk 4.0, the widgets do not uniformly take -width and -height options; rather, each widget may take either or both options, and if they do, the meaning of bare number (without a unit specifier) varies from widget to widget. For example, in Tk 4.0 -width 25 means 25 characters to an entry widget, but 25 pixels to a canvas widget. In Limbo/Tk, all widgets may have height and width specified, and bare numbers always mean screen pixels.

The color parameters can be color names or RGB values. Only a small set of names are known currently:

black

blue

darkblue

red

yellow

green

white

orange

aqua

fuchia

gray

lime

maroon

navy

olive

purple

teal

`black`	`blue`	`darkblue`	`red`
`yellow`	`green`	`white`	`orange`
`aqua`	`fuchia`	`gray`	`lime`
`maroon`	`navy`	`olive`	`purple`
`teal`

For RGB values, one of the two syntaxes #RGB or #RRGGBB must be used.

The font parameter should be the complete pathname to an Inferno font file, for example, /fonts/pelm/unicode.9.font. Another parameter type like this (not used in any of the generic options) is bitmap. Unlike Tcl/Tk 4.0, bitmap specifications in Limbo/Tk do not give just a 1-bit deep bitmap to be colored with foreground and background. Instead, they give a full-color image (pixmap, in X11 terminology) to be used as is. If bitmap begins with an @, the remaining characters should be a filename of an Inferno image file. If bitmap begins with a <, the remaining characters should be a decimal integer giving a file descriptor number of an open file from which the bitmap can be loaded. Otherwise, bitmap should be the name of a bitmap file in the /icons/tk directory.

Options Not Supported in Limbo Tk

The following options, listed in as Tk 4.0 Options, are not implemented by any Limbo/Tk widget:

-cursor 
-disabledforeground 
-exportselection
-geometry 
-highlightbackground 
-highlightcolor 
-highlightthickness 
-insertbackground 
-insertborderwidth 
-insertofftime 
-insertontime
-insertwidth 
-repeatdelay
-repeatinterval 
-setgrid 
-takefocus 
-textvariable
-troughcolor

Tk Commands

This section lists all of the commands documented in the Tk 4.0 man pages, giving the differences between the behavior specified in those man pages and the behavior implemented in Limbo/Tk.

NOTE:

Many of the Tk 4.0 widgets take 'Standard Options' such as
-insertontime that are not implemented in Limbo/Tk. See Options Not Supported in Limbo Tk.

The characters cannot be specified using X11 names (for example, Return).

Control. This represents the press of the character in the following seqitem with the Control key pressed.

ButtonPress or Button. This represents the pressed state of the mouse button given by the following seqitem, which should be 1, 2, or 3. If there is no following seqitem, this represents the press of any button.

NOTE:

Unlike Tk 4.0, if the mouse is moved with a button pressed, the Button event is delivered in combination with a Motion event as long as the button remains pressed.

ButtonRelease. Like ButtonPress, but representing the release of a button.

Motion. This represents possible motion of the mouse.

Double. This means that any seqitems in the sequence representing button presses must be double-clicked for the sequence to match.

Map. This represents the event of the widget being drawn on the screen, either for the first time or after being de-iconified.

Unmap. This represents the event of the widget being de-iconified.

Enter. This represents the event of the mouse entering the widget from outside.

Leave. This represents the event of the mouse going outside the boundaries of the widget.

FocusIn. This represents the event of the widget getting the keyboard focus.

FocusOut. This represents the event of the widget losing the keyboard focus.

The event sequence can contain any combination of the above seqitems. They are treated as independent events, and if any of the events occur, the sequence matches. You cannot combine Key Presses of more than one key. As for delivery: events will not be combined, except that Motion events may be combined with button presses (possibly doubled).

The binding script argument has % substitution, as specified in Tk 4.0. However, only the following are implemented: %%, %b, %h, %s, %w, %x, %y, %A, %K, %W, %X, and %Y. The %s substitution gives the logical OR of the mouse buttons for mouse events, and the decimal value of the pressed character for key events. The %K substitution gives the pressed character in the form of four hexadecimal digits (not a textual string, as in Tk 4.0). The %A substitution will escape a {, }, or a \, so that it won't confuse the command string parser when used in a bind script.