jmetawidgets.tcl

Introduction

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.

Usage

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.

Credits and Copyright

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.

Overview

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

j:buttonbar

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 natural­language 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 natural­language string database to find the string to display on the button. See jldb.tcl for details of this. If you're not using a natural­language 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.

j:colour_chooser

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 pseudo­widget suitable for choosing colours, which is useful for constructing things like preferences panels. The pseudo­widget has a label on the left­hand 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.

j:variable_entry

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 up­arrow button or pressing the up arrow on the keyboard will go up (back) in the history list. Clicking the down­arrow 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

Bugs and Misfeatures