4BtnDialog

(System Library)

Description:	Draws a message dialog with up to 4 buttons and 3 lines of text and returns the number of the button that was pressed.
Returns:	Numeric
Usage:	Steady State only.
Function Groups:	Graphics
Related to:	Window
Format:	System.4BtnDialog(Icon, Btn1Label [, Btn2Label, Btn3Label, Btn4Label, Text1, Text2, Text3, Open, Modal, BoldFirst, Title, XPosPtr, YPosPtr, CloseButton, DefFocus, HelpFileName, HelpContextID])
Parameters:

Icon

Optional. Any image value for the (41 x 41) icon to display in the dialog. Set to "Invalid" to display only text with no icon. predefined icons include:  \System\Question_icon, \System\Error_icon, and \System\Warning_icon.

Btn1Label

Required. Any text expression for the label on the first button.

Btn2Label

An optional parameter giving any text expression for the label on the second button. If invalid, the button will be omitted.

Btn3Label

An optional parameter giving any text expression for the label on the third button. If invalid, the button will be omitted.

Btn4Label

An optional parameter giving any text expression for the label on the fourth button. If invalid, the button will be omitted.

Text1

An optional parameter giving any text expression for the first line of text to display.

Text2

An optional parameter giving any text expression for the second line of text to display.

Text3

A parameter giving any text expression for the third line of text to display. Must be given as Invalid if there is to be no third line.

Open

An optional parameter that is any logical expression. If TRUE (non-0) the dialog will be open. If FALSE (0), it will be closed. The default is TRUE. Open will be set to FALSE after the dialog has been acknowledged.

Modal

An optional parameter that is any logical expression. If true (non-0), the dialog is modal A modal dialog is always displayed on top of the calling window and prevents further interaction with that window., if false (0) it is non-modal. This parameter will override the System NoModal flag. If it is omitted, the NoModal flag will prevail. If the NoModal flag is also omitted, the dialog will default to being modal.

BoldFirst

An optional parameter that is any logical expression. If true (non-0) the first line of text in the dialog will appear in boldface type. If false (0), it will not be bolded. The default is false.

Title

An optional parameter that is any text expression that gives the title to appear in the window's title bar.

XPosPtr

An optional parameter that is a pointer to a variable in which the x-coordinate of the center of the dialog is stored.

YPosPtr

An optional parameter that is a pointer to a variable in which the y-coordinate of the center of the dialog is stored.

CloseButton

An optional parameter that is the index of the button to which the title bar close button should be mapped (from 1 to 4). If CloseBtn is invalid, then the title bar close button is mapped to the first button with the same text as the CancelLabel or CloseLabel application properties. If no buttons match these labels, then "0" is returned when the dialog is closed using the title bar close button.

DefFocus

An optional parameter that is the index of the button that should have the focus when the dialog opens (from 1 to 4). If DefFocus is invalid, the first button has the focus when the dialog opens.

HelpFileName

An optional parameter that is the name of the help file containing the help topic for this dialog (as identified in the HelpContextID parameter). If HelpFileName or HelpContextID are invalid, then the default is as per the Window function.

HelpContextID

An optional parameter that is the numeric context ID identifying the help topic for this dialog (within the help file identified in the HelpFileName parameter). If HelpFileName or HelpContextID are invalid, then the default is as per the Window function.

Comments

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section. If your application predates version 11.2, use the backslash notation rather than dot: \System\ The return value for this module is in the range of 1 to 4 and identifies which button has been pressed. If one of the buttons is labeled "Cancel", pressing <ESC> will cause the number of the "Cancel" button to be returned. For any optional parameter that is to be set, all optional parameters preceding the desired one must be present, although they may be invalid.

Example:

  If Valid(FileName) && ! Valid(OK);
  [
    Size = FileFind(FileName, 8, 4);
    IfElse(Size[0], Execute(
      OpenErrDlg = 1,
      OK = 0
    ),
    { else }
      OK = 1
    );
  ]

  System.4BtnDialog(\System\Warning_Icon { Icon to use },
                     \GetPhrase("OKLabel"), \GetPhrase("CancelLabel"), Invalid, Invalid { 2 buttons },
                     "File exists !" {1st line of text},
                     "Replace it ?"  {2nd line of text},
                     Invalid         {3rd line of text},
                     OpenErrDlg { Opening trigger});

This example shows English text as the dialog message for the sake of clarity. In practice, phrases should be created and \GetPhrase used instead.

This code waits until a file name has been set, presumably from an edit field or some other method not shown here, and then checks to see if it already exists in the current directory. If it does exist, the variable OpenErrDlg is set TRUE and an error dialog with "OK" and "Cancel" buttons appears, warning of the existence of the file.