Previous IDL Reference Guide: Procedures and Functions Next

DIALOG_MESSAGE

Syntax | Return Value | Arguments | Keywords | Version History | See Also

The DIALOG_MESSAGE function creates a modal (blocking) dialog box that can be used to display information to the user. The dialog must be dismissed, by clicking on one of its option buttons, before execution of the widget program can continue.

This function differs from widgets in a number of ways. The DIALOG_MESSAGE dialog does not exist as part of a widget tree, has no children, does not exist in an unrealized state, and generates no events. Instead, the dialog is displayed whenever this function is called. While the DIALOG_MESSAGE dialog is displayed, widget activity is limited because the dialog is modal. The function does not return to its caller until the user selects one of the dialog's buttons. Once a button has been selected, the dialog disappears.

There are four basic dialogs that can be displayed. The default type is "Warning". Other types can be selected by setting one of the keywords described below. Each dialog type displays different buttons. Additionally any dialog can be made to show a "Cancel" button by setting the CANCEL keyword. The four types of dialogs are described in the table below:

Table 3-39: Types of DIALOG_MESSAGE Dialogs

Table 3-39: Types of DIALOG_MESSAGE Dialogs
Dialog Type
Default Buttons
Error
OK
Warning
OK
Question
Yes, No
Information
OK

Syntax

Result = DIALOG_MESSAGE( Message_Text [, /CANCEL] [, /CENTER] [, /DEFAULT_CANCEL | , /DEFAULT_NO] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, /ERROR | , /INFORMATION | , /QUESTION] [, RESOURCE_NAME=string] [, TITLE=string] )

Return Value

DIALOG_MESSAGE returns a text string containing the text of the button selected by the user. Possible returned values are "Yes", "No", "OK", and "Cancel".

Arguments

Message_Text

A scalar string or string array that contains the text of the message to be displayed. If this argument is set to an array of strings, each array element is displayed as a separate line of text.


Note
You can use language catalogs to internationalize this value with strings in particular languages. For more information, see Using Language Catalogs.

Keywords

CANCEL

Set this keyword to add a "Cancel" button to the dialog.

CENTER

Set this keyword to center the dialog on the screen.


Note
This keyword is ignored on Microsoft Windows platforms because the dialog is always automatically centered.

DEFAULT_CANCEL

Set this keyword to make the "Cancel" button the default selection for the dialog. The default selection is the button that is selected when the user presses the default keystroke (usually Space or Return depending on the platform). Setting DEFAULT_CANCEL implies that the CANCEL keyword is also set.

DEFAULT_NO

Set this keyword to make the "No" button the default selection for "Question" dialogs. Normally, the default is "Yes".

DIALOG_PARENT

Set this keyword to the widget ID of a widget over which the message dialog should be positioned. When displayed, the DIALOG_MESSAGE dialog will be positioned over the specified widget. Dialogs are often related to a non-dialog widget tree. The ID of the widget in that tree to which the dialog is most closely related should be specified.

DISPLAY_NAME

Set this keyword equal to a string indicating the name of the X Windows display on which the dialog is to appear. This keyword is ignored if the DIALOG_PARENT keyword is specified. This keyword is also ignored on Microsoft Windows platforms.

ERROR

Set this keyword to create an "Error" dialog. The default dialog type is "Warning".

INFORMATION

Set this keyword to create an "Information" dialog. The default dialog type is "Warning".

QUESTION

Set this keyword to create a "Question" dialog. The default dialog type is "Warning".

RESOURCE_NAME

A string containing an X Window System resource name to be applied to the dialog. See RESOURCE_NAME for a complete discussion of this keyword.

TITLE

Set this keyword to a scalar string that contains the text of a title to be displayed in the dialog frame. If this keyword is not specified, the dialog has the dialog type as its title as shown in the table under DIALOG_MESSAGE.


Note
You can use language catalogs to internationalize this value with strings in particular languages. For more information, see Using Language Catalogs.

Version History

5.0
Introduced
6.2
Added CENTER keyword

See Also

XDISPLAYFILE

  IDL Online Help (March 06, 2007)