NAME

hwtk::dialog - create a dialog box.

 

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.

 

CLASS DIAGRAM

SYNOPSIS

hwtk::dialog - pathName ?option value? ...

 

STANDARD OPTIONS

-clientdata, clientData, ClientData

-height, height, Height

-width, width, Width

 

WIDGET-SPECIFIC OPTIONS

 

Command-Line Name: -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.

 

Command-Line Name: -destroyonunpost

Database Name: destroyonunpost

Database Class: DestroyOnUnpost

Specifies whether or not the dialog should be destroyed when unposted. Acceptable values are 1 and 0.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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 graphics area. None means a non-modal dialog, no interaction locking.

 

Command-Line Name: -padx

Database Name: padX

Database Class: Pad

Specifies the amount of extra space to allocate for the dialog, in pixels, in the X (horizontal) direction.

 

Command-Line Name: -pady

Database Name: padY

Database Class: Pad

Specifies the amount of extra space to allocate for the dialog, in pixels, in the Y (vertical) direction.

 

Command-Line Name: -propagate

Database Name: propagate

Database Class: Propagate

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.

 

Command-Line Name: -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.

 

Command-Line Name: -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; the separator option is set to true. Valid values are true and false.

 

Command-Line Name: -title

Database Name: title

Database Class: Title

The title of the dialog which will appear in the title bar of the dialog.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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 COMMAND

In addition to the standard configure, cget, identify, instate, and state commands, dialog support the following additional widget commands:

pathName add ?arg arg ...?

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 -text. 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 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 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 insert index newbutton

Inserts a new button into the button toolbar in the dialog at a location just before the given button index.

 

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.

 

EXAMPLES

 

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