jprompts.tcl

Introduction

The jprompts.tcl library is distributed as part of the jstools package. It provides procedures for asking the user for information of various kinds. (Two of the procedures, j:prompt_tcl and j:prompt_unix, actually do something with the information; the others just return it.)

Three of the procedures (j:prompt, j:prompt_tcl, and j:prompt_unix) support the history mechanism provided by jhistory.tcl, so your users don't have to retype recently­used values.

This document describes jprompts.tcl version 8.0/4.5.

Usage

Accessing the Library

In order to use the jprompts.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/


Thanks

j:prompt_colour_rgb is an eviscerated version of selcol.tcl by Sam Shen <sls@aero.org>, which also lets you choose HSV values.

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:prompt - prompt the user for information
j:prompt_tcl - prompt for a Tcl command and execute it
j:prompt_unix - prompt for a Unix command and execute it
j:prompt_colour_name - prompt for a colour name
j:prompt_colour_rgb - prompt for a colour RGB value
j:prompt_font - prompt for a font

j:prompt

Usage

j:prompt [options]

Options

-text text (localisable, default Enter a value:)
-default default (default {})
-cancelvalue cancel (default {})
-file bool (default 0)
-show char (default {})
-title title (localisable, default Prompt)
-history history (default {})

Example

set new_name [j:prompt \
-text "Enter a new name for $file." -file 1]
if {$new_name != ""} {
exec mv $file $new_name
}

Description


This procedure creates a panel that asks the user to type in some information. The panel will have a message widget displaying text, an entry whose initial contents are default, and three buttons labelled OK, Clear, and Cancel. Clicking OK (or pressing Return) will return the current contents of the entry; clicking Cancel will return the value of cancel (the null string by default). Clicking Clear will delete the current contents of the entry, which is handy when the user wants to paste something else.

If -file 1 is specified, then pressing the Tab key in the entry widget will do filename completion using j:expand_filename in jprefixmatch.tcl. Note that j:fs in jfs.tcl may often be a better choice when you want to ask the user for a filename.

If char is specified, and char is not an empty string, then the entry will not display characters typed; the first character of char will be displayed in their place. This is useful for requesting passwords. (Warning: This doesn't work under versions of Tk prior to 4.0.)

If title is specified, it will be the title of the panel, for use by the window manager.

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. Clicking the OK button or pressing Return will append the currently­displayed value to the history list.

j:prompt_colour_name

Usage


j:prompt_colour_name [options]

Options


-prompt prompt (localisable, default Choose a colour:)
-title title (localisable, default Colour Name Selector)
-default default (default magenta)

Description


This procedure creates a panel that asks the user to choose a colour by name from a listbox. At the top of the panel is a label displaying prompt; to the left is a listbox with colour names taken from the file /usr/lib/X11/rgb.txt (and a scrollbar), in the lower right is an OK button, and on the right is a large patch of the current colour.

Single­clicking on a colour in the listbox changes the colour of the patch, and double­clicking on a colour name or clicking OK dismisses the panel and causes j:prompt_colour_name to return the selected colour. If the user clicks OK before selecting a colour, bisque will be returned.

If default is specified (and is a legal colour name), the panel will initially be set for that colour. If default is not specified, the panel defaults to magenta, because that's (a reasonable approximation to) my favourite colour.

If title is specified, it will be the title of the panel, for use by the window manager.

If /usr/lib/X11/rgb.txt doesn't exist, the listbox will contain a short (and arbitrary) hard­wired list of colours.

This procedure also works if you call it j:prompt_color_name.

j:prompt_colour_rgb

Usage


j:prompt_colour_rgb [options]

Options


-prompt prompt (localisable, default Choose a colour:)
-title title (localisable, default RGB Colour Selector)
-default default (default #ff80ff)

Description


This procedure creates a panel that asks the user to choose a colour by adjusting component red, green, and blue values with three sliders. At the top of the panel is a label displaying prompt; to the left are the three sliders, to the right is a patch of the current colour and a small label displaying the current colour in X Windows' hexadecimal notation, and in the bottom right is an OK button. Adjusting the sliders changes the current colour (reflected in the patch on the right), and clicking OK dismisses the panel and causes j:prompt_colour_name to return the current colour.

If default is specified (and is a legal 24­bit RGB colour value in HTML/X11 hexadecimal notation), the panel will initially be set for that colour. If default is not specified, the panel defaults to light purple, because that's my favourite colour.

If title is specified, it will be the title of the panel, for use by the window manager.

This is an eviscerated version of Sam Shen <sls@aero.org>'s selcol.tcl routine, which supports choosing a colour by HSV as well as RGB values.

This procedure also works if you call it j:prompt_color_rgb.

j:prompt_font

Usage


j:prompt_font [options]

Options


-prompt prompt (localisable, default Font:, but currently ignored)

Description


This procedure brings up a panel that lets the user choose a font. The panel has an option menu that lists all the font families available on the system, a small entry widget for the user to type a font size, and checkbuttons for the user to request a bold or italic font.

The interface is a little clumsy at the moment; I hope to improve it in the future.

j:prompt_tcl

Usage


j:prompt_tcl [options]

Option

-history history (default j_tcl)

Description


This procedure pops up a j:prompt panel asking the user for a Tcl command, and evaluates it (in the current context).

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. Clicking the OK button or pressing Return will append the currently­displayed value to the history list.

j:prompt_unix

Usage


j:prompt_unix [options]

Option

-history history (default j_unix)

Description


This procedure pops up a j:prompt panel asking the user for a Unix command, and executes it. If the command produces any output, that is displayed in a separate panel, otherwise an alert box informs the user that there was no output.

Any output to standard error while executing the command will cause the tkerror(n) procedure to be invoked; the default tkerror procedure puts up a dialogue box displaying the error message.

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. Clicking the OK button or pressing Return will append the currently­displayed value to the history list.

Bugs and Limitations

Future Directions