PtMessage

A text message in a popup window

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtMessage

For more information, see the diagram of the widget hierarchy.

PhAB icon:

None - use PhAB's Message module.

Public header:

<photon/PtMessage.h>

Description:

The PtMessage widget displays a text-based message in a popup window. The message can include up to three optional buttons, allowing the user to select a course of action.

A PtMessage widget.

New resources:

Pt_ARG_MSG_BUTTON1, Pt_ARG_MSG_BUTTON2, Pt_ARG_MSG_BUTTON3

The labels for the three optional buttons that are displayed below the message. If no value is provided for Pt_ARG_MSG_BUTTON1, the default label of "Ok" is used. If no label is provided for the other two buttons, they default to NULL, which means they won't be displayed. These defaults are useful for messages that simply provide information.

You can assign a keyboard shortcut to each button. Simply place & in front of the character that will act as the shortcut. For example, if you specify &Save, the S will be underlined in the button. To select the button, the user can press s or S.

Note that the function PtAskQuestion() duplicates the functionality of the above example. For more information, see the Photon Library Reference. This function also makes the PtMessage dialog work as a modal dialog.

Pt_ARG_MSG_DEFAULT

The number of the default button, which can be selected by pressing Enter. The text of the default button is displayed in bold.

Pt_ARG_MSG_ESCAPE

The number of the button that Esc is bound to. If the value is 0 (the default), the Esc is disabled; otherwise the callback for the specified button is invoked when Esc is pressed.

Pt_ARG_MSG_FLAGS

Flags that control the appearance of the message:

• Pt_MSG_CENTER_ON_PARENT-if this flag is set, the message is centered on its parent.

Pt_ARG_MSG_FONT

The font in which the message will be displayed. Default is Helvetica 12 point.

Pt_ARG_MSG_TEXT

The text of the message.

Pt_ARG_MSG_TITLE

This optional resource displays a title in the window frame of the message. Defaults to NULL for no title.

Pt_CB_MSG_BUTTON1, Pt_CB_MSG_BUTTON2, Pt_CB_MSG_BUTTON3

These resources define lists of callback functions that will be invoked if the user selects one of the buttons. These resources correspond with the buttons by number. So, for example, if the user selects the button labeled with Pt_ARG_MSG_BUTTON1, then Pt_CB_MSG_BUTTON1 is invoked.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource (for example, Pt_CB_MSG_BUTTON1) that caused this callback to be invoked.

reason_subtype

0 (not used)

event

The raw event that caused the the callback to be invoked.

cbdata

Always NULL for this widget.

These callbacks should return Pt_CONTINUE.

Inherited resources:

Although this widget is a subclass of the PtContainer superclass, the only inherited resource it uses is Pt_ARG_POS for positioning the message:

Convenience functions:

The PtMessage widget defines a convenience function that makes it easier to use the widget once it's been created. Here's a brief overview:

PtMessageGetWindow()

Get the widget pointer to the message's window