jmetawidgets.tcl
The
jmetawidgets.tcl library is distributed as part of the
jstools package. It consists of procedures to create compound widgets,
including a buttonbar, a colour chooser, and a labelled entry
widget used to set a global variable.
This document describes
jmetawidgets.tcl version 4.1/4.4.
Accessing the Library
In order to use the
jmetawidgets.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:buttonbar - group of command buttons
j:colour_chooser - preference widget for selecting colors
j:variable_entry - labelled entry to set
a
global variable
See Also
j:filler in
jtkutils.tcl
j:rule in
jtkutils.tcl
jldb.tcl
Usage
j:buttonbar
frame
[options]
Argument
frame is the pathname of the new frame widget to create
Options
-default
defaultbutton
(default
(NONE))
-padx
padx
(default
5)
-pady
pady
(default
5)
-orient horizontal|vertical
(default
horizontal)
-buttons
buttonlist
(default
{})
buttonlist is a list of
{name
text
command}... sublists
Example
j:buttonbar .foo.b -default ok -buttons {
{
ok OK {apply_changes; exit 0}
}
{
cancel Cancel {exit 0}
}
}
pack .foo.b -in .foo -side bottom -fill x
Description
This procedure creates a horizontal (by default) row of buttons,
with some spacing between and around them. Each element in
the
buttonlist will create a button with the name
frame.name, the label corresponding to
text in the naturallanguage database, and the command
command. The buttons will be created from right to left, and each
button will be at least eight characters wide (for visual consistency).
The button with the name
default (if any) will be surrounded with a sunken rectangle.
For each button, the string key
text is looked up in the current naturallanguage string database
to find the string to display on the button. See
jldb.tcl for details of this. If you're not using a naturallanguage
string database, you can just use the label you want on the button
here. (However, I strongly recommend using such a database,
because it will make it easy for your application to be localised
for use by speakers of languages other than the one you designed
your application in.)
If given,
padx and
pady specify the space to add around the edges of the group of buttons.
The default is to add five pixels around the group of buttons.
These options do not affect the spacing between buttons..
If
-orient vertical is specified, the buttons will be laid out vertically (starting
at the botton), rather than horizontally.
If you need to do complicated substitution on the commands of
the buttons, you may find it useful to create the buttons with
empty commands and add the commands after creating the buttons
with
frame.name configure -command
command for each button
name. Alternatively,
format(n) can be useful.
You may find
j:default_button and
j:cancel_button (both in
jtkutils.tcl) useful with
j:buttonbar.
Usage
j:colour_chooser
w
[options]
Argument
w is the pathname of the new frame widget to create
Options
-label
label
(localisable, default
Colour:)
-variable
var
(default
j_prefs_colour - not really optional)
Example
pack [j:colour_chooser \
.foo.fg -label "Foreground:" \
-variable APPPREFS(fg)] \
[j:colour_chooser \
.foo.bg -label "Background:" \
-variable APPPREFS(bg)] \
-in .foo -side top -fill x
Description
This procedure creates a pseudowidget suitable for choosing colours,
which is useful for constructing things like preferences panels.
The pseudowidget has a label on the lefthand side, a small
patch of the colour (raised, so the user can see how 3-D effects
will look), and two buttons labelled RGB and Name. The RGB
and Name buttons pop up
j:prompt_colour_rgb and
j:prompt_colour_name panels respectively (both in
jprompts.tcl), allowing the user to choose a colour. The variable
var, which should be a global variable or an element of a global
array, is set to the colour the user chooses. Typically, this
would be an element of an array, so that the routines in
jprefs.tcl can be used to save and restore it.
Usage
j:variable_entry
w
[options]
Argument
w is the pathname of the new frame to create
Options
-label
label
(localisable, default
Value:)
-variable
var
(default
value - not really optional)
-labelwidth
lw
(default
16)
-entrywidth
ew
(default
40)
-labelconfig
lc
(default
{})
-entryconfig
ec
(default
{})
-history
history
(default
{})
Example
toplevel .find
j:variable_entry .find.search \
-label "Search for:" -variable j_find(searchfor)
j:variable_entry .find.replace \
-label "Replace with:" -variable j_find(replacewith)
pack .find.search .find.replace -in .find
Description
This procedure creates a labelled entry linked to a global variable
(or an element in a global array). If
-labelwidth is given, the label to the left of the entry will be
lw characters wide; otherwise it will be 16 characters wide.
If
-entrywidth is given, the entry will be
ew characters wide; otherwise it will be 40 characters wide.
If you wish to configure the label or the entry further (say,
to specify a font), you can specify
-labelconfig or
-entryconfig with a list of configuration options, for instance `-entryconfig {-font 12x24}' or `-labelconfig {-foreground red}'.
The
-variable
var option isn't really optional for practical purposes; it specifies
the global variable that will hold the contents of the entry widget.
If
history is specified (and is not the empty string), it will be used
as the name of a history list (see
jhistory.tcl) associated with the prompt panel. Two buttons with arrows
will be displayed next to the entry field. Clicking the uparrow
button or pressing the up arrow on the keyboard will go up (back)
in the history list. Clicking the downarrow button or pressing
the down arrow on the keyboard will go down (forwards) in the
history list. It's up to the calling procedure to append elements
to the history list, but
j:variable_entry initialises it when the entry is created.
You may find
j:tab_ring (in
jtkutils.tcl) useful with
j:variable_entry.
Future Directions
-
There should be a
j:buttonbar:button procedure to add a button to an existing buttonbar.
-
j:colour_chooser and
j:variable_entry should take more options to control their appearance.
- These procedures should create pseudowidget commands, so you
could say things like `.foo.buttonbar configure -default cancel'.
- Procedures that use global variables shouldn't. They should
use variables in the caller's context, which can be global or
not as the caller sees fit.
Bugs and Misfeatures
- The global entry variable interacts oddly with the history
list in
j:variable_entry.