Difference between revisions of "MenuThings Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|Kit Reference|Data File Reference|Portal Element (Data)}} ==The "menu_things" Element== The "checkbox" element is useful whenever the user has a choice between two clearly oppo...)
 
Line 3: Line 3:
 
==The "menu_things" Element==
 
==The "menu_things" Element==
  
The "checkbox" element is useful whenever the user has a choice between two clearly opposite states, such as on/off, enable/disable, show/hide, etc. In addition to the traditional visual presentation of text with a box next to it, the Kit allows you to use checkboxes to present to alternate visual states. For example, within the World of Darkness data files, the abilities to promote items to the top of a list and toggle inclusion within printouts are checkboxes that merely toggle between two states and change the visuals accordingly. The complete list of attributes for this element is below.
+
The "menu_things" element is used when the user needs to select an item that exists within the data files. For example, an in-play adjustment can select an attribute or skill that the actor possesses, or an ability can select a weapon type that receives a bonus. The common thread is that the options presented in the menu are either things or picks within the data files. The complete list of attributes for this element is below.
 +
 
 +
{{important}}Within a thing-based menu, the selected thing is '''not''' added to the container as a new pick. The thing is merely identified for reference and can be accessed via the menu, but no new pick appears within the container. Only tables and choosers can actually add new picks to a container.
  
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|field
 
|class="leftnormal"|field
|Id – Specifies the unique id of the field whose contents dictate whether the checkbox is in the on or off state. The field must be a value-based field, with a non-zero value indicating "on" and a zero value indicating "off". The field must exist within the pick/thing associated with the containing template. If this portal is not defined within a template, a checkbox is not allowed.
+
|Id – Specifies the unique id of the field whose contents reflect the current selection from the menu. The field must be a value-based field of style "menu" and must exist within the pick/thing associated with the containing template. If this portal is not defined within a template, a menu is not allowed.
 
|-
 
|-
|message
+
|component
|(Optional) Text – Specifies the message text to display next to the actual box. If empty, no text is displayed. Default: Empty.
+
|Id – Specifies the unique id of the component that all choices must be derived from.
 
|-
 
|-
|dyanamicfield
+
|defthing
|(Optional) Id – Specifies the unique id of a different field from which the message text will be pulled. This allows the message text to be dynamically determined via scripts. If empty, no dynamic field is specified. Default: Empty.
+
|(Optional) Id – Specifies the unique id of the thing to pre-select as the default choice within the menu. If empty, no default selection is made. Default: Empty.
 
|-
 
|-
|readonly
+
|usepicks
|(Optional) Boolean Indicates whether the checkbox portal is unable to be changed by the user. Default: "no".
+
|(Optional) Set Designates whether the menu is populated with things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:<br>
 +
thing – The menu is populated with things.<br>
 +
container – The menu is populated with picks from the container of the pick associated with the template.<br>
 +
hero – The menu is populated with picks from the actor.<br>
 +
actor – Same as "hero".<br>
 +
Default: "thing".
 +
|-
 +
|sortset
 +
|(Optional) Id – Specifies the unique id of the sort set to be used to determine the sequence in which the items are listed in the menu. If empty, the items are listed alphabetically. Default: Empty.
 +
|-
 +
|maxvisible
 +
|(Optional) Integer – Specifies the maximum number of items that will be visible at one time within the menu when the user opens it for selection. If there are more items to choose from, a scroller will allow the user to access them. Default: "5".
 +
|-
 +
|usepicksfield
 +
|(Optional) Id – Specifies the unique id of a value-based field that dynamically dictates when the menu is populated with things or picks. If empty, the "usepicks" attribute dictates the behavior. If specified, the field value dictates the behavior according to the list below. Default: Empty.
 +
0 – The menu is populated with things.<br>
 +
1 – The menu is populated with picks from the container of the pick associated with the template.<br>
 +
2 – The menu is populated with picks from the actor.
 +
|-
 +
|candidatefield
 +
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] to be used when populating the menu options. Default: Empty.<br>
 +
{{important}}This mechanism is secondary to the "candidate" element, so the field is '''ignored''' if the "candidate" element is non-empty.
 +
|-
 +
|}
 +
-Added the optional "restriction" tagexpr to table-based selection portals
 +
    -When omitted, contents of tables are governed normally, with all things being
 +
        included except for unique things that already exist in the container
 +
        -Unique things are NEVER allowed to be duplicated within a container
 +
    -When specified, the additional restriction is imposed on contents of table, where
 +
        any pick/thing that satisfies the tagexpr AND has already been added to that
 +
        table will be omitted from the list presented (i.e. can only be added once)
 +
    -Allows things to be unique within a given table, which means that the same spell
 +
        can be added multiple times via different tables for different classes, so
 +
        the same spell list can be re-used for different classes
 +
 
 +
