jtkutils.tcl
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.4.
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.
Author
Jay Sekora
js@aq.org
http://www.aq.org/~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.
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
j:active_window - return or set the most recent active window
j:winfo - manipulate properties associated with windows
j:tlinfo - manipulate properties associated with windows
See Also
jinit.tcl
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'.
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.)
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.
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.
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.
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.
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).
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).
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: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.
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.
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.)
Usage
j:hide_pointer
widget
Argument
widget is the name of the widget whose mouse pointer is to be hid
Description
This procedure hides the mouse pointer of
widget, by setting it to a blank bitmap. It's useful so that the
mouse pointer doesn't obscure text while the user is typing.
It's called automatically by the standard
jstools bindings libraries for text and entry widgets, but you can
use it for other purposes as well.
Usage
j:show_pointer
widget
Argument
widget is the name of the widget whose mouse pointer is to be restored
Description
This procedure restores the mouse pointer of
widget to the widget default. Note that that may not be the same
as what it was before
j:hide_pointer was called. This should be called whenever the user moves
the mouse after
j:hide_pointer has been called, so that the user can follow the mouse.
It's called automatically by the standard
jstools bindings libraries for text and entry widgets, but you can
use it for other purposes as well.
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.
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.
Usage
j:active_window
[options]
[w]
Argument
w, if given, is the widget to set active
Option
-class
class
(default
any)
Example
bind Text <FocusIn> {j:active_window %W}
[...]
proc capitalise {} {
set w [j:active_window -class Text]
if {$w == "none"} {
j:alert -text "No active window!"
} else {
set text [string toupper [$w get 1.0 end]]
$w delete 1.0 end
$w insert end $text
}
}
Description
This procedure is used to manage multiwindow or multidocument
applications, where it's important to keep track of which window
is currently active (e.g. so that future commands can be applied
to it).
You should arrange to make a window active with
j:active_window whenever the user starts using it. For a text or entry widget,
this might appropriately be done whenever the widget gains keyboard
focus. For a canvas, you might do this whenever the user clicks
in the canvas.
Any commands that should act upon the currentlyactive window
(rather than being called with a specific window as an argument,
or having a window path hardcoded into them) will use
j:active_window to find out what window to operate on.
If called with an argument
w,
j:active_window records the fact that
w is the current active window (and will remain so until a subsequent
call to
j:active_window). It also records the fact that
w is the current active window of its
class, where that class typically corresponds to the Tk class of the
window (i.e. its type: Text, Entry, Label, etc.) The
class can be specified, however, so theoretically it need not correspond
to a Tk window class.
If called without an argument
w, and without
class specified (or with
class specified as `any'), it returns the name of the current or most recent active window
(of any class). If no window has ever been active, it returns
`none'.
If called with no argument
w, but with
class specified (as something other than `any'), it returns the name of the most recent (or current) active
window of class
class. If no window of class
class has ever been active, it returns `none'.
Usage
j:winfo
w
action
[property]
[value]
Arguments
w is the window whose properties you're querying or setting
action is one of
get,
set,
defined,
unset, or
list
property is an arbitrary property name
value is the value to set
property to, or a default value for
property
Description
This procedure allows you to associate arbitrary properties with
widget names. (For instance, if you have a widget whose contents
can be saved, you might want to associate a filename with it.)
If
action is
set, then widget
w's property named
property is set to
value (and
value is returned).
If
action is
get, then if a property named
property is defined for
w, that property's current value is returned. Otherwise,
value is returned (but
property remains undefined for
w).
If
action is
defined, then this procedure returns
1 (true) if a property named
property is currently defined for
w, and
0 (false) otherwise.
If
action is
unset, than the
w's property named
property is deleted.
If
action is
list, then this procedure returns a (possibly empty) list of all the
properties currently defined for
w.
If
value is omitted, it defaults to the empty string, so `j:winfo .w get foo' will return the empty string if the window
.w doesn't currently have a
foo property associated with it. The same is true of
property, although I don't recommend this except with
list.
Usage
j:tlinfo
w
action
[property]
[value]
Arguments
w is the window whose properties you're querying or setting
action is one of
get,
set,
defined,
unset, or
list
property is an arbitrary property name
value is the value to set
property to, or a default value for
property
Description
This procedure behaves identically to
j:winfo, except that instead of manipulating or querying properties associated
with widget
w, it manipulates or queries properties associated with
w's toplevel widget. In all cases, a statement beginning `j:tlinfo
w
...' should behave identically with the corresponding statement
beginning `j:winfo [winfo toplevel
w]
...'.
The
j:tlinfo command is provided as a convenience, because a multidocument
application may find it easier to treat all the widgets within
the toplevel window that represents a single document as a unit.
Also, you can easily associate information to be used in bindings
to a toplevel with that toplevel. (For instance, in a dialogue
panel a different button might be the default depending on the
state of a panel. You could use
j:tlinfo to record the name of the current default button, for use when
the user presses
Return.)
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.