# 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.0/4.0.

## 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@calumet.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.

``