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 {::tycho::inform {You said yes!}} \
    -nocommand {::tycho::inform {Then how did you click on the No button?}}
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 must make the dialog modal using the wait procedure of the Dialog class. For example,
::tycho::YesNoQuery .z -text {Are you awake?}
if [::tycho::Dialog::wait .z] {
    ::tycho::inform {You said yes!}
} {
    ::tycho::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:

::tycho::YesNoQuery .z -text {Are you awake?} \
         -yescommand {set y {yes}} \
         -nocommand {set y {no}}
::tycho::Dialog::wait .z
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. A simple workaround is to use the Tcl format command, as follows:
::tycho::YesNoQuery .z -text {Are you awake?} \
        -yescommand {format yes} \
        -nocommand {format no}
::tycho::Dialog::wait .z

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:

::tycho::YesNoCancel .z -text {Are you awake?}
::tycho::Dialog::wait .z
By default, the cancel button returns -1, unless you specify something different withe the -cancelcommand option. Similarly, by default, the Yes button returns 1 and the No button 0.

Query Class

The Query class opens a dialog box with one or more text entry widgets widgets and/or radio button widgets. It is used by the "query" and "queryinfo" procedures, which provide simpler interfaces. You can also create instances of it directly.

The actions taken in response to the OK and Cancel buttons are given by the -okcommand and -cancelcommand options. By default, both buttons destroy the object. In addition, if you use the class as a modal dialog using wait, then the OK button returns the user responses as a list and the Cancel button returns a null string. After either command is executed, the widget is destroyed.

The Query class creates a dialog box with any of several types of interactions with the user. Text entry boxes can be created using the line method, as shown here:

::tycho::Query .bb -okcommand {::tycho::inform [.bb get]}
.bb line month {Enter Month} Jan
.bb line day {Enter Day} Mon

Here, a non-modal dialog is created, and the result of the dialog is retrieved by the get method and posted by the inform command. The line method takes three arguments, a tag, a label, and a default string.

The get method, invoked above on clicking the OK button, returns an indexed list of entries. A modal dialog can be created as well, and will return the values in the same form as the get method. For example,

::tycho::Query .bb
.bb line text {Enter Something} {foo bar}
::tycho::Dialog::wait .bb

Notice that it was no longer necessary to specify a -okcommand option.

The list returned by the get method has the form {tag value tag value ...}. This form can be used to set the contents of an array using array set, providing a very simple way to access multiple responses.

Additional arguments can be supplied to the line method, which case they are just passed to the Tk entry widget. For example,

::tycho::Query .bb
.bb line a {password} {} -show *
::tycho::Dialog::wait .bb
This causes the entry box to display the character "*" rather than whatever you type. This is useful, for example, to query the user for a password.

Another method allows you to create multi-line text edit boxes, as in the following example:

::tycho::Query .bb
.bb lines a {Multi-line entry:} "multi-line\ndefault" 4
.bb centerOnScreen

Now the query will have four lines. An Edit widget is used, providing an emacs-like text editor. Note that the OK button is no longer triggered by <Return>. It can now be triggered by <Meta-Return>. This is because in a multi-line entry box, <Return> moves the insertion cursor to a new line.

The radio method puts radio buttons into the dialog. For example, assuming you have not dismissed the Query that you created above (if you have, then just recreate it),

.bb radio selmonth {Select Month} {Jan Feb March} Jan
.bb radio selday {Select Day} {Mon Tue Wed Thu Fri} Mon

The arguments are a name for the bank of buttons, a label, the list of possible values, and the default selection.

In simple queries, the Tab key moves the focus from one query entry to the next. When there are multi-line queries in a Query object, then instead of Tab, Control-Tab moves the insertion cursor from query to query. Within a radio button, either Tab or Control-Tab moves the focus from button to button. The Space key selects the current button.

It is also possible to have queries that are mediated by some other widget. For example,

::tycho::Query .bb -entrywidth 70
.bb mediated color {Color:} red {::tycho::querycolor {Choose color}}
.bb mediated font {Font:} fixed ::tycho::queryfont
::tycho::Dialog::wait .bb

Here, the query takes the form of a pushbutton. Pushing this button invokes another widget (in this case the ColorBrowser or FontBrowser), which mediates the selection of a value.

It is also possible to present an option menu to the user. For example,

::tycho::Query .bb
.bb choice drink {Drink:} {Coke Snapple Lemmonade} Coke
.bb choice chips {Chips:} {None Potato Plantain} None
::tycho::Dialog::wait .bb 0

Here, the query consists of a menu button. Pushing this button causes a pop-up menu to appear. For technical reasons, the second argument (0) to the the ::tycho::Dialog::wait procedure is needed. This second argument disables the auto-raise feature that modal dialogs have by default. Unfortunately, auto-raise obscures the pop-up menu as soon as it appears.

In all of the above examples, we have first created the Query object, and then added queries to it by invoking its methods. Alternatively, the -queries option specifies the initial list of entry boxes that will appear in the window, and can be used to create an entire dialog all at once. The value of this option should be a list of queries, where each query is a list beginning with a type keyword. This keyword is actually the method name for the Query class. Here is a summary of the arguments associated with each method:

  • choice tag label possibilities default 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, 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 command argument to the choice query is optional.

    The arguments above are explained below:

  • tag: a string that uniquely identifies the query.
  • 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.
  • possibilities: a list of possible choices. These are the labels that appear on each of the radio buttons or in the pop-up menu in the choice query.
  • command: a command to invoke for a mediated query or, in the choice, when the user changes the selection. 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.
  • Note that no two queries in the same dialog box can have the same tag. Here is an example that creates one of each of the types of queries:
    ::tycho::Query .z \
        -queries { \
            {line first {First query:} {Default string}} \
            {lines second {Second query:} {Another default} 4}  \
            {radio third {Third query:} {A B C D} A}  \
            {choice fourth {Fourth query:} {A B C D} A}  \
            {mediated fifth {Fifth entry:} red {::tycho::querycolor Choose}}  \
         } \
        -okcommand {::tycho::inform "Result of a get:\n[.z get]"} \
        -cancelcommand {::tycho::inform "You canceled"}
    

    The disable method disables a query. For instance,

    .z disable first
    
    The query can be re-enabled with enable method, as follows:
    .z enable first
    
    The remove method takes a tag as an argument and simply removes the corresponding query.
    .z remove first
    

    The get method may also specify a particular tag.

    ::tycho::inform [.z get second]
    

    The clear method clears all entries (or a single entry, if a tag argument is given).

    .z clear
    
    In the case of radio button and mediated entries, "clear" means to reset to the default value.

    The insert method inserts a string into the specified entry.

    .z insert second {An inserted string. }
    

    You may delete this window by clicking on the OK button.

    The class is derived from Dialog, 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::Query .aa \
        -bitmap questhead \
        -text {Enter modified values, then click OK} \
        -queries {{line first {First entry:} {Default string}} \
            {line second {Second entry:} {Another default}}}  \
        -title "Query Widget" \
        -okcommand {::tycho::inform "Result of a get: [.aa get]"} \
        -cancelcommand {::tycho::inform "You canceled"}
    

    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" method of the base class. For example,

    ::tycho::Dialog::new \
        Query .z -queries {{line n {Enter value} {default}}}
    

    FileBrowser Class

    Another dialog box is a file browser. Consider the example:
    ::tycho::FileBrowser .f -command "::tycho::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 "::tycho::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 wait:

    ::tycho::FileBrowser .w
    ::tycho::Dialog::wait .w
    

    ColorBrowser Class

    A related dialog box is a color browser. Consider the example:
    ::tycho::ColorBrowser .f -command "::tycho::inform"
    wm deiconify .f
    
    The -command option again specifies a command to execute once the user has selected a color name, as above. Refer to the user-level documentation for further information about the Color browser.

    Note that you should not directly use color names. Instead, you should pass them to the procedure ::tycho::color, as in the following example:

    ::tycho::ColorBrowser .f
    ::tycho::color [::tycho::Dialog::wait .f]
    

    Note that, as usual, you can get a modal color browser using wait, as done above.

    Tycho Home Page


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