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...)
 
(The "menu_things" Element)
 
(9 intermediate revisions by one other user not shown)
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:
 +
<ul class="sets">
 +
<li>thing – The menu is populated with things.</li>
 +
<li>container – The menu is populated with picks from the container of the pick associated with the template.</li>
 +
<li>hero – The menu is populated with picks from the actor.</li>
 +
<li>actor – Same as "hero".</li>
 +
<li>Default: "thing".</li>
 +
</ul>
 +
|-
 +
|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.
 +
<ul class="sets">
 +
<li>0 – The menu is populated with things.</li>
 +
<li>1 – The menu is populated with picks from the container of the pick associated with the template.</li>
 +
<li>2 – The menu is populated with picks from the actor.</li>
 +
</ul>
 +
|-
 +
|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.
 +
|-
 +
|namefield
 +
|(Optional) Id - Specifies the unique id of a text-based field that is used instead of the "name" of each thing shown within the array. This makes it possible to customize the name to be displayed in the menu differently from the standard name shown for the thing.
 +
|-
 +
|showlabel
 +
|(Optional) Boolean – (iPad only) Indicates whether the label displaying the current selection of the menu should be shown. This is used when you just want the menu control to be used as a button to make a selection which will be displayed some other way. Default: "yes".
 +
|-
 +
|}
 +
 
 +
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]]
 +
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] 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 "candidate" Element{{anchor|candidate}}==
 +
 
 +
The "candidate" element defines a [[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 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 86:
 
==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>

Latest revision as of 21:53, 19 December 2013

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.

namefield (Optional) Id - Specifies the unique id of a text-based field that is used instead of the "name" of each thing shown within the array. This makes it possible to customize the name to be displayed in the menu differently from the standard name shown for the thing.
showlabel (Optional) Boolean – (iPad only) Indicates whether the label displaying the current selection of the menu should be shown. This is used when you just want the menu control to be used as a button to make a selection which will be displayed some other way. Default: "yes".

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 An optional "candidate" element may appear as defined by the given link. This element defines a Candidate Tag Expression for the portal.
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 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 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>