Programming Guide



sm_message_box

Displays a message in a dialog box

int sm_message_box(char *text, char *title, unsigned int options, char *icon);

text
The text of the message. The text can contain format options shown in "Description." For Motif, the text has a maximum size of 75 characters.

title
The title of the dialog box. A null pointer or empty string specifies no title.

options
A bit mask that specifies message box display and behavior. Arguments that set different bits can be OR'd together. Table 5-11shows the flags that you can set on this mask.

icon
Specifies the icon to use in the dialog box. The icon specified here overrides any icon set through options. This argument is ignored in character-mode.

Returns

Description

sm_message_box creates a dialog box that displays a message and requests the user to select a button. Panther prevents further interaction with the application until the function returns with the user's selection.

The message text is a single string that wraps within the window. The text can contain these % format options:

%Kkeyname
Displays the specified key, where keyname is a logical key constant. When Panther displays the message, it replaces keyname with the key label string defined for that key in the key translation file. If there is no label, the %K is stripped out and the constant remains. Key constants are defined in smkeys.h

%B
Beeps the terminal with sm_bel before the message displays. This escape character must precede the message text.

%N
Creates a new line.

You control message box display and behavior by setting one or more flags in Table 5-11. You can set one flag from each group. Flag settings from different groups can be OR'd together.

Table 5-11 Message box settings

Flag settings (by group) Display/Action

Button Combinations

SM_MB_OK

OK

SM_MB_OKCANCEL

OK, Cancel

SM_MB_ABORTRETRYIGNORE

Abort, Retry, Ignore

SM_MB_YESNOCANCEL

Yes, No, Cancel

SM_MB_YESNO

Yes, No

SM_MB_RETRYCANCEL

Retry, Cancel

SM_MB_YESALLNOCANCEL

Yes, Yes to All, No, Cancel

SM_MB_OKALL

OK, OK to All

SM_MB_OKHELP

OK, Help

SM_MB_OKCANCELHELP

OK, Cancel, Help

SM_MB_ABORTRETRYIGNOREHELP

Abort, Retry, Ignore, Help

SM_MB_YESNOCANCELHELP

Yes, No, Cancel, Help

SM_MB_YESNOHELP

Yes, No, Help

SM_MB_RETRYCANCELHELP

Retry, Cancel, Help

SM_MB_YESALLNOALLCANCEL

Yes, Yes to all, No, No to all, Cancel

System Icon Display

SM_MB_ICONNONE

No icon

SM_MB_ICONSTOP

Stop

SM_MB_ICONQUESTION

Question

SM_MB_ICONWARNING

Warning

SM_MB_ICONINFORMATION

Information

Default Button

SM_MB_DEFBUTTONn

Sets the button in the nth position as the default button.

Modality

SM_MB_APPLMODAL

Confines user interaction to message box until message is acknowledged; user can interact freely with other applications.

SM_MB_SYSTEMMODAL

Confines user interaction to message box until message is acknowledged.

The following sections describe these settings in more detail.

Button Combinations

User options are controlled through the message box buttons. Table 5-11 shows the permissible combinations and the constants that set them.

Your message file defines the labels of message box buttons. You can edit this file and modify the label text. For more information on button label text, refer to "Customizing Push Button Labels for Message Boxes" in Application Development Guide.

System Icon

You can use the options parameter to set a flag for the system icon you want to display in the message window, if any. The actual icon that appears is platform-specific. In character mode, Panther searches in the message file for the tag that corresponds to the specified icon and its associated text; this text appears in front of the title text. For information on modifying message file tags, refer to "Using Message Files" in Application Development Guide.

Default Buttons

The options parameter can set the default button. The default button is specified by position—for example, you can set the third button as the default. You cannot set the Help button as the default button.

Modality

Panther requires the user to respond to the message before continuing interaction with the application. You can extend this restriction to the entire system, and thereby prevent interaction with other applications, by setting SM_MB_SYSTEMMODAL on the options parameter. The default modality setting is SM_MB_APPLMODAL, which constrains user interaction only within the Panther application.

Example

proc clean_exit()
{
vars btnPush
btnPush = sm_message_box("Save changes before exiting?",\
"", SM_MB_YESNOCANCEL | SM_MB_ICONQUESTION,"")

if (btnPush == SM_IDCANCEL)
{
return
}
if (btnPush == SM_IDYES)
{
call save_changes()
}
if (btnPush == SM_IDNO)
{
call sm_jclose()
}

}