Modal Dialog Interface Kit [User-Supported (Platform) Libraries]

Classes
struct	dialog_result_t
class	modal_dialog_t
Typedefs
typedef boost::function< bool(name_t, const any_regular_t &)>	action_callback_t
Enumerations
enum	display_options_t { dialog_display_s, dialog_no_display_s, dialog_never_display_s }
Functions
dialog_result_t	handle_dialog (const dictionary_t &input, const dictionary_t &record, const dictionary_t &display_state, display_options_t display_options, std::istream &layout_definition, std::istream &sheet_definition, action_callback_t callback, const boost::filesystem::path &working_directory, platform_display_type parent=platform_display_type())

---

Detailed Description

The goal of the modal dialog interface kit is to provide a single point from which a user can have a dialog brought up and managed by the layout enging (Eve) and the property model manager (Adam). We also want to allow for easy "scripting" of the dialog through the interface, as well as being able to remember and reuse dialog-specific state information. There are several structs to support the one API through which interaction takes place.

---

Typedef Documentation

typedef boost::function<bool (name_t, const any_regular_t&)> action_callback_t

The modal dialog interface now sports an API call back to the client in the case when a button is pushed. In the Eve definition of the dialog there must be an action parameter and a bind statement to notify the implementation what Adam cell is to be bound to this button. In the case when the button is clicked this callback is handed the action value and the Adam cell contents of the bound Adam cell. In return the callback should send back a bool specifying whether or not to close the dialog. If the callback returns true, the terminating_action_m field in the dialog return results will be this action name.

Definition at line 153 of file modal_dialog_interface.hpp.

---

Enumeration Type Documentation

enum display_options_t

Display options control how the dialog is to be used during the playback of scripted command parameters.

Enumerator:

dialog_display_s	Show the dialog to the user in any instance
dialog_no_display_s	Do not show the dialog to the user unless the command parameters are invalid for the model as currently specified. This allows for the user to modify the parameters and verify them before moving them on to the command.
dialog_never_display_s	Do not show the user the dialog for any reason. In this instance when the parameter are invalid, error out of the playback.

Definition at line 54 of file modal_dialog_interface.hpp.

---

Function Documentation

dialog_result_t adobe::handle_dialog	(	const dictionary_t &	input,
		const dictionary_t &	record,
		const dictionary_t &	display_state,
		display_options_t	display_options,
		std::istream &	layout_definition,
		std::istream &	sheet_definition,
		action_callback_t	callback,
		const boost::filesystem::path &	working_directory,
		platform_display_type	parent = platform_display_type()
	)

One function call to display a model dialog (or playback a script). We might also want to consider a preview function call back (that will get called with the same command dictionary anytime something in the sheet changes).

Parameters:

input	contains the input values for input cells as they are defined in the sheet. Each key in this dictionary should correspond to an input cell in the sheet to which the relevant value will be imposed. This can be a default-constructed dictionary, in which case input cells will be set to the values defined in their sheet initializers.
record	is the previously recorded script information for the dialog, to be used to execute the dialog when running from an action or to retain the previoud instance of the dialog's values for the new dialog instance.
display_state	is the previously recorded layout state information for the dialog.
display_options	is one of the three enumerations specified above, according to which semantic behavior you would like to get out of this routine.
layout_definition	is a stream that will be parsed as the Eve definition for this dialog.
sheet_definition	is a stream that will be parsed as the Adam definition for this dialog. Note that the only requirement on the Adam sheet is that there exist an output cell called result that is defined to be a dictionary of values. The value of the result cell will be handed back in the command_m field of the dialog_result_t upon return from this procedure.
callback	is the function proc that is called when a button in the modal dialog is invoked by the user. The two parameters to the callback are the action name of the button as defined in the Eve definition, along with the contents of the Adam cell to which the button is bound. The boolean return value specifies whether or not the modal dialog interface should terminate the dialog.
working_directory	is the directory from which the dialog widgets should use to fetch disk-based resources. Whether or not this is necessary is predicated on the resource requirements of the widgets used in the dialog.
parent	is the parent widget that will 'own' the dialog that is about to be created. This notion is purely a platform-specific one, and is not a requirement as far as ASL goes.

Returns:

a filled in dialog_result_t.

Definition at line 255 of file modal_dialog_interface.hpp.