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?}}
wm deiconify .y
.y focusin
Typing y or n will invoke the corresponding button. Typing Return (or Enter on some keyboards) will invoke the Yes button. Typing Escape will dismiss the dialog without invoking either button.

The options -yescommand and -nocommand specify scripts to be executed in response to these buttons. If you do not specify these options, nothing interesting will happen when you click on the buttons. This is because 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?}
set response [::tycho::Dialog::wait .z]
if {$response == 1} {
    ::tycho::inform {You said yes!}
} elseif {$response == 0} {
    ::tycho::inform {Then how did you click on the No button?}
}
Notice that the response may in fact be a null string. This occurs if the user types Escape without invoking either 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 Yesbutton returns 1 and the No button 0. As usual, typing Escape dismisses the window without invoking any of the buttons, so the above will return an empty string in this case.

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
wm deiconify .bb

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. Note that typing Return will no longer invoke the OK button while the focus is in the multi-line text widget. Typing Control+Tab will move the focus to the next item in the query box (a simple Tab simply inserts a tab in the text window. Then Return works again to invoke OK.

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
::tycho::Dialog::wait .bb

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

Within a radio button, 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 Lemonade} 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
  • 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"}
    wm deiconify .z
    

    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"}
    wm deiconify .aa
    

    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 .cc -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 dialog. 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-1998, The Regents of the University of California. All rights reserved.
    Last updated: 06/08/98, comments to: eal@eecs.berkeley.edu