Title

jtkutils.tcl

Introduction

The jtkutils.tcl library is distributed as part of the jstools package. It consists of procedures useful in constructing dialogue boxes and laying out user­interface components, convenience procedures for working with the selection, procedures to help support session management, and procedures for setting fonts in a fault­tolerant way.

This document describes jtkutils.tcl version 4.0/4.0.

Usage

Accessing the Library

In order to use the jtkutils.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

Credits and Copyright

Author

Jay Sekora

js@calumet.org

http://shore.net/~js/

Copyright

The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview

Procedures

j:wm_client - set the session client hostname

j:wm_command - set the session client command

j:new_toplevel - create a new toplevel, avoiding name conflicts

j:selection_if_any - return selection if it exists, else {}

j:no_selection - true if there is no selection

j:beep - flash a widget and/or ring the X display's bell

j:default_button - bind Return to default button

j:cancel_button - set up bindings for cancel button

j:tab_ring - specify order for tab traversal of entry widgets

j:dialogue - position a toplevel near center of screen

j:dialog - alias for j:dialogue

j:rule - return a frame widget suitable for use as a divider

j:filler - return a frame widget suitable for use as a spacer

j:configure_font - configure a widget with font from list, or default

j:configure_tag_font - configure a text tag with font from list, or default

See Also

jinit.tcl

j:wm_client

Usage

j:wm_client [hostname]

Arguments

hostname, if specified, is the machine to claim to be running on

Description

This procedure is normally called without arguments, in which case it tries to determine the name of the machine the current application is running on, and sets that as the X `client' machine, for the use of session managers. If hostname is specified, that will be set as the X client hostname.

This procedure tries to determine the hostname by looking in several places for the Unix hostname(1) command; if it can't find hostname(1), it will set the client hostname to `localhost'.

j:wm_command

Usage

j:wm_command [command]

Arguments

command, if specified, is the command line to register

Example

global argv0

j:wm_command [list $argv0 +$line $filename]

Description

This procedure is normally called without arguments, in which case it sets the X client command (used by session managers) to the command line that was used to invoke the current application, as best it can determine, using the Tcl variables argv0 and argv. (For details of these variables, see the wish(1) or tclsh(1) manual pages.) If command is specified, it will be used instead. (It should have proper Tcl list structure, so the list(n) or concat(n) command is likely to be useful.)

j:new_toplevel

Usage

j:new_toplevel prefix [args]

Arguments

prefix will be the initial part of the new toplevel widget

args, if any, are configuration options for the new toplevel

Example

set tl [j:new_toplevel .notice]

message $tl.msg -text $text

button $tl.b -text OK -command [list destroy $tl]

pack $tl.msg $tl.b -fill x

Description

This procedure creates a new toplevel widget with a name that won't conflict with any existing widget. It does this by taking the prefix (which must start with a period) and adding the lowest possible integer suffix to it that will not produce the name of a widget that already exists. For instance, if you specify prefix as .more and no window named .more0 already exists, the new window will be named more0. The name of the created window is returned.

j:selection_if_any

Usage

j:selection_if_any

Description

This convenience procedure, from R. James Noble <kjx@comp.vuw.ac.nz>, returns the selection if there is one, and the empty string {} otherwise.

j:no_selection

Description

This procedure returns true (1) if there is no current selection, and false (0) if there is a valid selection. It's useful as a test before doing selection get or manipulating the selection. Note that j:no_selection will be true if there's an X selection, even if it's not in the current application.

j:beep

Usage

j:beep widget

Argument

widget is the widget to call the user's attention to

Description

This procedure tries to get the user's attention, either by briefly flashes a widget, reversing the foreground and background colours (if J_PREFS(visiblebell) is true), or by ringing the X display's bell (if J_PREFS(audiblebell) is true), or both.

Ideally, the widget argument should name a widget with distinct background and foreground colours for the visible bell to work; j:beep tries to do something reasonable with widgets that don't have both a foreground and a background colour, but it won't work in every case.

The X bell can't be rung in versions of Tk prior to 4.0, so J_PREFS(audiblebell) has no effect under versions 3.6 and earlier.

j:default_button

Usage

j:default_button button widget...

Arguments

button is the path name of the Cancel button

widget... are a series of widgets that can get keyboard focus, to bind to

Example

j:default_button .buttons.call .name.entry .phone.entry

Description

This procedure arranges a keyboard shortcut for pressing a default button. The widget arguments are widgets that might get the keyboard focus. For each widget, the Return key is bound so as to invoke button. Typically, you'd create a panel with a default button, and possibly some entry and/or text widgets, and invoke j:default_button listing all the entry and text widgets. You can also use focus to give the keyboard focus to the toplevel widget, and specify it instead (or as well).

j:cancel_button

Usage

j:cancel_button button widget...

Arguments

button is the path name of the Cancel button

widget... are a series of widgets that can get keyboard focus, to bind to

Description

This procedure arranges several keyboard shortcuts for pressing a Cancel button. The widget arguments are widgets that might get the keyboard focus. For each widget, Control-c, Control-g, Meta-q, Meta-period, and Escape are bound so as to invoke button. Typically, you'd create a panel with a Cancel button and some entry and/or text widgets, and invoke j:cancel_button listing all the entry and text widgets. You can also use focus to give the keyboard focus to the toplevel widget, and specify it instead (or as well).

j:tab_ring

Usage

j:tab_ring widget...

Arguments

widget... are a series of (typically entry) widgets to chain together

Description

Under Tk 3.6 and earlier, this procedure lets you link several widgets, typically entry widgets, so that the Tab key can be used to move the keyboard focus back and forth between them. Under Tk 4.0 and later, it does nothing.

