Action Element (Data)

From HLKitWiki
Jump to: navigation, search

Context: HL KitKit 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>