hiDisplayAppDBox

hiDisplayAppDBox(
?name s_dboxHandle 
[ ?dboxBanner t_dboxBanner ]
[ ?dboxText t_dboxText ]
[ ?callback g_callback ]
[ ?dialogType x_dialogType ]
[ ?dialogStyle s_dialogStyle ] 
[ ?buttonLayout s_buttonLayout ]
[ ?buttons g_buttons ]
[ ?dontPopdowns g_dontPopdowns ]
[ ?defaultButton x_defaultButton ]
[ ?location l_location ]
[ ?help g_help ]
) 
=> t / nil / cancel

Description

Creates and displays a dialog box. You can add a pre-defined set of buttons to the dialog box or you can specfiy your own buttons. The dialog box is destroyed when it is removed from the screen.

Arguments

`?name` s_dboxHandle
	SKILL handle to the dialog box. The dboxHandle symbol is set to point to the created dialog box; when the dialog box is dismissed, this symbol is reset to `nil`.
`?dboxBanner` t_dboxBanner
	Text that appears in the window manager banner of the dialog box.
`?dboxText` t_dboxText
	Message that is displayed in the dialog box.
`?callback` g_callback
	Text string specifying the SKILL procedure to be executed when the user clicks OK or Yes in the dialog box. This callback is called if s_buttonLayout is `’`OKCancel, `’YesNo`, or `’YesNoCancel.` If s_buttonLayout is `’UserDefined` and you use the g_buttons argument to define your own buttons, specify g_callback as a list of callbacks which corresponds to the list of buttons. Each element in the list is a string (name of the callback function) or `nil` (if you do not want to specify a callback for a button). The first callback in g_callback is the callback for the first button in g_buttons, the second callback is for the second button, and so on. If you specified a Help button in g_buttons and if you want the standard Doc Assistant mechanism to be invoked when the user clicks the button, use the following procedure as the callback for the Help button: procedure ( myHelp ( ) hiHelp ( ’dbox dBoxName )) If s_buttonLayout is `’UserDefined` and s_dialogStyle is `’modeless`, you should specify a callback for each button, as the function returns `t` immediately after the dialog box is displayed (if there is no error). You can write the callback in a way that it returns the button index. For example, write the callback as: procedure( myCallback ( button ) when (button == 1 "Overwrite selected") and, in the `hiDisplayAppDBox` function, pass the button index to the callback: ?callback ’("myCallback(1)" "myCallback(2)" "myCallback(3)")
`?dialogType` x_dialogType
	One of the following dialog box types, which determine the appearance of the dialog box: `hicWarningDialog` (default) `hicErrorDialog` `hicInformationDialog` `hicMessageDialog` `hicQuestionDialog` `hicWorkingDialog`
`?dialogStyle` s_dialogStyle
	One of the following symbols, which determine the blocking behavior of the dialog box: `’modal` Blocks access to the application while it is displayed. The user must dismiss the dialog box in order to continue using the application. (Access to window manager commands or other applications is not blocked.) The `’modal` dialog box cannot be displayed before the initialization—which includes reading the `.cdsinit` file or other SKILL files—is complete. To delay displaying of the `’modal` dialog box until initialization is complete, use hiEnqueueCmd. `’modeless` Does not block access to the application. The user can continue using the application without having to close the dialog box. The default value of this argument is `’modal`.
`?buttonLayout` s_buttonLayout
	Symbol specifying the buttons that appear in this dialog box. Valid values are: `’OKCancel` (default) `’YesNo` `’YesNoCancel` `’CloseHelp` `’Close` `’UserDefined` If you want to customize the buttons, specify `’UserDefined` as the value of this argument and specify your buttons with the g_buttons argument. A Help button appears with all choices except `’Close` and `’UserDefined`. (See the description of g_buttons if you want a Help button with `’UserDefined`.) The dialog box callback, if any, is executed only if s_buttonLayout is not of type `’Close` or `’CloseHelp`, which simply dismiss the dialog box with no action taken.
`?buttons` g_buttons	List of buttons that you want to display in the dialog box. Specify this argument as a list of strings. You can specify any string for a button, for example, "`Overwrite"`, "`Update"`, or "`Cancel"`. A Help button is not added by default to your list of buttons. If you want a Help button, specify it in the g_buttons list and specify a callback for it in the g_callbacks argument. You can also invoke the standard Doc Assistant mechanism when the user clicks Help; see the description of g_callbacks for more information.
`?dontPopdowns` g_dontPopdowns
	A list, each element of which is `t` or `nil`, that determines whether the dialog box is closed when a button is clicked. Specify `t` if you want to continue to display the dialog box when the button is clicked; specify `nil` if you want the dialog box to be closed when the button is clicked. The items in the list correspond to the buttons in g_buttons. The first item in g_dontPopdowns determines the behavior of the first button in g_buttons, the second item determines the behavior of the second button, and so on. The default value of this argument is `nil` for all buttons.
`?defaultButton` x_defaultButton
	Specifies the default button to be used when the Return key is pressed. The default button should be specified by its position. Possible choices can range from 1 through 4 depending on s_buttonLayout. For example, if the s_buttonLayout argument is set to ’`YesNo`, and the x_defaultButton is set to 2, the No button is set as the default button. If no value or an invalid value (such as "3" when there are only two buttons) is given for this argument, the first button is set as the default.
`?location` l_location
	The location of the dialog box on the screen, specified as the x and y coordinates of the upper left corner of the box: `list(`x-coordinate y-coordinate`)` If this argument is not specified or if it is specified incorrectly, then the default location set by `hiSetDBoxDefaultLocation` is used. If the default location has not been set, then the toolkit that implements the dialog box determines the location (usually the center of the screen).
`?help` g_help	The value of this argument is used if s_buttonLayout is `’`OKCancel, `’YesNo`, `’YesNoCancel`, or `’CloseHelp`. This argument is ignored if s_buttonLayout is `’UserDefined`, unless you have created a Help button that calls `hiHelp(’dBox` dBoxName`)`. If you specify a single string or symbol, it is used to set the `hiHelpAppName` property on the symbol that represents the dialog box name. If you specify a list of strings or a list of symbols, the first element in the list is used to set the `hiHelpAppName` property and the second element is used to set the `hiHelpSymName` property. (If you want to specify the help symbol only, specify a list of two strings or symbols, with `nil` as the first element of the list and the help symbol as the second element. This sets the `hiHelpSymName` property without setting the `hiHelpAppName` property.) When a user clicks Help on the dialog box, the `hiHelp` function is called with the following arguments: appId helpTag If the `hiHelpAppName` property has been set, it is used as the appId, otherwise the application ID of the current window is used as the appId. If the `hiHelpSymName` property has been set, it is used as the helpTag, otherwise the dialog box name is used as the helpTag. The appId and helpTag determine the name of the tag file that is called (appId`.tgf`) and the help tag in the file that is accessed. You can also use the `hiHelpAppName` and `hiHelpSymName` properties directly to specify the help file and help tag that are used to reference the help.
	If you do not want to use the default `.tgf` help file mechanism, you can specify your own callback for the Help button.

Values Returned

If s_buttonLayout is not ’UserDefined, this function returns one of the following values:

`t`	The OK, Yes, or Close button was selected. If s_dialogStyle is `’modeless`, the function returns `t` immediately after the dialog box is displayed, if there is no error; it does not wait for a button to be selected.
`nil`	The Cancel or No button was selected, an error occurred, or one of the arguments is invalid.
`’cancel`	The Cancel button was selected and s_buttonLayout is `’YesNoCancel`.

If s_buttonLayout is ’UserDefined and If s_dialogStyle is ’modal, this function returns one of the following values when a button is clicked:

buttonIndex	The index of the button that is clicked, if the button does not have a callback associated with it. The first button in the dialog box is `1`, the second is `2`, and so on.
callbackReturnVal	The return value of the callback that is associated with the button that is clicked.

If s_buttonLayout is ’UserDefined and s_dialogStyle is ’modeless, this function returns one of the following values immediately after the dialog box is displayed:

`t`	There is no error.
`nil`	There is an error.

Examples

Creates a reminder list and a warning dialog box for each item of the list.

;;; creating the reminder list
trReminders = '( "Project Meeting 10-11" "Workout 12-1" "Team Meeting 3-4" )

foreach( reminderText trReminders ; for each reminder 
   hiDisplayAppDBox(
      ?name      gensym( 'trReminderDialogBox ) ; unique variable
      ?dboxBanner  "Reminder"
      ?dboxText  reminderText
      ?callback  sprintf( nil "trReminderCB( \"%s\" )"  reminderText ) ; dynamically built callback
      ?dialogType  hicWarningDialog
      ?dialogStyle  'modeless
      ?buttonLayout  'YesNo
      )
   ) ; foreach

procedure( trReminderCB( reminderText )
   printf( "%s completed" reminderText )
   )

Creates different types of modal dialog boxes.

trDialogTypes = '(
   hicWarningDialog hicErrorDialog hicInformationDialog
   hicMessageDialog hicQuestionDialog hicWorkingDialog
   )

Cadence User Interface SKILL Reference
Product Version IC23.1, September 2023