Alert Dialog API
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.
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
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);
- points to a C-string to be used to set the dialog title.
- points to a C-string to be used to set the dialog body text.
- points to the first button in a list of possible buttons from which the user can choose.
- points to one-past-the last button in a list of possible buttons from which the user can choose.
- 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.
- 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.
- is the button offset from
first_button_namethat is to be the default button -- that is, the button that is selected when the user hits the Enter or Return keys.
- is the button offset from
first_button_namethat is to be the cancel button -- that is, the button that is selected when the user his Escape key.
In the event when
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.
adobe::alert API returns a
std::pair whose elements are as follows:
- The name of the button the user selected in order to close the alert.
- 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
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
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
Issues and Future Considerations
- The range used to describe the button names should move away from
adobe::name_tand 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.