Difference between revisions of "Portal Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{contextmulti|Kit Reference|Data File Reference}} ==The "portal" Element== Within the hierarchy of visual elements, the individual elements that the user interacts with are [[Portals|po...)
 
(The "portal" Element)
 
(11 intermediate revisions by the same user not shown)
Line 17: Line 17:
 
|isheader
 
|isheader
 
|(Optional) Boolean – Indicates whether this portal is utilized within a [[Dual-purpose Headers on Tables|dual-purpose header]] as part of a table. Default: "no".<br>
 
|(Optional) Boolean – Indicates whether this portal is utilized within a [[Dual-purpose Headers on Tables|dual-purpose header]] as part of a table. Default: "no".<br>
{{note}}This attribute is only permitted on portals within templates that serves as dual-purpose headers.
+
{{note}}This attribute is only permitted on portals within templates that serves as dual-purpose headers.<br>
 +
{{note}}Field-based portals may '''never''' be designated for use within a header, as there is no pick/thing associated with dual-purpose templates.
 
|-
 
|-
 
|showinvalid
 
|showinvalid
Line 24: Line 25:
 
|showdisabled
 
|showdisabled
 
|(Optional) Boolean – Indicates whether the text used within the portal should be automatically changed to the built-in "lbldisable" color when the portal references a pick whose pre-requisites are not satisfied. This behavior only applies to suitable portal types, including labels, incrementers, checkboxes, and menus. Default: "yes".
 
|(Optional) Boolean – Indicates whether the text used within the portal should be automatically changed to the built-in "lbldisable" color when the portal references a pick whose pre-requisites are not satisfied. This behavior only applies to suitable portal types, including labels, incrementers, checkboxes, and menus. Default: "yes".
 +
|-
 +
|width
 +
|(Optional) Integer – Specifies the default width to use for the portal. In general, portal dimensions should only be controlled via the Position script of the containing visual element. If zero, the default auto-sizing behaviors are employed. Default: "0".
 +
|-
 +
|height
 +
|(Optional) Integer – Specifies the default height to use for the portal. In general, portal dimensions should only be controlled via the Position script of the containing visual element. If zero, the default auto-sizing behaviors are employed. Default: "0".
 
|-
 
|-
 
|}
 
|}
Line 29: Line 36:
 
The "portal" element also possesses child elements that define the specifics 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 "portal" element also possesses child elements that define the specifics 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.
  
