Dialog Procedures

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.

Contents

Modal and Non-Modal Dialogs

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.

Message Procedures

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}
All three of these open modal dialogs. When you click on the above, the dialog boxes appear one at a time, one after another, rather than all at once. The 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}
Note that with the 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.

Yes-No Questions

You can ask the user yes-no questions, getting the response back and taking some action accordingly. The askuser procedure asks a yes-no question:
if [::tycho::askuser "Are you awake?"] {
    ::tycho::inform "You said yes!"
} {
    ::tycho::inform "Then how did you click on the No button?"
}

Getting a File Name

The 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
The single argument is a message to include in the file browser. If a second argument is given (it is optional), then it is the default file name. The returned value is a fully expanded file name. If the user cancels (with the cancel button or the escape key), then a null string is returned.

Selecting a color

The querycolor procedure can be used to query the user for a color name, as in the following example:
::tycho::querycolor {Choose a color} red
The first argument is a message to include in the file browser. The second argument (which is optional) is the initial color choice. The returned value is a color name. If the user cancels (with the cancel button or the escape key), then a null string is returned.

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]

Questions with Textual Answers

You can prompt the user for a typed response with the queryinfo procedure. For example:
::tycho::queryinfo {Enter a string}
The 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}}}
This will return a list of the form {v value w value x value y value z value}. The first query is much like the used by the 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:

  • choice tag label possibilities command
  • line tag label default
  • lines tag label default height
  • radio tag label possibilities default
  • mediated tag label default command
  • In addition, all except choice can accept any number of additional arguments. These arguments are passed to the widget that implements the query (a Tk entry, a Tycho 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:

  • tag: a string that uniquely identifies the query. No two queries in the same dialog box can have the same tag.
  • label: a string that is inserted in the display to the left of the query.
  • default: the initial value of the query.
  • height: the number of lines in a multi-line text query. An Edit widget is used, providing an emacs-like text editor.
  • possibilities: a list of options. These are the labels that appear on each of the radio buttons, or the menu items in the choice pop-up menu.
  • command: a command to invoke for a mediated query or when the user changes the selection in a choice query. Before invoking this command, the current (default) value of the query will be appended to the command, separated by a space. The command should return the new value of the query.
  • 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.

    Tycho Home Page


    Copyright © 1996, The Regents of the University of California. All rights reserved.
    Last updated: 96/12/01, comments to: eal@eecs.berkeley.edu