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 userinterface components, convenience
procedures for working with the selection, procedures to help
support session management, and procedures for setting fonts in
a faulttolerant way.
This document describes
jtkutils.tcl version 4.1/4.2.
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@aq.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 onethird
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 autopositioned
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 12point 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.