{{important}}With the exception of the "live" and "mouseinfo" elements, exactly '''one''' of these child elements may be specified for each portal. If multiple are given, a compiler error will be reported. The chosen child element dictates the type of portal that is being defined. You may include up to one "live" and/or "mouseinfo" elements after the single child element that specifies the portal.
+
{{important}}With the exception of the "live" and "mouseinfo" elements, exactly '''one''' of these child elements may be specified for each portal. If multiple are given, a compiler error will be reported. The chosen child element dictates the type of portal that is being defined and its characteristics. You may include up to one "live" and/or "mouseinfo" elements after the single child element that specifies the portal.
  
 
:{| class="infotable"
 
:{| class="infotable"
Line 53: Line 60:
 
|An optional "edit" element may appear as defined by the given link. This element specifies the details of an edit portal.
 
|An optional "edit" element may appear as defined by the given link. This element specifies the details of an edit portal.
 
|-
 
|-
|{{flalt|Label Element (Data)|label}}
+
|{{flalt|EditDate Element (Data)|edit_date}}
|An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
+
|An optional "edit_date" element may appear as defined by the given link. This element specifies the details of an editdate portal.
 
|-
 
|-
|{{flalt|Label Element (Data)|label}}
+
|{{flalt|Checkbox Element (Data)|checkbox}}
|An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
+
|An optional "checkbox" element may appear as defined by the given link. This element specifies the details of a checkbox portal.
 
|-
 
|-
|{{flalt|Label Element (Data)|label}}
+
|{{flalt|MenuLiteral Element (Data)|menu_literal}}
|An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
+
|An optional "menu_literal" element may appear as defined by the given link. This element specifies the details of a menu portal consisting of a fixed set of options.
 
|-
 
|-
|{{flalt|Label Element (Data)|label}}
+
|{{flalt|MenuArray Element (Data)|menu_array}}
|An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
+
|An optional "menu_array" element may appear as defined by the given link. This element specifies the details of an array-based menu portal.
 
|-
 
|-
|{{flalt|Label Element (Data)|label}}
+
|{{flalt|MenuThings Element (Data)|menu_things}}
|An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
+
|An optional "menu_things" element may appear as defined by the given link. This element specifies the details of a thing-based menu portal.
 
|-
 
|-
|[[Resource Element (Data)|resource]]
+
|{{flalt|Action Element (Data)|action}}
|Zero or more "resource" elements may appear as defined by the given link. This element specifies new resources that are used in conjunction with the style.
+
|An optional "action" element may appear as defined by the given link. This element specifies the details of an action portal.
 
|-
 
|-
|}
+
|{{flalt|Region Element (Data)|region}}
 
+
|An optional "region" element may appear as defined by the given link. This element specifies the details of a region portal.
==Colors in Styles{{anchor|colors}}==
+
 
+
Many styles allow you to directly specify a color value in the format "xxxxxx". The format for the color uses standard HTML color syntax, with each character representing a hexadecimal digit. The first two characters define the Red color value, the next two Green, and the last two Blue. For example, the color "ff0080" specifies a Red value of "ff", a Green value of "00", and a Blue value of "80".
+
 
+
For additional details on specifying colors via the HTML syntax, please refer to one of the many websites that provide this information, such as
+
[http://www.w3schools.com/Html/html_colors.asp http://www.w3schools.com/Html/html_colors.asp].
+
 
+
==Scaling of Images{{anchor|scaling}}==
+
 
+
When encoded text is supported within a category of portal, you will typically be given control over the scaling of images within the corresponding style. When enabled, image scaling is applied to all bitmaps that are inserted into the encoded text that is rendered into the portal. The scaling ratio is based on the difference between the initial font size for the portal and the current font size at which the text is now being rendered. Scaling is valuable for when you want to ensure that the bitmaps remain proportionally sized relative to the font size of the text, which is important when text and bitmaps are interleaved within the encoded text.
+
 
+
==The "style_label" Element{{anchor|label}}==
+
 
+
The "style_label" element defines the facets of a style for label portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
 
|-
 
|-
|textcolor
+
|{{flalt|Separator Element (Data)|separator}}
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|An optional "separator" element may appear as defined by the given link. This element specifies the details of a separator portal.
 
|-
 
|-
|textcolorid
+
|{{flalt|ChooserTable Element (Data)|chooser_table}}
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|An optional "chooser_table" element may appear as defined by the given link. This element specifies the details of a table-based chooser portal.
 
|-
 
|-
|background
+
|{{flalt|TableFixed Element (Data)|table_fixed}}
|(Optional) Id – Unique id of the bitmap resource to use as the background. If omitted, the text is drawn transparently on the existing background region. Default: Empty.
+
|An optional "table_fixed" element may appear as defined by the given link. This element specifies the details of a non-editable table portal.
 
|-
 
|-
|alignment
+
|{{flalt|TableDynamic Element (Data)|table_dynamic}}
|(Optional) Set – Specifies how the text should be horizontally aligned within the portal width. Must be one of these values:<br>
+
|An optional "table_dynamic" element may appear as defined by the given link. This element specifies the details of a table portal to which the user can add arbitrary items.
left – Text is left-aligned.<br>
+
center – Text is centered within the portal.<br>
+
right – Text is right-aligned.<br>
+
Default: "left".
+
 
|-
 
|-
|ispattern
+
|{{flalt|TableAuto Element (Data)|table_auto}}
|(Optional) Boolean – Indicates whether the background bitmap should be centered within the portal dimensions or tiled to fill the entire portal. Default: "yes".
+
|An optional "table_auto" element may appear as defined by the given link. This element specifies the details of a table portal to which a specific item can be added.
 
|-
 
|-
|scaleimage
+
|{{flalt|SettingEdit Element (Data)|setting_edit}}
|(Optional) Boolean – Indicates whether bitmaps included within encoded text are scaled ([[#scaling|see above]]). Default: "no".
+
|An optional "setting_edit" element may appear as defined by the given link. This element specifies the details of a special portal for editing configuration settings.
 
|-
 
|-
|}
+
|{{flalt|SettingSummary Element (Data)|setting_summary}}
 
+
|An optional "setting_summary" element may appear as defined by the given link. This element specifies the details of a special portal for showing a summary of configuration settings.
==The "style_image" Element{{anchor|image}}==
+
 
+
The "style_image" element defines the facets of a style for image portals. Since image portals simply contain the image and nothing else, there are no special attributes for this element.
+
 
+
==The "style_edit" Element{{anchor|edit}}==
+
 
+
The "style_edit" element defines the facets of a style for edit portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
 
|-
 
|-
|textcolor
+
|{{flalt|Alliance Element (Data)|alliance}}
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|An optional "alliance" element may appear as defined by the given link. This element specifies the details of a special portal for controlling the alliance state of an actor.
 
|-
 
|-
|textcolorid
+
|{{flalt|OutputLabel Element (Data)|output_label}}
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|An optional "output_label" element may appear as defined by the given link. This element specifies the details of a label portal for sheet output.
 
|-
 
|-
|backcolor
+
|{{flalt|OutputImage Element (Data)|output_image}}
|(Optional) Text – Color value to be used as the background in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "backcolorid" attribute must be specified. Default: Empty.
+
|An optional "output_image" element may appear as defined by the given link. This element specifies the details of an image portal for sheet output.
 
|-
 
|-
|backcolorid
+
|{{flalt|OutputTable Element (Data)|output_table}}
|(Optional) Id – Unique id of the color resource to be used as the background. If omitted, the "backcolor" attribute must be specified. Default: Empty.
+
|An optional "output_table" element may appear as defined by the given link. This element specifies the details of a table portal for sheet output.
 
|-
 
|-
|alignment
+
|{{flalt|OutputDots Element (Data)|output_dots}}
|(Optional) Set – Specifies how the text should be horizontally aligned within the portal width. Must be one of these values:<br>
+
|An optional "output_dots" element may appear as defined by the given link. This element specifies the details of a special label portal for sheet output.
left – Text is left-aligned.<br>
+
center – Text is centered within the portal.<br>
+
right – Text is right-aligned.<br>
+
Default: "left".
+
 
|-
 
|-
|autoselect
+
|{{flalt|OutputSeparator Element (Data)|output_separator}}
|(Optional) Set – Indicates whether to automatically select the entire text contents of the portal when it gains the focus. Must be one of the following:<br>
+
|An optional "output_separator" element may appear as defined by the given link. This element specifies the details of a separator portal for sheet output.
yes – Contents are always automatically selected when focus is gained.<br>
+
no – Contents are never selected when focus is gained.<br>
+
default – Default handling is performed. If the edit portal contains a numeric field, the contents are automatically selected, but no selection is performed for text-based fields.
+
Default: "default".
+
 
|-
 
|-
|itemborder
+
|[[#live|live]]
|(Optional) Id – Unique id of the border resource to draw around each individual edit cell for an "edit_date" portal. If "none", no border is drawn. Default: "none".
+
|An optional "live" element may appear as defined by the given link. This element defines a [[Live Tag Expression]] for the portal.
 
|-
 
|-
|septext
+
|[[#mouseinfo|mouseinfo]]
|(Optional) Text – Specifies the text to be drawn between each individual edit cell for an "edit_date" portal. Default: "/".
+
|An optional "mouseinfo" element may appear as defined by the given link. This element defines a [[MouseInfo Script]] for the portal.
|-
+
|sepfont
+
|(Optional) Id – Unique id of the font resource to be used for drawing the separator text between individual cells for an "edit_date" portal. If empty, the resource specified by the "font" attribute is assumed. Default: Empty.
+
|-
+
|sepcolor
+
|(Optional) Text – Color value to be used for drawing the separator text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "sepcolorid" attribute must be specified. Default: Empty.
+
|-
+
|sepcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing the separator text. If omitted, the "sepcolor" attribute must be specified. Default: Empty.
+
 
|-
 
|-
 
|}
 
|}
  
==The "style_checkbox" Element{{anchor|checkbox}}==
+
==The "live" Element{{anchor|live}}==
  
The "style_checkbox" element defines the facets of a style for checkbox portals. The complete list of attributes for this element is below.  
+
The "live" element defines a [[Live Tag Expression]] for the portal that determines whether the portal is applicable based on the prevailing conditions. In general, portals should be controlled via scripts using the "visible" target reference instead of using this mechanism. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|font
+
|class="leftnormal"|PCDATA
|Id Unique id of the font resource to be used for the style.
+
|TagExpr Specifies the code comprising the Live tag expression.
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|scaleimage
+
|(Optional) Boolean – Indicates whether bitmaps included within encoded text are scaled ([[#scaling|see above]]). Default: "no".
+
|-
+
|check
+
|(Optional) Id – Unique id of the bitmap resource used to indicate the box is checked. If omitted, a default bitmap it used. Default: Empty.
+
|-
+
|checkoff
+
|(Optional) Id – Unique id of the bitmap resource used to indicate the box is checked when the portal is disabled. If omitted, a default bitmap it used. Default: Empty.
+
|-
+
|uncheck
+
|(Optional) Id – Unique id of the bitmap resource used to indicate the box is not checked. If omitted, a default bitmap it used. Default: Empty.
+
|-
+
|uncheckoff
+
|(Optional) Id – Unique id of the bitmap resource used to indicate the box is not checked when the portal is disabled. If omitted, a default bitmap it used. Default: Empty.
+
 
|-
 
|-
 
|}
 
|}
  
==The "style_menu" Element{{anchor|menu}}==
+
==The "mouseinfo" Element{{anchor|mouseinfo}}==
  
The "style_menu" element defines the facets of a style for menu portals. The complete list of attributes for this element is below.  
+
The "mouseinfo" element defines a [[MouseInfo Script]] for the portal that synthesizes text for display to the user whenever the user pauses the mouse over the portal. The complete list of attributes for this element is below.  
  
 
:{| class="infotable"
 
:{| class="infotable"
|class="leftnormal"|font
+
|class="leftnormal"|PCDATA
|Id – Unique id of the font resource to be used for the style.
+
|Script – Specifies the code comprising the MouseInfo script.
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|backcolor
+
|(Optional) Text – Color value to be used as the background in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "backcolorid" attribute must be specified. Default: Empty.
+
|-
+
|backcolorid
+
|(Optional) Id – Unique id of the color resource to be used as the background. If omitted, the "backcolor" attribute must be specified. Default: Empty.
+
|-
+
|selecttext
+
|(Optional) Text – Color value to be used for drawing text of the selected item when the menu is "dropped" in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "selecttextid" attribute must be specified. Default: Empty.
+
|-
+
|selecttextid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text of the selected item when the menu is "dropped". If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|selectback
+
|(Optional) Text – Color value to be used as the background of the selected item when the menu is "dropped" in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "selectbackid" attribute must be specified. Default: Empty.
+
|-
+
|selectbackid
+
|(Optional) Id – Unique id of the color resource to be used as the background of the selected item when the menu is "dropped". If omitted, the "backcolor" attribute must be specified. Default: Empty.
+
|-
+
|activetext
+
|(Optional) Text – Color value to be used for drawing text of the selected item in the format "xxxxxx" ([[#colors|see above]]). This color is only used within the "non-dropped" region of the menu and allows the color highlighting of invalid menu items without impacting the behavior of the "dropped" menu. If omitted, the "selectbackid" attribute may be specified. If neither color is specified, the "selecttext" color is used. Default: Empty.
+
|-
+
|activetextid
+
|(Optional) Id – Unique id of the color resource to be used as the background of the selected item. See the "activetext" attribute above for further details. If omitted, the "activetext" attribute may be specified. Default: Empty.
+
|-
+
|scaleimage
+
|(Optional) Boolean – Indicates whether bitmaps included within encoded text are scaled ([[#scaling|see above]]). Default: "no".
+
|-
+
|}
+
 
+
==The "style_action" Element{{anchor|action}}==
+
 
+
The "style_action" element defines the facets of a style for action portals (typically used as clickable buttons). The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|up
+
|Id – Unique id of the bitmap resource to be used as the "up" state of the action portal.
+
|-
+
|down
+
|Id – Unique id of the bitmap resource to be used as the "down" state of the action portal.
+
|-
+
|off
+
|Id – Unique id of the bitmap resource to be used as the "up" state of the action portal when the portal is disabled.
+
|-
+
|xoffset
+
|(Optional) Integer – Specifies the offset adjustment of any text along the horizontal X axis. The text is centered along the axis and can be shifted left or right via this attribute, with positive values shifting to the right and negative values shifting left. Default: "0".
+
|-
+
|yoffset
+
|(Optional) Integer – Specifies the offset adjustment of any text along the vertical Y axis. The text is centered along the axis and can be shifted up or down via this attribute, with positive values shifting downward and negative values shifting upward. Default: "0".
+
|-
+
|}
+
 
+
==The "style_incrementer" Element{{anchor|incrementer}}==
+
 
+
The "style_incrementer" element defines the facets of a style for incrementer portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|(Optional) background
+
|Id – Unique id of the bitmap resource to be used as the background. If empty, the portal has no background and is drawn transparently. Default: Empty.
+
{{note}}If a background bitmap is specified, the incrementer size is dictated by the dimensions of the bitmap. If not specified, then the dimensions must be specified via the "fullwidth" and "fullheight" attributes.
+
|-
+
|fullwidth
+
|(Optional) Integer – Specifies the fixed width to utilize for all incrementers assigned this style. If "0", a background must be specified to dictate the dimensions. Default: "0".
+
|-
+
|fullheight
+
|(Optional) Integer – Specifies the fixed height to utilize for all incrementers assigned this style. If "0", a background must be specified to dictate the dimensions. Default: "0".
+
|-
+
|textleft
+
|Integer – Specifies the left edge of the region in which text is drawn within the incrementer.
+
|-
+
|texttop
+
|Integer – Specifies the top edge of the region in which text is drawn within the incrementer.
+
|-
+
|textwidth
+
|Integer – Specifies the width of the region in which text is drawn within the incrementer.
+
|-
+
|textheight
+
|Integer – Specifies the height of the region in which text is drawn within the incrementer.
+
|-
+
|plusup
+
|Id – Unique id of the bitmap resource to be used for the "+" button in its "up" state.
+
|-
+
|plusdown
+
|Id – Unique id of the bitmap resource to be used for the "+" button in its "down" state.
+
|-
+
|plusoff
+
|Id – Unique id of the bitmap resource to be used for the "+" button in its "up" state when the incrementer is disabled.
+
|-
+
|plusx
+
|Integer – Specifies the offset along the horizontal X axis where the "+" button is positioned within the overall incrementer portal.
+
|-
+
|plusy
+
|Integer – Specifies the offset along the vertical Y axis where the "+" button is positioned within the overall incrementer portal.
+
|-
+
|minusup
+
|Id – Unique id of the bitmap resource to be used for the "-" button in its "up" state.
+
|-
+
|minusdown
+
|Id – Unique id of the bitmap resource to be used for the "-" button in its "down" state.
+
|-
+
|minusoff
+
|Id – Unique id of the bitmap resource to be used for the "-" button in its "up" state when the incrementer is disabled.
+
|-
+
|minusx
+
|Integer – Specifies the offset along the horizontal X axis where the "-" button is positioned within the overall incrementer portal.
+
|-
+
|minusy
+
|Integer – Specifies the offset along the vertical Y axis where the "-" button is positioned within the overall incrementer portal.
+
|-
+
|editable
+
|(Optional) Boolean – Indicates whether the incrementer value can be directly user-edited by clicking within the value region. Disabling this can be useful when the value does not correspond to what is displayed, such as when selecting a die type (e.g. d6, d8, d10). Default: "yes".
+
|-
+
|scaleimage
+
|(Optional) Boolean – Indicates whether bitmaps included within encoded text are scaled ([[#scaling|see above]]). Default: "no".
+
|-
+
|}
+
 
+
==The "style_chooser" Element{{anchor|chooser}}==
+
 
+
The "style_chooser" element defines the facets of a style for chooser portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|backcolor
+
|(Optional) Text – Color value to be used as the background in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "backcolorid" attribute must be specified. Default: Empty.
+
|-
+
|backcolorid
+
|(Optional) Id – Unique id of the color resource to be used as the background. If omitted, the "backcolor" attribute must be specified. Default: Empty.
+
|-
+
|scaleimage
+
|(Optional) Boolean – Indicates whether bitmaps included within encoded text are scaled ([[#scaling|see above]]). Default: "no".
+
|-
+
|}
+
 
+
==The "style_region" Element{{anchor|region}}==
+
 
+
The "style_region" element defines the facets of a style for region portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|(Optional) background
+
|Id – Unique id of the bitmap resource to be used as the background for the region. If empty, the portal has no background and is drawn transparently. Default: Empty.
+
|-
+
|}
+
 
+
==The "style_table" Element{{anchor|table}}==
+
 
+
The "style_table" element defines the facets of a style for table portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|(Optional) background
+
|Id – Unique id of the bitmap resource to be used as the background for the table. If empty, the portal has no background and is drawn transparently. Default: Empty.
+
|-
+
|itemborder
+
|(Optional) Id – Unique id of the bitmap resource to be used as a border around each individual item inside the table. If empty, no border is drawn. Default: Empty.
+
|-
+
|showgridhorz
+
|(Optional) Boolean – Indicates whether horizontal grid lines should be drawn between each item within the table. Default: "no".
+
|-
+
|showgridvert
+
|(Optional) Boolean – Indicates whether vertical grid lines should be drawn between each item within the table. Default: "no".
+
|-
+
|gridwidth
+
|(Optional) Integer – Thickness of the grid lines drawn between items within the table (in pixels). The thickness of both horizontal and vertical grid lines is always the same. Default: "1".
+
|-
+
|gridcolor
+
|(Optional) Text – Color value to be used for drawing grid lines in the format "xxxxxx" ([[#colors|see above]]). Default: "888888".
+
|-
+
|gridcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing grid lines. If specified, the default value for the "gridcolor" attribute is ignored. Default: Empty.
+
|-
+
|}
+
 
+
==The "style_separator" Element{{anchor|separator}}==
+
 
+
The "style_separator" element defines the facets of a style for separator portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|isvertical
+
|(Optional) Boolean – Indicates whether the separator is oriented vertically or horizontally. Default: "no".
+
|-
+
|start
+
|Id – Unique id of the bitmap resource to be used at the left/top end of the separator.
+
|-
+
|end
+
|Id – Unique id of the bitmap resource to be used at the right/bottom end of the separator.
+
|-
+
|center
+
|Id – Unique id of the bitmap resource to be used in the middle of the separator. This bitmap is tiled as necessary to fill the entire span of the separator.
+
|-
+
|}
+
 
+
==The "style_special" Element{{anchor|special}}==
+
 
+
The "style_special" element defines the facets of a style for special portals. Due to its nature, there are no attributes for this element.
+
 
+
==The "style_output" Element{{anchor|output}}==
+
 
+
The "style_output" element defines the facets of a style for output portals. The complete list of attributes for this element is below.
+
 
+
:{| class="infotable"
+
|class="leftnormal"|font
+
|Id – Unique id of the font resource to be used for the style.
+
|-
+
|textcolor
+
|(Optional) Text – Color value to be used for drawing text in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "textcolorid" attribute must be specified. Default: Empty.
+
|-
+
|textcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing text. If omitted, the "textcolor" attribute must be specified. Default: Empty.
+
|-
+
|backcolor
+
|(Optional) Text – Color value to be used as the background in the format "xxxxxx" ([[#colors|see above]]). If omitted, the "backcolorid" attribute must be specified. Default: Empty.
+
|-
+
|backcolorid
+
|(Optional) Id – Unique id of the color resource to be used as the background. If omitted, the "backcolor" attribute must be specified. Default: Empty.
+
|-
+
|alignment
+
|(Optional) Set – Specifies how the text should be horizontally aligned within the portal width (for labels). Must be one of these values:<br>
+
left – Text is left-aligned.<br>
+
center – Text is centered within the portal.<br>
+
right – Text is right-aligned.<br>
+
Default: "left".
+
|-
+
|(Optional) background
+
|Id – Unique id of the bitmap resource to be used as the background for tables. If empty, the portal has no background and is drawn transparently. Default: Empty.
+
|-
+
|itemborder
+
|(Optional) Id – Unique id of the bitmap resource to be used as a border around each individual item inside a table. If empty, no border is drawn. Default: Empty.
+
|-
+
|showgridhorz
+
|(Optional) Boolean – Indicates whether horizontal grid lines should be drawn between each item within a table. Default: "no".
+
|-
+
|showgridvert
+
|(Optional) Boolean – Indicates whether vertical grid lines should be drawn between each item within a table. Default: "no".
+
|-
+
|gridwidth
+
|(Optional) Integer – Thickness of the grid lines drawn between items within a table (in pixels). The thickness of both horizontal and vertical grid lines is always the same. Default: "1".
+
|-
+
|gridcolor
+
|(Optional) Text – Color value to be used for drawing grid lines in the format "xxxxxx" ([[#colors|see above]]). Default: "888888".
+
|-
+
|gridcolorid
+
|(Optional) Id – Unique id of the color resource to be used for drawing grid lines. If specified, the default value for the "gridcolor" attribute is ignored. Default: Empty.
+
 
|-
 
|-
 
|}
 
|}
Line 488: Line 150:
 
==Example==
 
==Example==
  
The following example demonstrates what various "style" elements might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what various "portal" elements might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
<style id="label">
+
<portal id="hair" style="editNormal">
  <style_label textcolor="f0f0f0" font="fntnormal" alignment="center"/>
+
   <edit field="perHair"/>
   </style>
+
   </portal>
 
+
<style id="edit" border="sunken">
+
  <style_edit textcolor="d2d2d2" backcolor="000000" font="fntedit" alignment="center"/>
+
   </style>
+
 
+
<style id="increment">
+
  <style_incrementer textcolor="f0f0f0" font="fntincrsim"
+
      textleft="13" texttop="0" textwidth="24" textheight="20"
+
      fullwidth="50" fullheight="20"
+
      plusup="incplusup" plusdown="incplusdn" plusoff="incplusof"
+
      plusx="39" plusy="0"
+
      minusup="incminusup" minusdown="incminusdn" minusoff="incminusof"
+
      minusx="0" minusy="0">
+
      </style_incrementer>
+
  </style>
+
 
+
<style id="action">
+
  <style_action textcolor="000088" font="fntactbig"
+
      up="actbigup" down="actbigdn" off="actbigof">
+
    </style_action>
+
  <resource id="actbigup" isbuiltin="yes">
+
    <bitmap bitmap="button_big_up.bmp"/>
+
    </resource>
+
  <resource id="actbigdn" isbuiltin="yes">
+
    <bitmap bitmap="button_big_down.bmp"/>
+
    </resource>
+
  <resource id="actbigof" isbuiltin="yes">
+
    <bitmap bitmap="button_big_off.bmp"/>
+
    </resource>
+
  </style>
+
 
+
<style id="table" border="brdsystem">
+
  <style_table itemborder="sunken" showgridhorz="yes" gridcolor="808080"/>
+
  </style>
+
 
+
<style id="checkbox">
+
  <style_checkbox textcolor="f0f0f0" font="fntcheck"/>
+
  </style>
+
  
<style id="image" border="brdsystem">
+
<portal id="name" style="chkNormal" showinvalid="yes"
   <style_image/>
+
      tiptext="Click to equip this item">
   </style>
+
   <checkbox field="grIsEquip" dynamicfield="grStkName"/>
 +
   </portal>
  
<style id="menu" border="sunken">
+
<portal id="menu" style="menuNormal">
   <style_menu font="fntmenu" textcolor="84c8f7" backcolor="2a2c47"
+
   <menu_things field="adjChosen" component="none" maxvisible="20"
      selecttext="1414f7" selectback="f0f0f0"/>
+
        usepicksfield="adjUsePick" candidatefield="adjCandid">
   </style>
+
    <candidate></candidate>
 +
    </menu_things>
 +
   </portal>
  
<style id="separator">
+
<portal id="gender" style="menuNormal">
  <style_separator isvertical="no"
+
   <menu_literal field="perGender">
      start="sephorzsta" center="sephorzmid" end="sephorzend"/>
+
     <choice value="0" display="Gender: Male"/>
   <resource id="sephorzsta" isbuiltin="yes">
+
     <choice value="1" display="Gender: Female"/>
     <bitmap bitmap="sep_horz_start.bmp"/>
+
     </menu_literal>
    </resource>
+
   </portal>
  <resource id="sephorzmid" isbuiltin="yes">
+
    <bitmap bitmap="sep_horz_middle.bmp"/>
+
     </resource>
+
  <resource id="sephorzend" isbuiltin="yes">
+
    <bitmap bitmap="sep_horz_end.bmp"/>
+
     </resource>
+
   </style>
+
  
<style id="region" border="brdsystem">
+
<portal id="textlist" style="menuNormal">
   <style_region/>
+
   <menu_array field="conTextSel" array="conList" maxvisible="10"/>
   </style>
+
   </portal>
  
 +
<portal id="stRace" style="chsNormal" width="110">
 +
  <chooser_table component="Race" choosetemplate="LargeItem">
 +
    <chosen>
 +
      @text = "Race: " & field[name].text
 +
      </chosen>
 +
    <titlebar>
 +
      @text = "Choose the race for your character"
 +
      </titlebar>
 +
    </chooser_table>
 +
  </portal>
 
</pre>
 
</pre>

Latest revision as of 02:59, 20 February 2009

Context: HL KitKit Reference … Data File Reference  … Multiple Sources

The "portal" Element

Within the hierarchy of visual elements, the individual elements that the user interacts with are portals. There is a wide assortment of different portal types that can be employed for different purposes. Each separate portal is specified through the use of a "portal" element. The complete list of attributes for this element is below.

id Id – Specifies the unique id of the portal. This id is used in all references to the portal.
style Id – Specifies the unique id of the style to utilize with this portal. The style must be compatible with the portal type (e.g. a label style must be used with a label portal).
tiptext (Optional) Text – Description information to be shown to the user when the user pauses the mouse over the portal. If empty, nothing is shown. Default: Empty.
isheader (Optional) Boolean – Indicates whether this portal is utilized within a dual-purpose header as part of a table. Default: "no".

NOTE! This attribute is only permitted on portals within templates that serves as dual-purpose headers.
NOTE! Field-based portals may never be designated for use within a header, as there is no pick/thing associated with dual-purpose templates.

showinvalid (Optional) Boolean – Indicates whether the text used within the portal should be automatically changed to the built-in "lblwarning" color when the portal references an invalid pick. This behavior only applies to suitable portal types, including labels, incrementers, checkboxes, and menus. Default: "no".
showdisabled (Optional) Boolean – Indicates whether the text used within the portal should be automatically changed to the built-in "lbldisable" color when the portal references a pick whose pre-requisites are not satisfied. This behavior only applies to suitable portal types, including labels, incrementers, checkboxes, and menus. Default: "yes".
width (Optional) Integer – Specifies the default width to use for the portal. In general, portal dimensions should only be controlled via the Position script of the containing visual element. If zero, the default auto-sizing behaviors are employed. Default: "0".
height (Optional) Integer – Specifies the default height to use for the portal. In general, portal dimensions should only be controlled via the Position script of the containing visual element. If zero, the default auto-sizing behaviors are employed. Default: "0".

The "portal" element also possesses child elements that define the specifics 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.

IMPORTANT! With the exception of the "live" and "mouseinfo" elements, exactly one of these child elements may be specified for each portal. If multiple are given, a compiler error will be reported. The chosen child element dictates the type of portal that is being defined and its characteristics. You may include up to one "live" and/or "mouseinfo" elements after the single child element that specifies the portal.

label An optional "label" element may appear as defined by the given link. This element specifies the details of a label portal.
image_field An optional "image_field" element may appear as defined by the given link. This element specifies the details of a field-based image portal.
image_user An optional "image_user" element may appear as defined by the given link. This element specifies the details of an image portal containing user-selected images.
image_literal An optional "image_literal" element may appear as defined by the given link. This element specifies the details of an image portal containing a static image.
image_reference An optional "image_reference" element may appear as defined by the given link. This element specifies the details of an image portal that references a field-based image.
incrementer An optional "incrementer" element may appear as defined by the given link. This element specifies the details of an incrementer portal.
edit An optional "edit" element may appear as defined by the given link. This element specifies the details of an edit portal.
edit_date An optional "edit_date" element may appear as defined by the given link. This element specifies the details of an editdate portal.
checkbox An optional "checkbox" element may appear as defined by the given link. This element specifies the details of a checkbox portal.
menu_literal An optional "menu_literal" element may appear as defined by the given link. This element specifies the details of a menu portal consisting of a fixed set of options.
menu_array An optional "menu_array" element may appear as defined by the given link. This element specifies the details of an array-based menu portal.
menu_things An optional "menu_things" element may appear as defined by the given link. This element specifies the details of a thing-based menu portal.
action An optional "action" element may appear as defined by the given link. This element specifies the details of an action portal.
region An optional "region" element may appear as defined by the given link. This element specifies the details of a region portal.
separator An optional "separator" element may appear as defined by the given link. This element specifies the details of a separator portal.
chooser_table An optional "chooser_table" element may appear as defined by the given link. This element specifies the details of a table-based chooser portal.
table_fixed An optional "table_fixed" element may appear as defined by the given link. This element specifies the details of a non-editable table portal.
table_dynamic An optional "table_dynamic" element may appear as defined by the given link. This element specifies the details of a table portal to which the user can add arbitrary items.
table_auto An optional "table_auto" element may appear as defined by the given link. This element specifies the details of a table portal to which a specific item can be added.
setting_edit An optional "setting_edit" element may appear as defined by the given link. This element specifies the details of a special portal for editing configuration settings.
setting_summary An optional "setting_summary" element may appear as defined by the given link. This element specifies the details of a special portal for showing a summary of configuration settings.
alliance An optional "alliance" element may appear as defined by the given link. This element specifies the details of a special portal for controlling the alliance state of an actor.
output_label An optional "output_label" element may appear as defined by the given link. This element specifies the details of a label portal for sheet output.
output_image An optional "output_image" element may appear as defined by the given link. This element specifies the details of an image portal for sheet output.
output_table An optional "output_table" element may appear as defined by the given link. This element specifies the details of a table portal for sheet output.
output_dots An optional "output_dots" element may appear as defined by the given link. This element specifies the details of a special label portal for sheet output.
output_separator An optional "output_separator" element may appear as defined by the given link. This element specifies the details of a separator portal for sheet output.
live An optional "live" element may appear as defined by the given link. This element defines a Live Tag Expression for the portal.
mouseinfo An optional "mouseinfo" element may appear as defined by the given link. This element defines a MouseInfo Script for the portal.

The "live" Element

The "live" element defines a Live Tag Expression for the portal that determines whether the portal is applicable based on the prevailing conditions. In general, portals should be controlled via scripts using the "visible" target reference instead of using this mechanism. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the Live tag expression.

The "mouseinfo" Element

The "mouseinfo" element defines a MouseInfo Script for the portal that synthesizes text for display to the user whenever the user pauses the mouse over the portal. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the MouseInfo script.

Example

The following example demonstrates what various "portal" elements might look like. All default values are assumed for optional attributes.

<portal id="hair" style="editNormal">
  <edit field="perHair"/>
  </portal>

<portal id="name" style="chkNormal" showinvalid="yes"
      tiptext="Click to equip this item">
  <checkbox field="grIsEquip" dynamicfield="grStkName"/>
  </portal>

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

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

<portal id="textlist" style="menuNormal">
  <menu_array field="conTextSel" array="conList" maxvisible="10"/>
  </portal>

<portal id="stRace" style="chsNormal" width="110">
  <chooser_table component="Race" choosetemplate="LargeItem">
    <chosen>
      @text = "Race: " & field[name].text
      </chosen>
    <titlebar>
      @text = "Choose the race for your character"
      </titlebar>
    </chooser_table>
  </portal>