PtAlert()

Display a message and request a response

Synopsis:

int PtAlert( PtWidget_t *parent,
             PhPoint_t const *location,
             char const *title,
             PhImage_t const *image,
             char const *message,
             char const *msgFont,
             int btnCount,
             char const **buttons,
             char const **btnFonts,
             int defBtn,
             int escBtn,
             int flags );

Arguments:

parent

A pointer to the parent widget of the dialog (usually a window). By setting the flags, you can block the parent and/or position the dialog relative to it.

location

A pointer to a PhPoint_t structure that specifies the location of the dialog relative to the parent or console, depending on the flags. If location is NULL, the dialog is centered.

title

The title for the dialog. If you don't want a title bar, set this argument to NULL.

image

A pointer to a PhImage_t structure that specifies an icon to display beside the message. If you don't want an icon, set this argument to NULL.

message

The message to display.

msgFont

The font for the message text; the default is TextFont09. You should create the font name by calling PfGenerateFontName().

btnCount

The number of buttons to display.

buttons

A pointer to an array of strings to be displayed in the buttons. This array must contain at least btnCount strings.

All button-text arguments let you define shortcut keys. Place an ampersand (&) in front of the character that you want to be the shortcut. For example, if you specify &Yes, the Y is underlined in the button, and you can select the button by pressing y or Y.

btnFonts

A pointer to an array of strings containing the fonts to be used in the buttons. If this argument is NULL, TextFont09 is used for all the buttons. Otherwise, this array must contain at least btnCount fonts. You should create the font names by calling PfGenerateFontName().

defBtn

The number of the button that initially has focus when the dialog is realized. The left button's index is 1.

escBtn

The number of the button that's bound to the Esc key. If you wish to disable the Esc key, set this argument to 0. If Esc is enabled, the close button is included in the dialog's titlebar (if there is one). Closing the dialog in this manner is the same as pressing the Esc key; the dialog closes and the escBtn button is selected.

flags

Flags that specify the behavior for the dialog. This can be up to one of the following:

• Pt_CENTER — center the dialog.
• Pt_LEFT — left-align the dialog (the default).
• Pt_RIGHT — right-align the dialog.

with any combination of the following:

• Pt_BLOCK_ALL — block all of the application's windows while the dialog is displayed.
• Pt_BLOCK_PARENT — block the widget specified by the parent argument (if non-NULL).
• Pt_ESC_DISABLE — disable the ESC key as a means of dismissing the dialog.
• Pt_MODAL — the same as Pt_BLOCK_ALL.
• Pt_RELATIVE — position the dialog relative to the given parent widget. If this bit isn't set or parent is NULL, the dialog is positioned relative to the current console.

Pt_BLOCK_ALL overrides Pt_BLOCK_PARENT.

Library:

ph

Description:

This function displays a dialog that displays a message and contains any number of buttons so that you can respond.

A sample dialog displayed by PtAlert().

Returns:

The number of the button that you selected.

Examples:

char const *btns[] = { "&Save it", "&Discard changes",
                       "&Cancel" };
char Helvetica14[MAX_FONT_TAG];

switch( PtAlert( base_wgt, NULL, "File Not Saved", NULL,
           "The file hasn't been saved.\n\
What do you want to do with it?",
           PfGenerateFontName("Helvetica", 0, 14,
                              Helvetica14),
           3, btns, NULL, 1, 3, Pt_BLOCK_ALL ) ) {

    case 1:
        /* save */ 
        break; 

    case 2:
        /* discard changes */
        break;

    case 3:
        /* cancel */
        return; 
}

Classification:

Photon

See also:

ApError(), PfGenerateFontName(), PhImage_t, PhPoint_t, PtNotice(), PtPassword(), PtPrompt()

“Dialog modules” in the Working with Modules chapter of the Photon Programmer's Guide