Class ::tycho::Dialog


Inherits: ::tycho::TopLevel - Source File - Contents: itk_options - public methods - public procs - protected method - protected common
This is a top-level dialog window to which buttons and other widgets are added in the derived classes. It provides a message window that contains an optional bitmap, a message, and a separator. In the derived classes, buttons are added below the separator using the addButton method. For example,
::tycho::Dialog .m -text {A dialog}
.m addButton pushme -text {Push Me} -command \
     {::tycho::post thanks; delete object .m}
.m centerOnScreen
A childsite is provided for additional widgets below the label and above the separator. It is a frame with name $itk_component(childsite).

The window starts out in the withdrawn state. To be visible, it must be mapped using the "wm deiconify" command or the "centerOnScreen" method. The reason for deferring the mapping is to avoid the visually distracting effect of mapping a partial window and then filling it in.

There are a couple of convenience procedures. The new procedure will create and map a window onto the screen. The wait procedure will map a window onto the screen and then wait for it to be dismissed (this is called a modal dialog). If the dialog object sets a result in the common variable commandResult(name), where name is the name of the widget, then that result will be returned. Otherwise, an empty string will be returned.

The design is fashioned somewhat after the DialogShell widget by by Mark L. Ulferts. A major difference is that instead of mapping and unmapping this window, the window is destroyed when it is dismissed.


Itk_options

-bitmap
If a non-null bitmap option is given, insert the bitmap left of the text. Typical values are "error", "warning", "info", "hourglass", or "questhead". The default is a null string, which means no bitmap.
-image
If a non-null image option is given, insert the image left of the text. The value of the option is assumed to be the name of an image that has been created with the Tk "image create" command.
-text
If a non-null text option is given, insert the text in the message. The text will be left justified and filled. If there are newline characters in the text, they become line breaks in the message. If there are more than 30 newline characters in the message, then the message is truncated so that it is reasonably sure to fit on the screen (there is still no guarantee because it will depend on the length of the lines).
-messagefont [::tycho::font
The font to use for "message" displays.

Public constructs

Public Methods

addButton args
Add a button to the set of buttons at the bottom. The arguments are options understood by the Tk button command. The most useful options are -command, which specified the command to execute, -text, which specifies the label in the button, and -width, which specifies the desired width of the button.
default id
Specify the default button (the one invoked by the Return key). This button will have an extra frame around it. It can be specified either by the path name or a unique text (its label) or bitmap name.
execCommand option args
Execute the command given by an option, if it has been defined. The first argument gives the name of the option, including the leading minus sign. For example, several of the derived classes have a -okcommand option, which specifies the command to invoke in response to pressing the "OK" button. This command is invoked as follows, where $obj is the name of the object:
   $obj execCommand -okcommand
The execCommand method sets the commandResult(name) to the value returned by the command executed. Any arguments beyond the option name to use are passed to the command as arguments. The command is executed in the global scope. If you need to access a method in a class derived from Dialog, the following sequence in the constructor will work, for example:
    $obj configure -okcommand "$this mymethod"
    addButton b -text "Push Me" \
            -command "$this execCommand -okcommand"
The "this" variable returns a fully qualified name for the object that includes the namespace context.

This method is public only because it is often invoked by key or mouse bindings.

invoke args
Invoke the command associated with a button. If no argument is specified, then the current default button is invoked. Otherwise, the argument is expected to be a list of buttons to invoke. Each button can be specified either by the path name or a unique text (its label) or bitmap name.

Public Procs

answer value
This procedure simply returns its argument. Used for default commands.
wait instance {autoraise 1}
This procedure maps the named object (which must be a Dialog) to the screen and returns only when that object is destroyed. If the object sets a value in $commandResult($name), then that value is returned. Otherwise, a null string is returned. Normally, once the window is created, any mouse movement or click will raise it. This can be a problem, for example, if the window has menus. If a second argument is given and has value 0, then this auto-raise feature is disabled.
new class instance args
This procedure creates an instance of the named class at the global scope with the given instance name. The window is mapped to the screen. The procedure returns immediately, returning the instance name. A typical call would be:
   ::tycho::Dialog::new YesNoQuery .y -text "Are you sure"
The arguments after the class and instance names are just passed directly to the constructor of the class. The class is assumed to be defined in namespace ::tycho, so the string "::tycho::" is prepended to the class name. If the option -geometry is given, then it specifies the placement of the window. Otherwise, the window is centered on the screen.

Protected constructs

Protected Method

preference mode args
Access the preferences associated with this widget. This method overrides the default method in ::tycho::TWidget to access the "dialogs" preferences, which contains values for most preferences needed by dialog boxes.

Protected Common

commandResult
Modal dialogs should put their return value in this array, with the array index being the name of the instance.

Index of classes



Author: Edward A. Lee
Version: @(#)Dialog.itcl 1.10 12/16/96
Copyright: (c) 1995-1996 The Regents of the University of California.