The "menu_things" 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="leftnormal"|[[#candidate|candidate]]
 +
|A single "candidate" element must appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the portal.
 +
|-
 +
|[[#restriction|restriction]]
 +
|An optional "restriction" elements must appear as defined by the given link. This element defines a secondary [[Candidate Tag Expression]] for the portal that must also be satisfied. The restriction is only used when the Candidate tag expression is specified via a field.
 +
|-
 +
|[[#change|change]]
 +
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the portal.
 +
|-
 +
|}
 +
 
 +
==The "candidate" Element{{anchor|candidate}}==
 +
 
 +
The "candidate" element defines a primary [[Candidate Tag Expression]] for the portal that limits the set of things/picks that are available for selection. The complete list of attributes for this element is below.
 +
 
 +
:{| class="infotable"
 +
|class="leftnormal"|PCDATA
 +
|TagExpr – Specifies the code comprising the primary Candidate tag expression.
 +
|-
 +
|}
 +
 
 +
==The "restriction" Element{{anchor|restriction}}==
 +
 
 +
The "restriction" element defines a secondary [[Candidate Tag Expression]] for the portal that further limits the set of things/picks that are available for selection. This tag expression is only utilized if the primary Candidate tag expression is determined via a field. The complete list of attributes for this element is below.
 +
 
 +
:{| class="infotable"
 +
|class="leftnormal"|PCDATA
 +
|TagExpr – Specifies the code comprising the secondary Candidate tag expression.
 +
|-
 +
|}
 +
 
 +
==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="leftnormal"|PCDATA
 +
|Script – Specifies the code comprising the Change script.
 
|-
 
|-
 
|}
 
|}
Line 22: Line 99:
 
==Example==
 
==Example==
  
The following example demonstrates what a checkbox portal might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what a thing-based menu portal might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
<portal id="name" style="chkNormal" showinvalid="yes"
+
<portal id="menu" style="menuNormal">
      tiptext="Click to equip this weapon">
+
  <menu_things field="adjChosen" component="none" maxvisible="20"
  <checkbox field="grIsEquip" dynamicfield="grStkName"/>
+
        usepicksfield="adjUsePick" candidatefield="adjCandid">
 +
    <candidate></candidate>
 +
    </menu_things>
 
   </portal>
 
   </portal>
 
</pre>
 
</pre>

Revision as of 00:10, 2 December 2008

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

The "menu_things" Element

The "menu_things" element is used when the user needs to select an item that exists within the data files. For example, an in-play adjustment can select an attribute or skill that the actor possesses, or an ability can select a weapon type that receives a bonus. The common thread is that the options presented in the menu are either things or picks within the data files. The complete list of attributes for this element is below.

IMPORTANT! Within a thing-based menu, the selected thing is not added to the container as a new pick. The thing is merely identified for reference and can be accessed via the menu, but no new pick appears within the container. Only tables and choosers can actually add new picks to a container.

field Id – Specifies the unique id of the field whose contents reflect the current selection from the menu. The field must be a value-based field of style "menu" and must exist within the pick/thing associated with the containing template. If this portal is not defined within a template, a menu is not allowed.
component Id – Specifies the unique id of the component that all choices must be derived from.
defthing (Optional) Id – Specifies the unique id of the thing to pre-select as the default choice within the menu. If empty, no default selection is made. Default: Empty.
usepicks (Optional) Set – Designates whether the menu is populated with things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:

thing – The menu is populated with things.
container – The menu is populated with picks from the container of the pick associated with the template.
hero – The menu is populated with picks from the actor.
actor – Same as "hero".
Default: "thing".

sortset (Optional) Id – Specifies the unique id of the sort set to be used to determine the sequence in which the items are listed in the menu. If empty, the items are listed alphabetically. Default: Empty.
maxvisible (Optional) Integer – Specifies the maximum number of items that will be visible at one time within the menu when the user opens it for selection. If there are more items to choose from, a scroller will allow the user to access them. Default: "5".
usepicksfield (Optional) Id – Specifies the unique id of a value-based field that dynamically dictates when the menu is populated with things or picks. If empty, the "usepicks" attribute dictates the behavior. If specified, the field value dictates the behavior according to the list below. Default: Empty.

0 – The menu is populated with things.
1 – The menu is populated with picks from the container of the pick associated with the template.
2 – The menu is populated with picks from the actor.

candidatefield (Optional) Id – Specifies the unique id of a text-based field that contains the Candidate tag expression to be used when populating the menu options. Default: Empty.

IMPORTANT! This mechanism is secondary to the "candidate" element, so the field is ignored if the "candidate" element is non-empty.

-Added the optional "restriction" tagexpr to table-based selection portals

   -When omitted, contents of tables are governed normally, with all things being
       included except for unique things that already exist in the container
       -Unique things are NEVER allowed to be duplicated within a container
   -When specified, the additional restriction is imposed on contents of table, where
       any pick/thing that satisfies the tagexpr AND has already been added to that
       table will be omitted from the list presented (i.e. can only be added once)
   -Allows things to be unique within a given table, which means that the same spell
       can be added multiple times via different tables for different classes, so
       the same spell list can be re-used for different classes

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

candidate A single "candidate" element must appear as defined by the given link. This element defines a Candidate Tag Expression for the portal.
restriction An optional "restriction" elements must appear as defined by the given link. This element defines a secondary Candidate Tag Expression for the portal that must also be satisfied. The restriction is only used when the Candidate tag expression is specified via a field.
change An optional "change" element may appear as defined by the given link. This element defines a Change Script for the portal.

The "candidate" Element

The "candidate" element defines a primary Candidate Tag Expression for the portal that limits the set of things/picks that are available for selection. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the primary Candidate tag expression.

The "restriction" Element

The "restriction" element defines a secondary Candidate Tag Expression for the portal that further limits the set of things/picks that are available for selection. This tag expression is only utilized if the primary Candidate tag expression is determined via a field. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the secondary Candidate tag expression.

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 thing-based menu portal might look like. All default values are assumed for optional attributes.

<portal id="menu" style="menuNormal">
  <menu_things field="adjChosen" component="none" maxvisible="20"
        usepicksfield="adjUsePick" candidatefield="adjCandid">
    <candidate></candidate>
    </menu_things>
  </portal>