Alert Dialog API

Contents

1. Description
2. Goals
3. API
   1. Location
   2. ASL Public Interface
   3. Return Value
   4. Notes
4. Alert Dialog Helper struct
5. Issues and Future Considerations

Description

This API is a refinement of the Modal Dialog Integration Kit in that the model and layout definitions are already defined, and you need to provide a simple collection of parameters to complete the fleshing out of the layout.

Goals

The intent of the API is to provide the client with an easy and portable way to set up an alert dialog that can:

• Notify the user of something in a way that requires immediate attention
• Optionally get some basic feedback from the user

API

Location

<adobe/future/alert.hpp>

ASL Public Interface

std::pair<adobe::name_t, bool> alert(const char*                    window_name,
                                     const char*                    message_text,
                                     adobe::name_t*                 first_button_name,
                                     adobe::name_t*                 last_button_name,
                                     const char*                    checkbox_name = 0,
                                     const boost::filesystem::path& icon_path = boost::filesystem::path(),
                                     std::size_t                    default_button_index = 0,
                                     std::size_t                    cancel_button_index = 1);

window_name

points to a C-string to be used to set the dialog title.

message_text

points to a C-string to be used to set the dialog body text.

first_button_name

points to the first button in a list of possible buttons from which the user can choose.

last_button_name

points to one-past-the last button in a list of possible buttons from which the user can choose.

checkbox_name

optionally points to a C-string to be used to label a checkbox. Common uses of a checkbox in an alert dialog may be “apply to all”- or “don’t ask again”-style questions. If the pointer is set to =0= the checkbox is not added to the layout.

icon_path

specifies the path to an image file that is to be used as the icon of the dialog. If unspecified the icon is not added to the layout.

default_button_index

is the button offset from first_button_name that is to be the default button – that is, the button that is selected when the user hits the Enter or Return keys.

cancel_button_index

is the button offset from first_button_name that is to be the cancel button – that is, the button that is selected when the user his Escape key.

In the event when default_button_index and cancel_button_index refer to the same button the button is given the default behavior, and the cancel behavior is ignored for this alert.

Should strings be passed in decorated with xstring notation they will be localized before they are displayed to the user.

Return Value

The adobe::alert API returns a std::pair whose elements are as follows:

name_t

The name of the button the user selected in order to close the alert.

bool

The state of the checkbox (if one was desired) for the dialog. In the case when the checkbox was not desired, the value of this bool is undefined.

Notes

While the adobe::name_t set used to name the buttons are not required to be unique it is recommended, otherwise you will not be able to distinguish between a user clicking on one or the other.

In the alert API the invocation of any button will close the dialog.

Alert Dialog Helper struct

The adobe::alert_helper_t struct has been supplied to ease in the execution of the alert dialog. It takes into account many default settings for you so you only specify that which is different from the default. Every member in the struct has a one-to-one correspondence to parameters within the alert dialog. Finally there is a run() member function that passes off the struct parameters to the adobe::alert procedure.

Issues and Future Considerations

• The range used to describe the button names should move away from adobe::name_t and to a format that is more easily localizable.
• The default and cancel button indices should be of the same type as type used to specify the button names.
• It should be a requirement that each of the button names is unique.