Difference between revisions of "Modal Dialog Integration Kit"

From Adobe Open Source Wiki
Jump to: navigation, search
(initial population)
 
 
(3 intermediate revisions by one user not shown)
Line 1: Line 1:
=<code>Goals</code>=
+
''This documentation has been moved to the ASL distribution as of release 1.0.22''
 
+
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
+
 
+
<pre>
+
enum display_options_t
+
{
+
    dialog_display_s,
+
    dialog_no_display_s,
+
    dialog_never_display_s
+
};
+
</pre>
+
 
+
; 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.
+
 
+
<pre>
+
typedef std::pair<dictionary_t, array_t> record_info_t;
+
</pre>
+
 
+
* 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===
+
 
+
<pre>
+
struct dialog_result_t
+
{
+
    record_info_t record_m;
+
    dictionary_t  display_state_m;
+
    dictionary_t  command_m;
+
    name_t        terminating_action_m;
+
};
+
</pre>
+
 
+
; 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 <code>handle_dialog</code> 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 <code>handle_dialog</code> it is assumed that there exists in the Adam model an output cell called <code>result</code> that will be fetched and whose value will be stuffed into this dictionary. Note the implication there is that the <code>result</code> 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 <code>action</code> parameter and a <code>bind</code> 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 <code>action</code> value and the Adam cell contents of the bound Adam cell. In return the callback should send back a <code>bool</code> specifying whether or not to close the dialog. If the callback returns <code>true</code>, the <code>terminating_action_m</code> field in the dialog return results will be this action name. The <code>typedef</code> for this parameter is:
+
 
+
<pre>
+
typedef boost::function <bool (adobe::name_t, const adobe::value_t&)> action_callback_t;
+
</pre>
+
 
+
===<code>handle_dialog</code> 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):
+
 
+
<pre>
+
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);
+
</pre>
+
 
+
; 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 <code>result</code> that is defined to be a dictionary of values. The value of the <code>result</code> cell will be handed back in the <code>command_m</code> field of the <code>dialog_result_t</code> 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 <code>action</code> 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.
+

Latest revision as of 20:29, 5 December 2006

This documentation has been moved to the ASL distribution as of release 1.0.22