For each widget in the list, the Tab key is bound so as to move the keyboard focus to the next widget in the list, and Shift-Tab is bound so as to move it to the previous widget. (The last widget in the list and the first are similarly linked.) This lets you support keyboard traversal of forms made up of entry or text widgets. (Theoretically, you could also use it to support keyboard control of other widgets as well, but since there's no visible indication of what wiidget has the focus in Tk 3.6 and earlier, this wouldn't be terribly clear, and in Tk 4.0 this procedure isn't necessary.)

j:dialogue

j:dialog

Usage

j:dialogue widget

Argument

widget is the toplevel widget to position

Description

This (probably misnamed) procedure simply positions a toplevel, widget, near the middle of the screen (centred halfway across, and one­third down from the top), and raises it. It only takes effect if the global variable J_PREFS(autoposition) is true (1); otherwise it lets the window manager position it. (A window manager will typically ask the user to position the new window with the mouse.) If you use j:read_standard_prefs (in jprefs.tcl) and j:global_pref_panel (in jprefpanel.tcl), your users can choose whether they want dialogue panels auto­positioned or not.

You can invoke this procedure as either j:dialogue or j:dialog.

j:rule

Usage

j:rule parent [args]

Argument

parent is the widget you're packing the rule into

Options

args are options to configure the appearance of the returned frame

Examples

pack \

$w.textbg \

[j:rule $w] \

$w.textfg \

[j:rule $w] \

$w.textsb \

[j:rule $w] \

$w.textsf \

-in $w -fill x

pack \

.foo.title \

[j:rule .foo -height 1 -background black] \

.foo.buttons \

-in .foo -side top -fill x -expand yes

Description

This procedure returns a thin sunken frame intended to be used as a `rule' - a narrow groove between other widgets. You typically use it in brackets directly in a pack command. By default, the frame returned is a 2x2 pixel square, but you typically specify either `-fill x' or `-fill y' when you pack it so that it gets stretched in one direction or the other. If you specify any args, they're used to configure the frame, so you can change its size (or other aspects of its appearance - you can make it raised instead of sunken, for instance, or change its color). You can also control its behaviour by arguments to the pack command.

j:filler

Usage

j:filler parent [args]

Argument

parent is the widget you're packing the filler into

Options

args are options to configure the appearance of the returned frame

Examples

pack [j:filler $w] $w.name [j:filler $w] $w.rgb \

[j:filler $w] $w.patch [j:filler $w] \

-in $w -side right

pack \

.foo.title \

[j:filler .foo -height 25] \

.foo.buttons \

-in .foo -side top -fill x -expand yes

Description

This procedure returns a frame intended to be used as a `filler' - as padding to control the spacing between other widgets. You typically use it in brackets directly in a pack command. By default, the frame returned is a 10x10 pixel square. If you specify any args, they're used to configure the frame, so you can change its size. You can also control its behaviour by arguments to the pack command.

When its created, the filler is lowered to the bottom of the stacking order. This means that it will be below its parent, so if it's a different colour than its parent, it won't create a gap. (The simple way of thinking about this, without worrying about stacking orders and packing, is that the filler is invisible and the parent shows through.)

j:configure_font

Usage

j:configure_font widget fontlist

Arguments

widget is the widget whose font you want to set

fontlist is a list of fonts (possibly just one) to try to use (or `default')

Examples

j:configure_font .t {

-*-lucidabright-medium-r-normal--*-100-75-75-*-100-*-*

-*-lucidabright-medium-r-normal--*-100-*-*-*-*-*-*

-*-times-medium-r-normal--*-100-*-*-*-*-*-*

flexible

}

j:configure_font .t {

koi9

default

fixed

}

Description

This is a general way to set fonts when you're not sure what fonts are available on the user's system. It goes through the list of fonts, and tries to set widget's font option to each font in turn, until it finds one that's available. If a font name is `default', then at that point in the list (i.e., if no previous fonts have succeeded), it'll try to set the widget's font to whatever it's normal X default font would be, using the X defaults mechanism. (Note that it is possible for this to fail, if the user has specfied a default font that doesn't exist on hir X server.) If a font in the list is empty (as will be the case if you specify fontlist as {}), it'll try to set the font to 12­point Courier.

If no font in fontlist can be found, the font of widget is unchanged.

Generally you want to put unusual fonts that your users might not have available at the beginning of the list, and end the list with fonts you're certain your users will have, like fixed or flexible.

j:configure_tag_font

Usage

j:configure_tag_font widget tag fontlist

Arguments

widget is the text widget that tag is in

tag is the tag whose font you want to set

fontlist is a list of fonts (possibly just one) to try to use (or `default')

Example

j:configure_tag_font .t bold {

-*-garamond-bold-r-normal--*-120-*

-*-garamond-demibold-r-normal--*-120-*

-*-times-bold-r-normal--*-120-*

-*-*-bold-r-normal--*-120-*

-*-*-bold-r-*--*-120-*

}

Description

This procedure is very similar to j:configure_font, but instead of setting the font of the entire widget, it sets the font for the particular tag tag in the text widget widget. See j:configure_font for a description of how fontlist is used.

Bugs and Misfeatures

* It's unfortunate to have to hardwire Shift-Tab to Backtab in j:tab_ring, but there doesn't seem to be a <Backtab> X11 keysym.

Future Directions

* j:tab_ring is essentially obsolete in Tk 4.0, since its functionality is provided by default Tk bindings. When I stop supporting Tk 3.6, it will no longer do anything.