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.
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
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?}
}
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
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
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
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
.
As usual, typing Escape
dismisses the window without invoking
any of the buttons, so the above will return an empty string in this
case.
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
*
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
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:
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
enable
method, as follows:
.z enable first
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
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}}}
::tycho::FileBrowser .f -command "::tycho::inform" wm deiconify .f
-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
::tycho::ColorBrowser .f -command "::tycho::inform" wm deiconify .f
-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.