Difference between revisions of "Action Element (Data)"

Revision as of 01:50, 2 December 2008

Context: HL Kit … Kit Reference … Data File Reference … Portal Element (Data) 

The "action" Element

Action portals behave like buttons and always trigger some sort of behavior. That behavior could be built into HL (e.g. delete a pick) or completely defined by you, but some sort of action is invoked. Action portals are specified via the "action" element. The complete list of attributes for this element is below.

IMPORTANT! Many action portals have behaviors that rely on an associated pick. These portals assume they are defined within the context of a template, and the associated pick is dictated by that template.

action	(Optional) Set – Designates the behavior to be invoked when the action portal is triggered by the user. Must be one of these values: delete – Deletes the associated pick. Only useful within tables for allowing the user to delete a pick that they added. info – Displays detailed information about the associated pick. edit – Brings up a form within which the user can edit the contents of a gizmo, where the gizmo is the child of the associated pick. form – Brings up the modal form specified within the "form" attribute. trigger – Invokes the Trigger script specified via the "trigger" child element. gear – notes – load – lock – unlock – master – minion – getgear – combatstart – combatend – newturn – initchange – integrate – dashsort – Default: "delete".
buttontext	(Optional) Text – Specifies the text to draw over whatever bitmap is used for the button. Although buttons with text are often larger that other buttons, they are also much easier to create. If empty, no text is drawn over the bitmap. Default: Empty.
confirm	(Optional) Text – Specifies the text to be displayed as a confirmation message before the triggered behavior is actually performed. This attribute is only utilized for the "trigger", "delete", "edit", and "form" action types. If empty, the triggered behavior is performed immediately - without any confirmation check. Default: Empty.
form	(Optional) Id – Specifies the unique id of the form to be displayed when the portal is triggered. This attribute only applies to the "form" action type and is required for that action type. Default: Empty.
field	(Optional) Id – Specifies the unique id of the field that contains the notes text to be edited. This attribute only applies to the "notes" action type and is required for that action type. Default: Empty.
minion	(Optional) Id – Specifies the unique id of the minion to be switched to when the "minion" action portal is triggered. This attribute only applies to the "minion" action type, but it is not required for that action type. If specified, the indicated minion is accessed. If not specified, the minion attached directly by the pick associated with the portal (via the containing template) is accessed. Default: Empty.

   -Action portal "trigger" enables the UI to trigger a script
       -Allows the invoking of adjustments against a usage pool
           -User enters value into edit field, then clicks action button, which
               then triggers the script to pull the value from the field and
               apply the adjustment to the usage pool, after which field is reset
       -XML requires a child "trigger" element containing the script
       -Script is invoked by calling Action_Trigger on the portal
       -Script starts with pick context associated with the containing template
       -Not valid for use in a thing context, since there is nothing to change
           via the script

-Action portal of type "load" can be used to load a new portfolio

   -Needed for the dashboard management
   -The "field" attribute specifies the field from which to get the file name
       to be loaded
   -UI must load the specified file as the new active portfolio
   -NOTE! This mechanism will be changed once we get campaign stuff into place

-To enable the user to access the master of a minion, use the "master" action portal

   -UI must recognize the action portal and interpret it appropriately
   -To identify the master, get the pick associated with the portal and use
       "pick->Get_Actor()->Get_Master_Actor()"
       -If NULL is returned, there is no master and an error should be reported

-To enable the user to access a master's minions, use the "minion" action portal

   -Author may specify an explicit minion by giving its id via "minion" attribute
       -If no minion given, implicit minion attached directly by pick is assumed
   -UI must recognize the action portal and interpret it appropriately
   -To identity the minion, follow these steps
       -Get the pick associated with the portal
       -Get the actor of the pick via "pick->Get_Actor()"
       -Get the id of the minion to be accessed from portal via "Get_Action_Minion"
       -If the id is 0, get the implicit minion via "actor->Get_Minion(pick)"
       -Otherwise, get the explicit minion via "actor->Get_Minion(id)"
       -If NULL is returned, there is no minion and an error should be reported

-The "getgear" action portal is provided for moving gear from minions into an actor

   -UI should create an iterator to get the proper set of sources and their gear
   -Engine provides five action portals for use to control key TacCon behaviors
       -"combatstart" - enters combat mode
           -Behaviors triggered via C_Portfolio::Enter_Combat_Mode
       -"combatend" - exits combat mode
           -Behaviors triggered via C_Portfolio::Exit_Combat_Mode
       -"newturn" - advances to the next combat turn
           -Behaviors triggered via C_Portfolio::Next_Combat_Turn
       -"initchange" - incorporates user changes to initiative values
           -Behaviors triggered via C_Portfolio::Apply_Initiative_Changes
       -"integrate" - properly integrates all pending actors into current combat
           -Behaviors triggered via C_Portfolio::Integrate_Pending_Actors

-The "dashsort" action portal provides a user trigger to re-sort the dashboard

   -Data files need to provide the button to use for the portal
   -UI can call C_Portfolio::Resort_Dashboard to actually trigger the re-sort

-If an "info" action portal does not have a "mouseinfo" script specified, default

   behavior will be used that shows the name, failed prereqs, and description

-All "edit" action portals default their visibility based on whether the pick

   actually has a gizmo associated with it; if no gizmo, the portal is hidden

-If a lock or unlock action portal is used without enabling "advancement" logic,

   a compilation error is reported

The "menu_literal" element also possesses child elements that define additional facets of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

choice	One or more "choice" elements must appear as defined by the given link. This element defines the individual options that the user can select from.
change	An optional "change" element may appear as defined by the given link. This element defines a Change Script for the portal.

The "choice" Element

The "choice" element defines an option that is listed within the menu for the user to select. Each choice has two facets: the value shown to the user and the value used internally. The complete list of attributes for this element is below.

display	Text – Specifies the text to be displayed for this choice.
value	(Optional) Text – Specifies the text to be tracked internally for this choice. When the user selects the choice, the value is saved into the associated field. If empty, the "display" text is used as the value. If the field used by the menu is value-based, all "value" attributes must be numeric values. Default: Empty.

The "change" Element

The "change" element defines a Change Script for the portal that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

PCDATA

Script – Specifies the code comprising the Change script.

Example

The following example demonstrates what a literal menu portal might look like. All default values are assumed for optional attributes.

<portal id="gender" style="menuNormal">
  <menu_literal field="perGender">
    <choice value="0" display="Gender: Male"/>
    <choice value="1" display="Gender: Female"/>
    </menu_literal>
  </portal>