# hwtk::dialog

Create a dialog box.

## Format

hwtk::dialog - pathName ?option value? …

## Description

A dialog box is a transient toplevel window containing a recess area for users to place widgets, and a row of configurable command buttons which include the standard Ok, Apply and Cancel buttons. When the user presses any of the buttons, an assigned callback function is invoked.

## Standard Options

-clientdata
Database name: clientData
Database class: ClientData
Acts as a data storage for a widgets. User can store any data and this will not have any effect on widget property.
-cursor
Database name: cursor
Database class: Cursor
Specifies the mouse cursor to be used for the widget. See Tk_GetCursor and cursors(n) in the Tk reference manual for the legal values. If set to the empty string (the default), the cursor is inherited from the parent widget.
-height
Database name: height
Database class: Height
If specified, the widget’s requested height in pixels.
-width
Database name: width
Database class: Width
Specifies the width of a widget.

## Widget Specific Options

-buttonboxpos
Database name: buttonBoxPos
Database class: Position

The position of the command button toolbar. Valid options are n, s, e, and w. Default position is s.

-destroyonunpost
Database name: destroyonunpost
Database class: DestroyOnUnpost
Specifies whether or not the dialog should be destroyed when unposted. Acceptable values are 1 and 0.
-height
Database name: height
Database class: Height
The height for the dialog. This option is only valid when -propagate is set to 0.The window manager will restrict the dialog’s height to be greater than or equal to the -minheight value.
-minheight
Database name: minheight
Database class: Height
The minimum permissible height for the dialog. For gridded windows the height is specified in grid units; otherwise it is specified in pixel units. The window manager will restrict the dialog’s height to be greater than or equal to the -minheight value.
-minwidth
Database name: minwidth
Database class: Width
The minimum permissible width for the dialog. For gridded windows the width is specified in grid units; otherwise it is specified in pixel units. The window manager will restrict the dialog’s width to be greater than or equal to the -minwidth value.
-modality
Database name: modality
Database class: Modality
This option allows the user to set the modalness of the dialog. Valid options are application, hyperworks, or none. Application locks the application until the user has responded/dismissed the dialog. Hyperworks locks the application, yet still allows for user interaction with the modeling window. None means a non-modal dialog, no interaction locking.
Specifies the amount of extra space to allocate for the dialog, in pixels, in the X (horizontal) direction.
Specifies the amount of extra space to allocate for the dialog, in pixels, in the Y (vertical) direction.
-parent
Database name: parent
Database class: Parent
Makes window the logical parent of the dialog. The dialog is displayed on top of its parent window.
-propogate
Database name: propogate
Database class: Propogate
If propagate has a true boolean value such as 1 or on then propagation is enabled for master. If it has a false boolean value then propagation is disabled for master. Propagation is enabled by default.
-remembergeom
Database name: remembergeom
Database class: Remembergeom
Remembers the geometry and applies it the next time the dialog posted. Geometry remembering is enabled by default.
-separator
Database name: separator
Database class: Separator
Option to show the separator line between the window recess and the command button toolbar. The separator is on by default i.e. the separator option is set to true. Valid values are true and false.
-title
Database name: title
Database class: Title
The title of the dialog which will appear in the title bar of the dialog.
-transient
Database name: transient
Database class: Transient
Make the dialog transient to the specified window. It is an error to attempt to make a dialog a master of itself.
-width
Database name: width
Database class: Width
The width for the dialog. This option is only valid when -propagate is set to 0.The window manager will restrict the dialog’s width to be greater than or equal to the -minheight value.
-x
Database name: x
Database class: X
Specifies the desired x location of the dialog on the screen, in pixels. The value specifies the number of pixels between the left edge of the screen and the left edge of window’s border. If this option is configured after the window is posted, you must force the window to repost by calling $windowname post to update the x geometry. -y Database name: y Database class: Y Specifies the desired y location of the dialog on the screen, in pixels. The value specifies the number of pixels between the top edge of the screen and the top edge of window’s border. If this option is configured after the window is posted, you must force the window to repost by calling$windowname post to update the y geometry.

## Widget Commands

This command adds a new button to the button toolbar in the dialog. The button will by default be added to the last position (rightmost in horizontal toolbar position, bottommost for vertical toolbar position) in the toolbar. If the user wishes to add the button in a different location, they may add the button using the insert command. Options to the add command include -text, -command and -default. The option -text will specify the text to appear on the button. If no -text option is given it will default to the button’s name as given by the first argument after the add command. The -command option specifies the command which is called when the button is invoked and -default may be set to one of normal, active or disabled.
pathName buttoncget index option
This option is used to obtain information about the buttons on the dialog’s toolbar. Information for the standard options for the toolbar can be obtained such as -command, -default and -default. The index is the named index given to the button upon creation.
pathName buttonconfigure index ?arg arg...?
This option is used to configure information about the buttons on the dialog’s toolbar. The standard options for the toolbar can be set such as -command, -default and -text. The index is the named index given to the button upon creation.
pathName buttonlist
Returns a list of buttons which have been added to the dialog by the user.
pathName cget option
Returns the current value of the configuration option given by option.
pathName component ?name?
Returns the path of a given component of the dialog widget. Options for the component command are dsrecess, message, statusbar, separator, hull, and bbox. Omitting this option from the command will cause the command to simply return the list of component options.
pathName configure ?option? ?value option value …?
Query or modify the configuration options of the widget. 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. If option is specified with no value, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no option is specified, returns a list describing all of the available options for pathName.
pathName default ?index?
In a dialog box, one button may be designated the default button (meaning, roughly, the one that gets invoked when the user presses Enter). Depending on the theme, the default button may be displayed with an extra highlight ring, or with a different border color. This option allows the user to specify the default button. The index specified must be end, ok, cancel or the index name of an existing button. If no index is specified the index of the current default button is returned.
pathName delete index
This command deletes a button from the button toolbar in the window. The index specified must be end, ok, cancel or the index name of an existing button. This command destroys the specified button widget, it no longer exists in memory.
pathName hide index
Hides the button in the button toolbar at the given button index. This causes the button to be unmapped and forgotten about by the window manager.
pathName identify element x y
Returns the name of the element under the point given by x and y, or an empty string if the point does not lie within any element. x and y are pixel coordinates relative to the widget. Some widgets accept other identify subcommands.
pathName insert index newbutton
Inserts a new button into the button toolbar in the dialog at a location just before the given button index.
pathName instate statespec ?script?
Test the widget’s state. If script is not specified, returns 1 if the widget state matches statespec and 0 otherwise. If script is specified, equivalent to
if{[pathNameinstatestateSpec]}script
pathName invoke index
Invokes the command associated with the button at button index.
pathName post ?arg arg …?
Posts the dialog. This causes the dialog to be mapped by the window manager. Optional arguments may be sent to the post command such as force, -height, -width, -x or -y.
pathName recess
Returns the path to the dialog’s recess. The recess is the main area of the dialog which will be utilized for user defined widgets.
pathName show index
Shows the button in the button toolbar at the given button index. This causes the button to be mapped by the window manager.
pathName unpost
Unposts the dialog. This causes the window to be unmapped and forgotten about by the window manager.
pathName statusmessage message ?type?
Posts a message to the status bar.

## Example

hwtk::dialog .d -title "::hwtk::dialog"
set msg "User must create widgets/sub-windows inside dialog recess area using dialog's 'recess' command."
pack [hwtk::label [.d recess].check1 -text "\$msg" -wraplength 3i] -anchor nw
.d post

#::hwtk::dialog