Modal Dialog Integration Kit

From Adobe Open Source Wiki
Revision as of 18:49, 21 June 2006 by FosterBrereton (Talk | contribs)

Jump to: navigation, search

Contents

Goals

The goals for such an interface:

  • Allow for easy "scripting" (recall/playback of command parameters)
  • Remember dialog-specific state information (current selected tab, etc.)

API Components

Display options

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

enum display_options_t
{
    dialog_display_s,
    dialog_no_display_s,
    dialog_never_display_s
};
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 parameters are invalid, error out of the playback.

Record Info

The record info handles action recording and playback. It can also retain dialog preferences if you want to remember parameters from the previous instance of the dialog.

typedef std::pair<dictionary_t, array_t> record_info_t;
  • The dictionary contains the contributing values which were modified after the initial dialog state.
  • The array contains a list of cells which are contributing - do not have their initial priority - and the values are the same as the initial values.

In the Adam API these correspond to a mark and can be applied with a set() and touch() [there should be a single call to apply a mark].

Dialog Result

struct dialog_result_t
{
    record_info_t record_m;
    dictionary_t  display_state_m;
    dictionary_t  command_m;
    name_t        terminating_action_m;
};
record_m 
The set and touched record pair that need to be stored in order to script the dialog to re-execute the command that is being returned (also in this struct). Note that this record information stores the "intention" of the user, and may vary greatly from the actual values needed by the command in order to execute. This information is more "accurate" than the parameters needed for this instance of the execution because the input values may vary for a command from instance to instance, but retaining the intention of the user assures that they get what they want out of the command based on the parameters they explicitly set. Note that this information can be round-tripped over multiple instantiations of the handle_dialog API, resulting in a new instance of the dialog having the same intent with which the previous instance left off (aka previous values are retained).
display_state_m 
Retained information as it pertains to the visual layout of the view (window location, size, etc.) and also as it pertains to the basic model of the view (what tab(s) are currently selected, what the state of other basic sheet cells are, etc.)
command_m 
Contains the complete parameter set necessary to execute the function of which this dialog is intended to collect the parameters. While using handle_dialog it is assumed that there exists in the Adam model an output cell called result that will be fetched and whose value will be stuffed into this dictionary. Note the implication there is that the result cell itself is a dictionary of values.
terminating_action_m 
The name of the action that was used to terminate (close) the dialog. See the Action Callback section of this documentation for more information on how this value is set at runtime.

Action Callback

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. The typedef for this parameter is:

typedef boost::function <bool (adobe::name_t, const adobe::value_t&)> action_callback_t;

handle_dialog Procedure

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):

dialog_result_t handle_dialog( const dictionary_t&  input,
                               const record_info_t& record,
                               const dictionary_t&  display_state,
                               display_options_t    display_options,
                               std::istream&        layout_definition,
                               std::istream&        sheet_definition,
                               action_callback_t    callback);
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.