jprompts.tcl
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 recentlyused values.
This document describes
jprompts.tcl version 8.0/4.5.
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.
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.
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
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 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. Clicking the OK button or pressing Return will
append the currentlydisplayed value to the history list.
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.
Singleclicking on a colour in the listbox changes the colour
of the patch, and doubleclicking 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)
hardwired list of colours.
This procedure also works if you call it
j:prompt_color_name.
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 24bit 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.
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.
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 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. Clicking the OK button or pressing Return will
append the currentlydisplayed value to the history list.
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 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. Clicking the OK button or pressing Return will
append the currentlydisplayed value to the history list.
Bugs and Limitations
- It would be nice to be able to use HSV mode to select colours.
I don't include that part of Sam's code because I had trouble
making it work reliably.
-
j:prompt_font should let you specify all the font attributes Tk knows about,
and there should be a facility for returning arbitrary font names
(like XLFD names). It should also have a preview ability.
- There should be a mechanism for passing defaults to
j:prompt_font.
- You should be able to specify the size, position, and directory
of a history list you're using.
- All these procedures should support history lists, not just
a few
- The history mechanism and the bindings mechanism should talk
to each other, so that (for instance) if I'm using Emacs bindings
Control-p should do the same thing as the up arrow on the keyboard.
Future Directions
-
j:prompt_tcl (and possibly
j:prompt_unix) should set up some variables to refer to things like the current
window and the current application name. It's hard to do this
in a sufficiently general fashion, though.