Difference between revisions of "Action Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|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 co...)
 
(→‎The "action" Element)
 
(2 intermediate revisions by the same user not shown)
Line 4: Line 4:
  
 
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.
 
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.
  
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|action
 
|class="leftnormal"|action
−
|(Optional) Set – Designates the behavior to be invoked when the action portal is triggered by the user. Must be one of these values:<br>
+
|(Optional) Set – Designates the behavior to be invoked when the action portal is triggered by the user. Must be one of these values:
−
delete – <br>
+
<ul class="sets">
−
info – <br>
+
<li>delete – Deletes the associated pick. Only useful within tables for allowing the user to delete a pick that they added.</li>
−
edit – <br>
+
<li>info – Displays detailed information about the associated pick via the associated MouseInfo script. If no script is defined, default behavior shows the name, failed pre-requisites, and description for the associated pick.</li>
−
form – <br>
+
<li>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.</li>
−
trigger – <br>
+
<li>form – Brings up the modal form specified within the "form" attribute.</li>
−
gear – <br>
+
<li>trigger – Invokes the Trigger script specified via the "trigger" child element.</li>
−
notes – <br>
+
<li>gear – Displays a menu allowing the user to move gear between holders.</li>
−
load – <br>
+
<li>notes – Brings up a form within which the user can edit the contents of the field designated by the "notes" attribute.</li>
−
lock – <br>
+
<li>load – Loads the actor containing the associated pick for manipulation by the user.</li>
−
unlock – <br>
+
<li>lock – Transitions the actor containing the associated pick into advancement mode.</li>
−
master – <br>
+
<li>unlock – Transitions the actor containing the associated pick into creation mode.</li>
−
minion – <br>
+
<li>master – Loads the master of the actor containing the associated pick, making it the active actor.</li>
−
getgear – <br>
+
<li>minion – Loads the minion attached by the associated pick, making it the active actor. If the "minion" attribute specifies a unique id, the designated minion is loaded instead.</li>
−
combatstart – <br>
+
<li>getgear – Displays a menu that allows the user to move gear between actors.</li>
−
combatend – <br>
+
<li>combatstart – Triggers the start of a new combat within the Tactical Console.</li>
−
newturn – <br>
+
<li>combatend – Triggers the end of an existing combat within the Tactical Console.</li>
−
initchange – <br>
+
<li>newturn – Transitions to a new combat turn within the Tactical Console.</li>
−
integrate – <br>
+
<li>initchange – Incorporates user-made changes to the initiatives of actors within the Tactical Console.</li>
−
dashsort – <br>
+
<li>integrate – Integrates all pending actors into an existing combat within the Tactical Console.</li>
−
Default: "delete".
+
<li>dashsort – Triggers a re-sort of all actors shown within the Dashboard.</li>
 +
<li>Default: "delete".</li>
 +
</ul>
 
|-
 
|-
 
|buttontext
 
|buttontext
Line 45: Line 49:
 
|-
 
|-
 
|}
 
|}
−
    -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.  
+
The "action" 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.  
  
 
:{| class="infotable"
 
:{| class="infotable"
−
|class="leftnormal"|[[#choice|choice]]
+
|class="leftnormal"|[[#trigger|trigger]]
−
|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.
+
|An optional "trigger" element may appear as defined by the given link. This element defines a [[Trigger Script]] for the portal.
−
|-
+
−
|[[#change|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{{anchor|choice}}==
+
==The "trigger" Element{{anchor|trigger}}==
  
−
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.
+
The "trigger" element defines a [[Trigger Script]] for the portal that is invoked whenever the user triggers the portal. This script only applies to the "trigger" action type and allows adjustments to be applied to usage pools, such as those for tracking damage, managing journal entries, etc. The complete list of attributes for this element is below.  
−
 
+
−
:{| class="infotable"
+
−
|class="leftnormal"|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{{anchor|change}}==
+
−
 
+
−
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.  
+
  
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|class="leftnormal"|PCDATA
−
|Script – Specifies the code comprising the Change script.
+
|Script – Specifies the code comprising the Trigger script.
 
|-
 
|-
 
|}
 
|}
Line 136: Line 70:
 
==Example==
 
==Example==
  
−
The following example demonstrates what a literal menu portal might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what an action portal might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
−
<portal id="gender" style="menuNormal">
+
<portal id="delete" style="actDelete"
−
   <menu_literal field="perGender">
+
      tiptext="Click to delete this equipment">
−
    <choice value="0" display="Gender: Male"/>
+
   <action action="delete"/>
−
    <choice value="1" display="Gender: Female"/>
+
  </portal>
−
     </menu_literal>
+
 
 +
<portal id="addxp" style="actSmall">
 +
  <action action="trigger" buttontext="Add XP">
 +
    <trigger>
 +
      ~add the XP to both the journal entry's and hero's usage pools
 +
      perform usagepool[JrnlXP].adjust[field[jrnXP].value]
 +
      perform hero.usagepool[TotalXP].adjust[field[jrnXP].value]
 +
      perform field[jrnXP].reset
 +
      </trigger>
 +
     </action>
 
   </portal>
 
   </portal>
 
</pre>
 
</pre>

Latest revision as of 02:31, 4 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 via the associated MouseInfo script. If no script is defined, default behavior shows the name, failed pre-requisites, and description for 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 – Displays a menu allowing the user to move gear between holders.
  • notes – Brings up a form within which the user can edit the contents of the field designated by the "notes" attribute.
  • load – Loads the actor containing the associated pick for manipulation by the user.
  • lock – Transitions the actor containing the associated pick into advancement mode.
  • unlock – Transitions the actor containing the associated pick into creation mode.
  • master – Loads the master of the actor containing the associated pick, making it the active actor.
  • minion – Loads the minion attached by the associated pick, making it the active actor. If the "minion" attribute specifies a unique id, the designated minion is loaded instead.
  • getgear – Displays a menu that allows the user to move gear between actors.
  • combatstart – Triggers the start of a new combat within the Tactical Console.
  • combatend – Triggers the end of an existing combat within the Tactical Console.
  • newturn – Transitions to a new combat turn within the Tactical Console.
  • initchange – Incorporates user-made changes to the initiatives of actors within the Tactical Console.
  • integrate – Integrates all pending actors into an existing combat within the Tactical Console.
  • dashsort – Triggers a re-sort of all actors shown within the Dashboard.
  • 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.

The "action" 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.

trigger An optional "trigger" element may appear as defined by the given link. This element defines a Trigger Script for the portal.

The "trigger" Element

The "trigger" element defines a Trigger Script for the portal that is invoked whenever the user triggers the portal. This script only applies to the "trigger" action type and allows adjustments to be applied to usage pools, such as those for tracking damage, managing journal entries, etc. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the Trigger script.

Example

The following example demonstrates what an action portal might look like. All default values are assumed for optional attributes. 

<portal id="delete" style="actDelete"
      tiptext="Click to delete this equipment">
  <action action="delete"/>
  </portal>

<portal id="addxp" style="actSmall">
  <action action="trigger" buttontext="Add XP">
    <trigger>
      ~add the XP to both the journal entry's and hero's usage pools
      perform usagepool[JrnlXP].adjust[field[jrnXP].value]
      perform hero.usagepool[TotalXP].adjust[field[jrnXP].value]
      perform field[jrnXP].reset
      </trigger>
    </action>
  </portal>
Retrieved from "http://hlkitwiki.wolflair.com/index.php5?title=Action_Element_(Data)&oldid=1233"