Tycho provides a set of ordinary procedures, defined in the tycho namespace, that serve as simplified interfaces to the classes used to create messages for the user and ask the user questions. These are explained here.
Messages and dialog boxes used to interact with users can be either modal or non-modal. A modal dialog is one that prevents the user from performing any other action (within the application) until the dialog has been dismissed. A non-modal dialog is one where the user can perform other functions before dealing with the dialog. Both are useful, and most widgets are designed to interact with the user support both.
There is unfortunately a hazard with using modal dialogs within Itcl
objects. Modal dialogs
indirectly call update
, a Tk utility
that processes pending events, including mouse events. If the modal
dialog is is called from within an Itcl object, directly or
indirectly, it is possible (albeit somewhat unlikely) that the
calling object from being deleted during the call. This can happen,
for example, because a user hits a key that triggers a dialog and a key
that dismisses a window in rapid succession.
Because of a
defect in at least some versions of Itcl, this can result
in catastrophic failure of the application (a core dump). In Tycho
objects, the safeEval
method should be used to evaluate
any procedure that opens a modal dialog.
This will prevent the deletion of the calling object during the
calls to "update".
If a modal dialog is created from the top level or from a
Tcl procedure that is not itself called from within an Itcl object,
then there is no cause for worry.
There are three basic modal message procedures:
::tycho::inform {This message is created with the inform command}
::tycho::warn {This message is created with the warn command}
tkerror {This message is created with the tkerror command}
inform
procedure posts a simple
message, the warn
procedure posts
a message with an exclamation point bitmap, and the
tkerror
procedure posts
a message with an error symbol bitmap and a button for requesting
a stack trace. The stack trace will correspond to the most recent error.
You should not use the tkerror
procedure directly, except in very rare
circumstances. Instead, just call the Tcl command error
when
you wish to signal an error. See
Error Handling.
There are also some non-modal mechanisms for posting messages.
"Non-modal" means that execution continues as soon as the
message is posted. Here is one simple way to provide information
to the user:
::tycho::post {This message is created with the post command}
post
procedure
you can leave the message on the screen as long
as you like, and proceed with your work.
Also note that it returns the name of the top-level window created.
if [::tycho::askuser "Are you awake?"] { ::tycho::inform "You said yes!" } { ::tycho::inform "Then how did you click on the No button?" }
queryfilename
procedure
can be used to query the user for a file name, as in the following example:
::tycho::queryfilename {Choose a file name} default
querycolor
procedure
can be used to query the user for a color name, as in the following example:
::tycho::querycolor {Choose a color} red
Note that the returned color name should never be used directly
in Tycho. Colors cannot be reliably used by name since different
installations understand different color names. The name can be passed
to ::tycho::color
to convert the name into a portable
RGB value.
The following example will display the RBG value of the selected color
rather than the color name:
::tycho::color [::tycho::querycolor {Choose a color} red]
queryinfo
procedure.
For example:
::tycho::queryinfo {Enter a string}
queryinfo
procedure opens a dialog box with an
entry box
for the user to enter text. It returns the string that the user
enters, or a null string if the user clicks on the Cancel button
(or enters a null string). This procedure takes one required argument,
a lable, and two additional optional
arguments, a default string, and a width (in characters) for the
entry box. For example,
::tycho::queryinfo {Enter a string} default 10
Much more complicated dialogs are possible using the
query
procedure.
For example, the following call will create a dialog with one of
each of the five kinds of queries:
::tycho::query {title text} { \
{line v {v label} foo} \
{lines w {w label} bar 4} \
{radio x {x label} {A B C} A} \
{choice y {y label} {A B C} A} \
{mediated z {z label} red {::tycho::querycolor Choose}}}
queryinfo
procedure, requesting a single line of text.
The second is similar, except that it has multiple lines
for the textual response. The third is a collection of radio buttons,
or buttons where the user can only select one.
The fourth is a pop-up menu listing the choices.
The last one is a mediated query,
which is a query where the response is created by some other widget.
In this case, the querycolor
procedure is used to
generate the response.
The first argument of query
is the
label for the entire query, and will appear at the top of the query
window. The second argument is the queries, which is actually a
collection of method invocations for the Query
class.
There are currently five relevant methods, shown with their arguments below:
Edit
object,
a set of Tk radio buttons, or a single Tk
button, respectively). These additional arguments can be used to
control the appearance of the query.
The arguments above are explained below:
A third argument can be given to the query
procedure:
the width of the entry box in characters.
It is optional and defaults to 40.