Xbasic

UI_DLG_BOX Function

Syntax

Result as C = UI_DLG_BOX(C title, C dialog_format [,C code])

Arguments

titleCharacter

The title of the dialog. The title may also be specified dynamically using the syntax:

Title = "@=" +  Title_Var_Name
dialog_formatCharacter

A series of Xdialog commands that describe the appearance of the dialog box. The basic structure of the Format section is:

<<%dlg%
Xdialog_Code
%dlg%
Argument
Description
<<%dlg%

The only optional part of this argument is the "dlg" sequence of characters (the marker), which can be any string of characters, as long as it is unique within this instance of the UI_DLG_BOX() function. The character sequence <<%dlg% is specifically recommended because it is supported by bubble help.

Xdialog_Code

One or more statements, each of which must be on a separate line from the <<%dlg% and %dlg% arguments.

%dlg%

The marker characters can be any string of characters, as long as they match those in the first argument ( <<%dlg% ).

codeCharacter

Xbasic code that describes what should happen when various events happen when the user is interacting with the dialog box. For example, what should happen when the user presses a button, or when the user tabs out of a field. The basic structure of the Event Handling section is:

<<%code%
Xbasic_code
%code%
Argument
Description
<<%code%

Indicates the start of a code block.

Xbasic_code

One or more statements, each of which must be on a separate line from the <<%code% and %code% arguments.

%code%

Indicates the end of a code block.

Returns

ResultCharacter

The value returned by the dialog. This is typically the name of the BUTTON that was pressed to close the dialog.

Description

Displays a dialog and returns the value of which button was pressed.

Discussion

The UI_DLG_BOX() function displays a modal dialog box and returns a character string.

Example 

This example of an extremely simple dialog box with the text "Hello World."

ui_dlg_box("Title","Hello World")

Alternatively:

format = <<%dlg%
"Hello World"
%dlg%
ui_dlg_box("Title", format)

Here is what this dialog box looks like:

Message box displaying the text "Hello World"
Message box displaying the text "Hello World"

Here is a dialog box with a title defined after the dialog box is displayed. The "@" is the indirection operator.

dim dlg_title as C
dlg_title = "Title1"
ui_dlg_box("@=dlg_title",<<%dlg%
<Set Title!settitle>
%dlg%,<<%code%
if a_dlg_button = "settitle" then
    dlg_title = ui_get_text("","Set new title",dlg_title)
     a_dlg_button = ""
end if
%code%)
Message with a button to change the title
Message with a button to change the title
Dialog shown when the Set Title button is clicked
Dialog shown when the Set Title button is clicked
Message updated to show the new title
Message updated to show the new title

Limitations

Desktop applications only.

See Also