# 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 2001.02.10.

## 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-2001 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

## Overview

### Procedures

`::jstools::buttonbar` - group of command buttons
`::jstools::colour_chooser` - preference widget for selecting colors
`::jstools::variable_entry` - labelled entry to set `a` global variable

### See Also

`::jstools::filler` in jtkutils.tcl
`::jstools::rule` in jtkutils.tcl
jldb. tcl

## ::jstools::buttonbar

### Usage

`::jstools::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

`::jstools::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 `::jstools::default_button` and `::jstools::cancel_button` (both in jtkutils.tcl) useful with `::jstools::buttonbar`.

## ::jstools::colour_chooser

### Usage

`::jstools::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 [::jstools::colour_chooser \
.foo.fg -label "Foreground:" \
-variable APPPREFS(fg)] \
[::jstools::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 `::jstools::prompt_colour_rgb` and `::jstools::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.

## ::jstools::variable_entry

### Usage

`::jstools::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
::jstools::variable_entry .find.search \
-label "Search for:" -variable j_find(searchfor)
::jstools::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 `::jstools::variable_entry` initialises it when the entry is created.

## Future Directions

##

##

There should be a `::jstools::buttonbar_button` procedure to add a button to an existing buttonbar.
- `::jstools::colour_chooser` and `::jstools::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 `::jstools::variable_entry`.

`
`