NAME

Dialog - Dialog abstraction with custom buttons

SYNOPSIS

Dialog pathName ?option value...?

DESCRIPTION

OPTIONS from ButtonBox

  -background or -bg

  -homogeneous

  -padx

  -pady

  -spacing

WIDGET-SPECIFIC OPTIONS

  -anchor

  -bitmap

  -cancel

  -class

  -default

  -geometry

  -image

  -modal

  -parent

  -place

  -separator

  -side

  -state

  -title

  -transient

WIDGET COMMAND

pathName add ?option value ...?

pathName cget option

pathName configure ?option? ?value option value ...?

pathName draw ?focus?

pathName enddialog result

pathName getframe

pathName invoke index

pathName itemcget index option

pathName itemconfigure index ?option? ?value option value ...?

pathName setfocus index

pathName withdraw

EXAMPLES

NAME

SYNOPSIS

DESCRIPTION

The Dialog widget provides a versatile framework for building dialogs. It is the basis of all the other Slab dialogs, i.e. MessageDlg, ProgressDlg, SelectColor, and SelectFont, and it helps the developer to construct a custom dialog by taking care of common elements such as a button bar, focus, grab, and GUI events on the dialog window and its buttons.

The Dialog includes a Slab ButtonBox, which displays the Slab Buttons specified for it.

The Dialog also provides a "user window", which is a Tk frame into which the developer can map any windows that are needed to create a custom dialog. The customization can be done after the Slab Dialog is created but before it is mapped by the draw widget command.

Some widget commands take index as an argument, indicating the Button to which the command applies. This index is the same as specified for the equivalent ButtonBox command:

number

Specifies the Button numerically, where 0 corresponds to the first added Button, 1 to the next, and so on.

end or last

Indicates the last Button added.

default

Indicates the default Button.

WIDGET-SPECIFIC OPTIONS

"Read-only" options must be supplied as arguments to the Dialog command. The values of these options cannot be changed later by calling the configure widget command.

-anchor (read-only)

Specifies the anchor point of the ButtonBox. Must be one of w, e, n, s or c. If the -side option is set to top or bottom, then the -anchor values n, s and c have the same effect. If the -side option is set to left or right, then the -anchor values w, e and c have the same effect.

-bitmap (read-only)

Specifies a bitmap to display at the left of the user frame. The -image option overrides -bitmap.

-cancel

Specifies the number of the cancel Button of the Dialog. When the user presses either the <Escape> key or the Dialog window's "Close" gadget, this Button is invoked.
If set to -1, the <Escape> key does not invoke anything. The window's "Close" gadget closes the Dialog in this case and returns -1.

-class (read-only)

The widget class, Dialog.

-default

Specifies the number of the default Button of the Dialog. When the user presses the <Return> key in the Dialog, this Button is invoked.

-geometry

Set the geometry used when method draw is called. See wm geometry for a parameter description.

-image (read-only)

Specifies an image to display at the left of the user frame. The -image option overrides -bitmap.

-modal

This option must be none, local or global. The value of this option specifies the grab mode of the dialog and how the "pathName draw" command works.

-parent

A Tk window path. A Dialog with -transient true will be transient with respect to this value or, if no value is supplied, to the toplevel window of the Dialog's Tk parent. The value of -parent may also be used by the widget command draw when mapping the dialog. See draw for details.

-place

Specifies where to draw the Dialog toplevel relative to the dialog's parent window. Must be one of none, center, left, right, above, below. The default value of place is center.

-separator (read-only)

(Boolean value). If and only if true, a separator is drawn between the user frame and the ButtonBox.

-side (read-only)

Specifies where to draw the ButtonBox relative to the user frame. Must be one of top, left, bottom or right.

-state

The widget state, one of normal, disabled, or active.

-title

Title of the Dialog toplevel.

-transient (read-only)

(Boolean value). If and only if true, the Dialog toplevel will be a transient window. Default value of -transient is true.

WIDGET COMMAND

pathName add ?option value ...?

Add a Button to the ButtonBox of the Dialog window. The available options are those of a Slab Button. A typical call will supply the option -name to label the Button.

(By default, the -command option of the Button is given the value pathName enddialog index where index is the number of the new Button: this ensures that when the Dialog is closed by clicking a Button, the correct value is returned.)

pathName cget option

Returns the current value of the configuration option given by option. The argument option may have any of the values accepted by the creation command Dialog.

pathName configure ?option? ?value option value ...?

Queries or modifies the configuration options of the widget. If no option is specified, returns a list describing all the available options for pathName. If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The arguments option may have any of the values accepted by the creation command Dialog. Read-only options cannot be modified.

pathName draw ?focus? ?overrideredirect? ?geometry?

This command draws the Dialog, and sets the grab to it if the value of the -modal option is not none. If the -modal option is set to none, the command immediately returns an empty string. In all other cases, the command returns when the enddialog widget command is called or when the Dialog is closed. The return value is the result argument of the enddialog widget command; see the -cancel option for the result if the Dialog is closed without a Button press.

Command arguments are all optional, and are:

focus - if supplied, this must be a Tk window path, or (the default) the empty string

Initial focus is set on this window, which is typically one of the Dialog's Buttons. If the argument is not supplied, focus is set to the default Button referenced by the -default option, or to the toplevel of the Dialog if no default Button has been set.

overrideredirect - boolean, default false

If and only if boolean true, the Dialog will be ignored by the window manager and drawn without window decorations (see the Tk command wm overrideredirect).

geometry - if supplied, this must be a value suitable as an argument to wm geometry, or (the default) the empty string

The geometry used to draw the dialog is selected with this order of priority:

• the value of the option -geometry, if this is not the empty string
• the argument geometry of the draw command, if this is not the empty string
• if option -place is not none, and option -parent is a valid Tk window path, Slab::place computes the geometry using the value of -place relative to the window -parent
• if option -place is not none, and option -parent is not supplied (or is not a valid window), Slab::place computes the geometry using the value of -place relative to the screen
• if option -place is none, then no value is set for the wm geometry: the window manager decides the position and size of the Dialog.

pathName enddialog result

This command is typically called within the -command of a Button. In a modal dialog (option -modal not equal to none), this makes the draw command return and deliver the return value result.

pathName getframe

Returns the Tk window path of the "user window".

pathName invoke index

Invokes the Button given by index.

pathName itemcget index option

Returns the current value of a configuration option for the Button with index index. The argument option may have any of the values accepted by the "Button creation" widget command add.

pathName itemconfigure index ?option? ?value option value ...?

This command is similar to the configure command, except that it applies to the options for an individual Button, whereas configure applies to the options for the widget as a whole. Arguments option may have any of the values accepted by the "Button creation" widget command add. If values are specified, options are modified as indicated in the command and the command returns an empty string. If no options are specified, the command returns a list describing the current options for the Button.

pathName setfocus index

Sets the focus to the Button given by index.

pathName withdraw

Call this command to hide the Dialog box.

EXAMPLES

A simple dialog box to ask whether to proceed with an installation:

Dialog .box -cancel 0 -default 1 -parent . -title Installer -separator 1
.box add -name Cancel
.box add -name OK
set middle [.box getframe]
label $middle.lab -text {Proceed with Installation?}
pack $middle.lab -expand 1 -fill both
set result [.box draw]
destroy .box

The resulting dialog, on the X11 windowing system, including window manager decorations: