[ Home ] [ Authors ] [ Index ] [ Abbreviations ] [ Bindings ]

Dialog Classes

Tycho provides a set of classes for asking the user questions. These can be yes-no questions, questions that require a typed response, or questions that require a file name response.

Contents

YesNoQuery Class

The YesNoQuery class poses a question and offers two buttons, labeled "Yes" and "No". For example:

::tycho::YesNoQuery .y -text {Are you awake?} \
    -yescommand {inform {You said yes!}} \
    -nocommand {inform {Then how did you click on the No button?}}
.y centerOnScreen
The options "-yescommand" and "-nocommand" specify scripts to be executed in response to these buttons. The default scripts simply destroy the window and return 0 or 1, but the return value is lost. To get the return value, you should use the "newModal" procedure. For example,
if [::tycho::DialogWindow::newModal YesNoQuery .z -text {Are you awake?}] {
    inform {You said yes!}
} {
    inform {Then how did you click on the No button?}
}

There is a bit of a technicality with using this capability. Suppose you wish to create a dialog box that returns the strings "yes" or "no" instead of 0 or 1. The -yescommand and -nocommand options specify Tcl scripts, and it is difficult to get a Tcl script to return a value. You could use the "set" command as follows:

set x [
    ::tycho::DialogWindow::newModal YesNoQuery .z -text {Are you awake?} \
         -yescommand {set y {yes}} \
         -nocommand {set y {no}}
]
inform "Your answer was $x"
But this not good coding style. The variable "y" gets set at the global scope, clobbering any previous value the user might have unwisely stored in y. The DialogWindow class provides a procedure "answer" that simply returns its argument precisely for this purpose. Thus, the preferred script is:
set x [
    DialogWindow::newModal YesNoQuery .z -text {Are you awake?} \
        -yescommand {DialogWindow::answer {yes}} \
        -nocommand {DialogWindow::answer {no}}
]
::tycho::inform "Your answer was $x"

YesNoCancel Class

The YesNoCancel class is like the YesNoQuery class, but there is one more button labeled "Cancel" and one more option -cancelcommand. To see an example, execute this:

set x [::tycho::DialogWindow::newModal YesNoCancel .z -text {Are you awake?}]
::tycho::inform "The value returned was $x"
By default, the cancel button returns -1.

EntryQuery Class

The EntryQuery class opens a dialog box with one or more text entry widgets. It is used by the "queryinfo" procedure described above. You can also create instances of it directly. It creates a dialog box with one or more entry widgets, an OK button, and a Cancel button. The actions taken in response to these buttons are given by the -okcommand and -cancelcommand options. By default, the -okcommand just returns the value entered by the user. The -cancelcommand does nothing. After either command is executed, the widget is destroyed. The -queries option specifies the initial list of entry boxes that will appear in the window. The value of this option should be a list of three or four-element lists. The first element of each list is an arbitrary tag used to identify the entry box. The second element is the label to put next to the entry box. The third element is the default string to put into entry box. The optional fourth element specifies the number of text lines that should be allowed in the entry box. This defaults to one. For example,

::tycho::EntryQuery .z \
    -queries {{first {First entry:} {Default string}} \
        {second {Second entry:} {Another default}}}  \
    -entrywidth 60 \
    -okcommand {inform "Result of a get: [.z get]"} \
    -cancelcommand {inform "You canceled"}
.z centerOnScreen
If you click OK, you see the result of the get method for this widget. The get method returns a list of two-element lists. The first element of each list is a tag, and the second element is the value in the corresponding entry box (which will be either the default or a new value entered by the user. Note that the order in which entries are returned is arbitrary.

Alternatively, entry boxes can be added after the EntryQuery object is created using the addQuery method. This method takes three arguments, a tag, a label, and a default string. These serve the same function as the elements passed in a -queries option. The removeQuery method takes a tag as an argument and simply removes the corresponding query. Click again on the above example to create the EntryQuery, if you dismissed it. Then try this example:

.z addQuery third {Third entry:} {Yet another default} 4
Notice that now the query has four lines and that the OK button is no longer triggered by . It can now be triggered by . This is because in a multi-line entry box, moves the insertion cursor to a new line. The removeQuery method takes a tag as an argument and simply removes the corresponding query.
.z removeQuery first
The get method may also specify a particular tag.
::tycho::inform [.z get second]
The clear method clears all defaults (or a single default, if a tag argument is given).
.z clear
The insert method inserts a string into the specified entry.
.z insert third {An inserted string. }
You may delete this window by clicking on the OK button.

The class is derived from DialogWindow, so it has the options -text, -bitmap, and -title, which control the text of the query, a bitmap left of the query, and a window manager title. For example,

::tycho::EntryQuery .aa \
    -bitmap questhead \
    -text {Enter modified values, then click OK} \
    -queries {{first {First entry:} {Default string}} \
        {second {Second entry:} {Another default}}}  \
    -entrywidth 20 \
    -title "EntryQuery Widget" \
    -okcommand {inform "Result of a get: [.aa get]"} \
    -cancelcommand {inform "You canceled"}
.aa centerOnScreen
The order of the -bitmap and -text options relative to the -queries option is important. In most circumstances, you will want them first.

You also have access to the "new" and "newModal" methods of the base class. For example,

::tycho::inform [::tycho::DialogWindow::newModal EntryQuery .z \
    -queries {{onlytag {Enter a value} {default value}}}]

FileBrowser Class

A rather more elaborate dialog box is a file browser. Consider the example:

::tycho::FileBrowser .f -command "inform"
wm deiconify .f
The -command option specifies a command to execute once the user has selected a file name. The file name is appended as an argument to the command before the command is executed. Thus, in this example, if you select a file named "foo" in directory /users/bar/, then the command that is executed will be "inform /users/bar/foo". Refer to the user-level documentation for further information about the file browser.

As usual, you can get a modal file browser using newModal.

::tycho::inform [::tycho::DialogWindow::newModal FileBrowser .w]


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