Difference between revisions of "Skinning HowTo/Common XUI attributes"

From Second Life Wiki
Jump to navigation Jump to search
(43 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This pages describes some of the most frequently used XML attributes.  The XUI elements that use them can be found at:
{{XUI Nav}}
*[[Skinning HowTo/XUI Containers]]
This page describes XML attributes common to all XUI elementsMost are defined in the LLView base class in source file <code>llui/llview.cpp</code>.
*[[Skinning HowTo/XUI Menus]]
*[[Skinning HowTo/XUI Widgets]]
When these parameters appear there, they are just listed under the elements that use them.


=Used by all XUI elements=
== Reference summary ==


===== name =====
The following table provides a quick reference for all the common XUI attribute.  The following sections provide a bit more detail and some examples for each attribute.
 
{| class="lltable" border=1
|--
! Attribute Name
! Required?
! Datatype
! Valid values
! Description
 
|--
|  bottom
| Optional
| Integer
| Positive or negative
| Sets the vertical position of the widget's bottom edge relative to the parent container's bottom edge.  A negative value sets the widget's bottom edge relative to the parent container's top edge.  For example, given a floater with a height of 300 and a title 20 pixels tall, set the <code>bottom</code> to 260 to put the bottom edge of the title 40 pixels away from the top border of the floater.
 
|--
|  bottom_delta
| Optional
| Integer
| Positive or negative
| Use instead of <code>bottom</code>. Sets the vertical position of the widget's bottom edge relative to the previous element's bottom edge, or, for the first widget, the bottom edge of the container.  Use a negative value to move the widget down, and a positive value to move it up.
 
|--
|  control_name
| Optional
| String
|
| Associates check box and slider values with particular saved settings.  When you load a floater or other XUI element containing a check box or slider with that tag, it will take its initial value from the named saved setting and automatically save modified values as the user interacts with those controls.
 
|--
|  default_tab_group
| Optional
| Integer
| Positive number
| See ...
 
|--
|  enabled
| Optional
| Boolean
| true/false
| Determines whether the the element and its children are operational.  When disabled, the element is visible, but "greyed out."
The Viewer may set this attribute value programatically to enable or disable the element as needed.
 
 
|--
|  follows
| Optional
| String
* left
* top
* right
* bottom
* all
 
| Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that  dynamically re-sizes itself with its container.  Separate multiple values with a pipe symbol (&#124;).
 
|--
|  font
| Optional
| String
|
*SansSerifSmall
* SansSerif
* SansSerifBig
* SansSerifBold
* Monospace
| Sets the size and style of the application font to use. The default is SansSerifSmall for <code>text</code> elements and SansSerif for controls (such as <code>check_box</code> and <code>button</code>.
|--
|  font.size
| Optional
| String
|
* Monospace: 9pt
* Small: 9pt
* Medium: 10pt
* Large: 12pt
* Huge: 16pt
| Sets the font size. The default size is defined by the font (e.g. SansSerifSmall is 'Small', SansSerif is 'Medium').
 
|--
|  font.style
| Optional
|String
|
* BOLD
* ITALIC
* UNDERLINE. 
| Sets the font style. The default size is NORMAL.  Separate multiple values with a pipe symbol (&#124;).
 
|--
|halign
| Optional
|String
|
* left
* center
* right
| Controls horizontal alignment of label.
 
|--
|  height
| Required
| Integer
| Positive number
| The height of the element in pixels. For text, this defines the visible text as well as the clickable area. If the height of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will lengthen when localizing the viewer.
For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.
 
|--
|  label
| Optional
| String
|
|  The text displayed in the element.
 
|--
|  left
| Optional
| Integer
|Positive or negative number.
| Sets the horizontal position of the widget's left edge relative to the container's left edge.  A negative value sets the position relative to the right edge of the container.
 
|--
|  left_delta
| Optional
| Integer
|Positive or negative number.
| Use instead of <code>left</code>.  Sets the horizontal position of the element's left edge relative to the previous element's left edge, or, for the first widget, the left edge of the container.  Best used to left-align the current element with the previous element.
 
|--
|  mouse_opaque
| Optional
| Boolean
| true/false
| Determines whether the the element reacts to the mouse when it is over it.  When it is set to false, elements below will handle the mouse actions.
 
|--
|  name
| Required
| String
| Unique value within the floater.
| The XML name of this element.  Do not modify this attribute. Many of the element names are looked up by the viewer. If the viewer cannot find an element name it expects, it will crash.
 
|--
|  right
| Optional
| Integer
|Positive or negative number.
| Sets the horizontal position of the widget's right edge relative to the container's left edge.  A negative value sets the position relative to the right edge of the container.  Best used to align something to the right. 
 
|--
|  sound_flags
| Optional
| Integer
|
| Determines whether to make a sound on mouse-up and/or mouse-down.
This attribute is written when saving the XML, but it is not read when loading XML.
 
|--
| tab_group
| Optional
| Integer
| Positive number
| Tab order by default follows the order widgets are listed in XML, and is the same for all widgets. Widgets are divided into groups, by number. All widgets are in group 0 by default.
 
 
|--
|  tool_tip
| Optional
| String
|
| Text of tooltip displayed when the user moves the mouse over the element.
 
 
|--
| top
| Optional
| Integer
|Positive or negative number.
| Sets the vertical position of the widget's top edge relative to the container's top edge.  A negative value sets the position relative to the top edge of the container.  Best used to align something to the top of the parent container.
 
|--
| use_bounding_rect
| Optional
| Boolean
| true/false
| Hit test against bounding rectangle that includes all child elements.
 
|--
|valign
| Optional
|String
|
* top
* bottom
* center
| Controls vertical alignment of label.
 
|--
|  visible
| Optional
| Boolean
| true/false
| Sets the initial visibility of the element and its children.  The Viewer sets this attribute value programatically to hide or show the element as needed.
 
|--
|  width
| Required
| Integer
| Positive number.
| The width of the element, in pixels. For text, this defines the visible text as well as the clickable area. If the width of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will widen when localizing the viewer. For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.
|}
 
== General attributes ==
 
These attributes are valid for all elements.
 
=== name ===
''Required.'' The XML name of this element. The name must be unique to the floater you are editing.  
''Required.'' The XML name of this element. The name must be unique to the floater you are editing.  


Line 14: Line 232:
String: <code>name="input_first_name"</code>
String: <code>name="input_first_name"</code>


===== visible =====
=== visible ===
''Optional.'' Sets the initial visibility of the element and its children.
''Optional.'' Sets the initial visibility of the element and its children.


Line 21: Line 239:
Boolean: <code>visible="false"</code>
Boolean: <code>visible="false"</code>


===== enabled =====
=== enabled ===
''Optional.'' Determines whether the the element and its children are operational.  When disabled, the element is visible, but "greyed out."
''Optional.'' Determines whether the the element and its children are operational.  When disabled, the element is visible, but "greyed out."


Line 28: Line 246:
Boolean: <code>enabled="false"</code>
Boolean: <code>enabled="false"</code>


===== tool_tip =====
=== tool_tip ===
''Optional.'' Explains the function of the element to the user when the user places the mouse over the element.
''Optional.'' Explains the function of the element to the user when the user places the mouse over the element.


String: <code>tool_tip="Pick a resident to mute"</code>
String: <code>tool_tip="Pick a resident to mute"</code>


===== mouse_opaque =====
=== mouse_opaque ===
''Optional.'' Determines whether the the element reacts to the mouse when it is over it.  When it is set to false, elements below will handle the mouse actions.
''Optional.'' Determines whether the the element reacts to the mouse when it is over it.  When it is set to false, elements below will handle the mouse actions.


Boolean: <code>mouse_opaque="false"</code>
Boolean: <code>mouse_opaque="false"</code>


===== control_name =====
=== control_name ===
''Optional.'' Lets you associate check box and slider values with particular saved settings without writing any C++ code. Very useful. When you load a floater or other XUI element containing a check box or slider with that tag, it will take it's initial value from the named saved setting and automatically saves back out modified values as the user interacts with those controls.
''Optional.'' Lets you associate check box and slider values with particular saved settings without writing any C++ code. Very useful. When you load a floater or other XUI element containing a check box or slider with that tag, it will take it's initial value from the named saved setting and automatically saves back out modified values as the user interacts with those controls.


Line 45: Line 263:
String: <code>control_name="particlesbeacon"</code>
String: <code>control_name="particlesbeacon"</code>


===== sound_flags =====
=== sound_flags ===
''Optional.'' Determines whether to make a sound on mouse-up and/or mouse-down.
 
* ''This attribute is written when saving the XML, but it is not read when loading XML.''
* ''This attribute is written when saving the XML, but it is not read when loading XML.''


===== hover_cursor =====
=== hover_cursor ===
Supposed to set the cursor icon used while hovering over this element.
''Optional.'' Supposed to set the cursor icon used while hovering over this element.


* ''This attribute seems to be overridden by hardcoded values.  If you find a widget that honors this, please document it here.''
'''Deprecated'''.


Allowed values are UI_CURSOR_ARROW, UI_CURSOR_WAIT, UI_CURSOR_HAND, UI_CURSOR_IBEAM, UI_CURSOR_CROSS, UI_CURSOR_SIZENWSE, UI_CURSOR_SIZENESW, UI_CURSOR_SIZEWE, UI_CURSOR_SIZENS, UI_CURSOR_NO, UI_CURSOR_WORKING, UI_CURSOR_TOOLGRAB, UI_CURSOR_TOOLLAND, UI_CURSOR_TOOLFOCUS, UI_CURSOR_TOOLCREATE, UI_CURSOR_ARROWDRAG, UI_CURSOR_ARROWCOPY, UI_CURSOR_ARROWDRAGMULTI, UI_CURSOR_ARROWCOPYMULTI, UI_CURSOR_NOLOCKED, UI_CURSOR_ARROWLOCKED, UI_CURSOR_GRABLOCKED, UI_CURSOR_TOOLTRANSLATE, UI_CURSOR_TOOLROTATE, UI_CURSOR_TOOLSCALE, UI_CURSOR_TOOLCAMERA, UI_CURSOR_TOOLPAN, UI_CURSOR_TOOLZOOMIN, UI_CURSOR_TOOLPICKOBJECT3, UI_CURSOR_TOOLSIT, UI_CURSOR_TOOLBUY, UI_CURSOR_TOOLPAY, UI_CURSOR_TOOLOPEN, UI_CURSOR_TOOLPLAY, UI_CURSOR_TOOLPAUSE, UI_CURSOR_TOOLMEDIAOPEN, UI_CURSOR_PIPETTE
Allowed values are UI_CURSOR_ARROW, UI_CURSOR_WAIT, UI_CURSOR_HAND, UI_CURSOR_IBEAM, UI_CURSOR_CROSS, UI_CURSOR_SIZENWSE, UI_CURSOR_SIZENESW, UI_CURSOR_SIZEWE, UI_CURSOR_SIZENS, UI_CURSOR_NO, UI_CURSOR_WORKING, UI_CURSOR_TOOLGRAB, UI_CURSOR_TOOLLAND, UI_CURSOR_TOOLFOCUS, UI_CURSOR_TOOLCREATE, UI_CURSOR_ARROWDRAG, UI_CURSOR_ARROWCOPY, UI_CURSOR_ARROWDRAGMULTI, UI_CURSOR_ARROWCOPYMULTI, UI_CURSOR_NOLOCKED, UI_CURSOR_ARROWLOCKED, UI_CURSOR_GRABLOCKED, UI_CURSOR_TOOLTRANSLATE, UI_CURSOR_TOOLROTATE, UI_CURSOR_TOOLSCALE, UI_CURSOR_TOOLCAMERA, UI_CURSOR_TOOLPAN, UI_CURSOR_TOOLZOOMIN, UI_CURSOR_TOOLPICKOBJECT3, UI_CURSOR_TOOLSIT, UI_CURSOR_TOOLBUY, UI_CURSOR_TOOLPAY, UI_CURSOR_TOOLOPEN, UI_CURSOR_TOOLPLAY, UI_CURSOR_TOOLPAUSE, UI_CURSOR_TOOLMEDIAOPEN, UI_CURSOR_PIPETTE
Line 57: Line 277:
String: <code>hover_cursor="UI_CURSOR_HAND"</code>
String: <code>hover_cursor="UI_CURSOR_HAND"</code>


===== use_bounding_rect =====
=== use_bounding_rect ===
''Optional.'' Hit test against bounding rectangle that includes all child elements.
''Optional.'' Hit test against bounding rectangle that includes all child elements.


Boolean: <code>use_bounding_rect="true"</code>
Boolean: <code>use_bounding_rect="true"</code>


===== default_tab_group =====
=== default_tab_group ===
''Optional.''
 
Integer: <code>default_tab_group="1"</code>
 
=== tab_group ===
 
Tab order by default follows the order widgets are listed in XML, and is the same for all widgets. Widgets are divided  into groups, by number. All widgets are in group 0 by default.


=Positioning=
If you give a widget a specific tab_group attribute setting, all widgets following it will be in the same tab group until you specify another one.  Tab order goes through the widgets in the lowest-numbered tab group in the order they are listed in XML, then goes to the next highest number tab group, and so on.  
Used by all XUI elements.


===== width =====
So, for example:
 
<xml><element_a .../>
<element_b tab_group="1" />
<element_c/></xml>
 
Element A will have tab group 0, and elements B and C will have tab group 1. So, the overall tab order would be a, b, c.
 
The point is to avoid having to number every single widget. You pick a couple of "anchor" points where you have, say, a row of buttons that you want to come at a specific point in the tab order. and you give the first one a unique number.
 
==Positioning and size attributes ==
 
These attributes are valid for all elements.
 
Horizontal dimensions are specified with "right", "left", "left_delta", and "width".  Together with the width of the parent container, that makes five constraints to define two edges.  Something has to give.  So "left" and "right" together override "width", and "left_delta" overrides "left" and/or "right".
 
The same is true of vertical dimensions.  The four parameters are "top", "bottom", "bottom_delta", and "height".  "top" overrides "height", and "bottom_delta" overrides "bottom" and/or "top".
 
The values may not mean what you think they do.  Read the definitions carefully.
 
When a parent container is resized, the child edges can be set to follow the parent edges using the "follows" parameter.  If the "follows" parameter is not set, the logic is a bit complicated.  If "left" is negative, the left edge follow the parent right edge; if non-negative, the left edge follows the parent left edge; unless "left_delta" or "right" are specified, in which case, nothing follows.  If "bottom" is negative, the bottom edge follows the parent top edge; if non-negative, the bottom edge follows the parent bottom; unless "bottom_delta" or "top" are specified.  If none of "top", "bottom", and "bottom_delta" are specified, the first child follows the parent top edge, and the others follow their siblings.
 
=== width ===
''Required.'' The width of the element, in pixels.  
''Required.'' The width of the element, in pixels.  


Line 77: Line 325:


Integer: <code>width="140"</code>
Integer: <code>width="140"</code>
===== height =====
 
=== height ===
''Required.'' The height of the element, in pixels.  
''Required.'' The height of the element, in pixels.  


Line 85: Line 334:


Integer: <code>height="24"</code>
Integer: <code>height="24"</code>
===== left =====
 
''Optional.'' Sets the position in the x dimension of the ''element's'' <u>left edge</u> relative to the container's '''left''' edge. Positive and negative values are accepted. A negative value will set the position relative to the '''right''' edge of the container.
=== left ===
''Optional.'' Sets the position in the horizontal dimension of the ''element's'' <u>left edge</u> relative to the container's '''left''' edge. Positive and negative values are accepted. A negative value will set the position relative to the '''right''' edge of the container.


Integer: <code> left="6"</code>
Integer: <code> left="6"</code>


===== right =====
=== right ===
''Optional.'' Sets the position in the x dimension of the ''element's'' <u>right edge</u> relative to the container's '''left''' edge. Positive and negative values are accepted.  A negative value will set the position relative to the '''right''' edge of the container.  Best used to align something to the right.  
''Optional.'' Sets the position in the horizontal dimension of the ''element's'' <u>right edge</u> relative to the container's '''left''' edge. Positive and negative values are accepted.  A negative value will set the position relative to the '''right''' edge of the container.  Best used to align something to the right.  
* For example, given a floater with a width of 500 and a button we wish to right align in the floater, we can set the <code>right</code> to 490 -- this puts the right edge of the button 10 pixels away from the right border of the floater.  
* For example, given a floater with a width of 500 and a button we wish to right align in the floater, we can set the <code>right</code> to 490 -- this puts the right edge of the button 10 pixels away from the right border of the floater.  


Integer: <code> right="6"</code>
Integer: <code> right="-6"</code>


===== left_delta =====
=== left_delta ===
''Optional. (use instead of <code>left</code>)'' Sets the position in the x dimension of the element's left edge relative to the previous element, or, for the first widget, the left edge of the container. Positive and negative values are accepted. Best used to left-align the current element with the previous element.  
''Optional. (use instead of <code>left</code>)'' Sets the position in the horizontal dimension of the element's left edge relative to the previous element's '''left''' edge, or, for the first widget, the left edge of the container. Positive and negative values are accepted. Best used to left-align the current element with the previous element.  
* For example, given Button B with a width of 100, a previous Button A with a width of 50 and a distance between elements of 6, we would set the <code>left_delta</code> to -106, putting the left edge of Button B 106 pixels to the left of Button A. We use a negative number to move left, and a positive number to move right.
* For example, given Button B with a width of 100, a previous Button A with a width of 50 and a distance between elements of 6, we would set the <code>left_delta</code> to -106, putting the left edge of Button B 106 pixels to the left of Button A. We use a negative number to move left, and a positive number to move right.


Integer: <code> left_delta="-106"</code>
Integer: <code> left_delta="-106"</code>


===== top =====
=== bottom ===
''Optional.'' Sets the position in the vertical dimension of the element's <u>bottom edge</u> relative to the parent container's '''bottom''' edge. Positive and negative values are accepted. A negative value sets the element's <u>bottom edge</u> relative to the parent container's '''top edge'''.  For example, given a floater with a height of 300 and a title 20 pixels tall and we want , we can set the <code>bottom</code> to 260 putting the bottom edge of the title 40 pixels away from the top border of the floater.


===== bottom =====
Integer: <code>bottom="260"</code>
''Optional.'' Sets the position in the y dimension of the element's bottom edge relative to the container. Positive and negative values are accepted. For example, given a floater with a height of 300 and a title 20 pixels tall and we want , we can set the <code>bottom</code> to (NEED TO DO MATH, LOL) -- putting the bottom edge of the title 40 pixels away from the top border of the floater.


Integer: <code> bottom="(NEED TO DO MATH, LOL)"</code>
=== top ===
''Optional.'' Sets the position in the vertical dimension of the ''element's'' <u>top edge</u> relative to the container's '''top''' edge. Positive and negative values are accepted.  A negative value will set the position relative to the '''top edge''' of the container.  Best used to align something to the top of the parent container.


===== bottom_delta =====
Integer: <code> top="-20"</code>


===== follows =====
=== bottom_delta ===
''Optional. (use instead of <code>bottom</code>)'' Sets the position in the vertical dimension of the element's bottom edge relative to the previous element's '''bottom''' edge, or, for the first widget, the bottom edge of the container. Positive and negative values are accepted.  We use a negative number to move down, and a positive number to move up.
 
Integer: <code>bottom_delta="-106"</code>
 
=== follows ===
''Optional.'' Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that can dynamically resize itself with its container.
''Optional.'' Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that can dynamically resize itself with its container.


Values: left, top, right, bottom. String multiple values together using pipes.
Values: "left", "top", "right", "bottom", "all". String multiple values together using pipes.


The following example sets an element to follow both the left and the top, such as a floater's title may be designed:
The following example sets an element to follow both the left and the top, such as a floater's title may be designed:
String: <code>follows="left|top"</code>
String: <code>follows="left|top"</code>


===== rect_control =====
=== rect_control ===
''Optional.''  Gets "left," "right," "bottom," and "top" from the default configuration file, but the XML parameters will override this.  For panels (and floaters, which are derived from panels) that are resized by the user, the resized values will be stored in the default configuration file.
 
String: <code>rect_control="FloaterAdvancedSkyRect"</code>
 
==Text attributes ==


=Text=
=== label ===
''Optional.''  This is the text that is displayed on the element.


===== label =====
String: <code>label="Oggetti scriptati"</code>


===== font =====
=== font ===
''Optional.'' Sets which size and style of the application font to use. The default is SansSerifSmall for <code>text</code> elements and SansSerif for controls (such as <code>check_box</code> and <code>button</code>.
''Optional.'' Sets which size and style of the application font to use. The default is SansSerifSmall for <code>text</code> elements and SansSerif for controls (such as <code>check_box</code> and <code>button</code>.


Line 132: Line 394:
String: <code>font="SansSerifSmall"</code>
String: <code>font="SansSerifSmall"</code>


===== font_size =====
=== font.size ===
''Optional.'' Sets the font size. The default size is defined by the font (e.g. SansSerifSmall is 'Small', SansSerif is 'Medium').
 
Values:
* Monospace = 9 pt
* Small = 9 pt
* Medium = 10 pt
* Large = 12 pt
* Huge = 16 pt
 
String: <code>font_size="Small"</code>


===== font_style =====
=== font.style ===
''Optional.'' Sets the font style. The default size is NORMAL.


===== style =====
Values:
* '''BOLD'''
* ''ITALIC''
* '''''BOLD|ITALIC'''''
* <U>UNDERLINE</U>
 
Example: <code>font.style="BOLD|ITALIC"</code>
 
=== style ===
Deprecated.
Deprecated.


===== halign =====
=== halign ===
===== valign =====
''Optional.'' Controls horizontal alignment of label on button face.  Options are "left", "center" and "right".
 
=== valign ===
Deprecated.
Deprecated.
= Other parameters used by many XUI elements =
===== tab_group =====
===== border =====

Revision as of 16:44, 21 May 2010

This page describes XML attributes common to all XUI elements. Most are defined in the LLView base class in source file llui/llview.cpp.

Reference summary

The following table provides a quick reference for all the common XUI attribute. The following sections provide a bit more detail and some examples for each attribute.

Attribute Name Required? Datatype Valid values Description
bottom Optional Integer Positive or negative Sets the vertical position of the widget's bottom edge relative to the parent container's bottom edge. A negative value sets the widget's bottom edge relative to the parent container's top edge. For example, given a floater with a height of 300 and a title 20 pixels tall, set the bottom to 260 to put the bottom edge of the title 40 pixels away from the top border of the floater.
bottom_delta Optional Integer Positive or negative Use instead of bottom. Sets the vertical position of the widget's bottom edge relative to the previous element's bottom edge, or, for the first widget, the bottom edge of the container. Use a negative value to move the widget down, and a positive value to move it up.
control_name Optional String Associates check box and slider values with particular saved settings. When you load a floater or other XUI element containing a check box or slider with that tag, it will take its initial value from the named saved setting and automatically save modified values as the user interacts with those controls.
default_tab_group Optional Integer Positive number See ...
enabled Optional Boolean true/false Determines whether the the element and its children are operational. When disabled, the element is visible, but "greyed out."

The Viewer may set this attribute value programatically to enable or disable the element as needed.


follows Optional String
  • left
  • top
  • right
  • bottom
  • all
Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that dynamically re-sizes itself with its container. Separate multiple values with a pipe symbol (|).
font Optional String
  • SansSerifSmall
  • SansSerif
  • SansSerifBig
  • SansSerifBold
  • Monospace
Sets the size and style of the application font to use. The default is SansSerifSmall for text elements and SansSerif for controls (such as check_box and button.
font.size Optional String
  • Monospace: 9pt
  • Small: 9pt
  • Medium: 10pt
  • Large: 12pt
  • Huge: 16pt
Sets the font size. The default size is defined by the font (e.g. SansSerifSmall is 'Small', SansSerif is 'Medium').
font.style Optional String
  • BOLD
  • ITALIC
  • UNDERLINE.
Sets the font style. The default size is NORMAL. Separate multiple values with a pipe symbol (|).
halign Optional String
  • left
  • center
  • right
Controls horizontal alignment of label.
height Required Integer Positive number The height of the element in pixels. For text, this defines the visible text as well as the clickable area. If the height of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will lengthen when localizing the viewer.

For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.

label Optional String The text displayed in the element.
left Optional Integer Positive or negative number. Sets the horizontal position of the widget's left edge relative to the container's left edge. A negative value sets the position relative to the right edge of the container.
left_delta Optional Integer Positive or negative number. Use instead of left. Sets the horizontal position of the element's left edge relative to the previous element's left edge, or, for the first widget, the left edge of the container. Best used to left-align the current element with the previous element.
mouse_opaque Optional Boolean true/false Determines whether the the element reacts to the mouse when it is over it. When it is set to false, elements below will handle the mouse actions.
name Required String Unique value within the floater. The XML name of this element. Do not modify this attribute. Many of the element names are looked up by the viewer. If the viewer cannot find an element name it expects, it will crash.
right Optional Integer Positive or negative number. Sets the horizontal position of the widget's right edge relative to the container's left edge. A negative value sets the position relative to the right edge of the container. Best used to align something to the right.
sound_flags Optional Integer Determines whether to make a sound on mouse-up and/or mouse-down.

This attribute is written when saving the XML, but it is not read when loading XML.

tab_group Optional Integer Positive number Tab order by default follows the order widgets are listed in XML, and is the same for all widgets. Widgets are divided into groups, by number. All widgets are in group 0 by default.


tool_tip Optional String Text of tooltip displayed when the user moves the mouse over the element.


top Optional Integer Positive or negative number. Sets the vertical position of the widget's top edge relative to the container's top edge. A negative value sets the position relative to the top edge of the container. Best used to align something to the top of the parent container.
use_bounding_rect Optional Boolean true/false Hit test against bounding rectangle that includes all child elements.
valign Optional String
  • top
  • bottom
  • center
Controls vertical alignment of label.
visible Optional Boolean true/false Sets the initial visibility of the element and its children. The Viewer sets this attribute value programatically to hide or show the element as needed.
width Required Integer Positive number. The width of the element, in pixels. For text, this defines the visible text as well as the clickable area. If the width of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will widen when localizing the viewer. For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.

General attributes

These attributes are valid for all elements.

name

Required. The XML name of this element. The name must be unique to the floater you are editing.

  • IMPORTANT: As noted above, do not re-name XML elements, even for localization. Many of the element names are looked up by the viewer. If the viewer cannot find an element name it expects, it will crash.

String: name="input_first_name"

visible

Optional. Sets the initial visibility of the element and its children.

This can be set programatically to hide or show the element as needed.

Boolean: visible="false"

enabled

Optional. Determines whether the the element and its children are operational. When disabled, the element is visible, but "greyed out."

This can be set programatically to enable or disable the element as needed.

Boolean: enabled="false"

tool_tip

Optional. Explains the function of the element to the user when the user places the mouse over the element.

String: tool_tip="Pick a resident to mute"

mouse_opaque

Optional. Determines whether the the element reacts to the mouse when it is over it. When it is set to false, elements below will handle the mouse actions.

Boolean: mouse_opaque="false"

control_name

Optional. Lets you associate check box and slider values with particular saved settings without writing any C++ code. Very useful. When you load a floater or other XUI element containing a check box or slider with that tag, it will take it's initial value from the named saved setting and automatically saves back out modified values as the user interacts with those controls.

This is extremely powerful and should let you create a custom panel to control any of the boolean or real valued settings that you see in the Debug_Settings floater. See floater_beacons.xml for examples.

String: control_name="particlesbeacon"

sound_flags

Optional. Determines whether to make a sound on mouse-up and/or mouse-down.

  • This attribute is written when saving the XML, but it is not read when loading XML.

hover_cursor

Optional. Supposed to set the cursor icon used while hovering over this element.

Deprecated.

Allowed values are UI_CURSOR_ARROW, UI_CURSOR_WAIT, UI_CURSOR_HAND, UI_CURSOR_IBEAM, UI_CURSOR_CROSS, UI_CURSOR_SIZENWSE, UI_CURSOR_SIZENESW, UI_CURSOR_SIZEWE, UI_CURSOR_SIZENS, UI_CURSOR_NO, UI_CURSOR_WORKING, UI_CURSOR_TOOLGRAB, UI_CURSOR_TOOLLAND, UI_CURSOR_TOOLFOCUS, UI_CURSOR_TOOLCREATE, UI_CURSOR_ARROWDRAG, UI_CURSOR_ARROWCOPY, UI_CURSOR_ARROWDRAGMULTI, UI_CURSOR_ARROWCOPYMULTI, UI_CURSOR_NOLOCKED, UI_CURSOR_ARROWLOCKED, UI_CURSOR_GRABLOCKED, UI_CURSOR_TOOLTRANSLATE, UI_CURSOR_TOOLROTATE, UI_CURSOR_TOOLSCALE, UI_CURSOR_TOOLCAMERA, UI_CURSOR_TOOLPAN, UI_CURSOR_TOOLZOOMIN, UI_CURSOR_TOOLPICKOBJECT3, UI_CURSOR_TOOLSIT, UI_CURSOR_TOOLBUY, UI_CURSOR_TOOLPAY, UI_CURSOR_TOOLOPEN, UI_CURSOR_TOOLPLAY, UI_CURSOR_TOOLPAUSE, UI_CURSOR_TOOLMEDIAOPEN, UI_CURSOR_PIPETTE

String: hover_cursor="UI_CURSOR_HAND"

use_bounding_rect

Optional. Hit test against bounding rectangle that includes all child elements.

Boolean: use_bounding_rect="true"

default_tab_group

Optional.

Integer: default_tab_group="1"

tab_group

Tab order by default follows the order widgets are listed in XML, and is the same for all widgets. Widgets are divided into groups, by number. All widgets are in group 0 by default.

If you give a widget a specific tab_group attribute setting, all widgets following it will be in the same tab group until you specify another one. Tab order goes through the widgets in the lowest-numbered tab group in the order they are listed in XML, then goes to the next highest number tab group, and so on.

So, for example:

<xml><element_a .../> <element_b tab_group="1" /> <element_c/></xml>

Element A will have tab group 0, and elements B and C will have tab group 1. So, the overall tab order would be a, b, c.

The point is to avoid having to number every single widget. You pick a couple of "anchor" points where you have, say, a row of buttons that you want to come at a specific point in the tab order. and you give the first one a unique number.

Positioning and size attributes

These attributes are valid for all elements.

Horizontal dimensions are specified with "right", "left", "left_delta", and "width". Together with the width of the parent container, that makes five constraints to define two edges. Something has to give. So "left" and "right" together override "width", and "left_delta" overrides "left" and/or "right".

The same is true of vertical dimensions. The four parameters are "top", "bottom", "bottom_delta", and "height". "top" overrides "height", and "bottom_delta" overrides "bottom" and/or "top".

The values may not mean what you think they do. Read the definitions carefully.

When a parent container is resized, the child edges can be set to follow the parent edges using the "follows" parameter. If the "follows" parameter is not set, the logic is a bit complicated. If "left" is negative, the left edge follow the parent right edge; if non-negative, the left edge follows the parent left edge; unless "left_delta" or "right" are specified, in which case, nothing follows. If "bottom" is negative, the bottom edge follows the parent top edge; if non-negative, the bottom edge follows the parent bottom; unless "bottom_delta" or "top" are specified. If none of "top", "bottom", and "bottom_delta" are specified, the first child follows the parent top edge, and the others follow their siblings.

width

Required. The width of the element, in pixels.

For text, this defines the visible text as well as the clickable area. If the width of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will widen when localizing the viewer.

For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.

  • Tip: See the bounding boxes of all XML elements in the viewer: Advanced menu > UI > Debug Views.

Integer: width="140"

height

Required. The height of the element, in pixels.

For text, this defines the visible text as well as the clickable area. If the height of a text element is not sufficient to hold the text, the text will be truncated. This is most likely what you will lengthen when localizing the viewer.

For most other elements, this describes the dimensions of an element, such as a button, icon, panel, text_area, etc.

Integer: height="24"

left

Optional. Sets the position in the horizontal dimension of the element's left edge relative to the container's left edge. Positive and negative values are accepted. A negative value will set the position relative to the right edge of the container.

Integer: left="6"

right

Optional. Sets the position in the horizontal dimension of the element's right edge relative to the container's left edge. Positive and negative values are accepted. A negative value will set the position relative to the right edge of the container. Best used to align something to the right.

  • For example, given a floater with a width of 500 and a button we wish to right align in the floater, we can set the right to 490 -- this puts the right edge of the button 10 pixels away from the right border of the floater.

Integer: right="-6"

left_delta

Optional. (use instead of left) Sets the position in the horizontal dimension of the element's left edge relative to the previous element's left edge, or, for the first widget, the left edge of the container. Positive and negative values are accepted. Best used to left-align the current element with the previous element.

  • For example, given Button B with a width of 100, a previous Button A with a width of 50 and a distance between elements of 6, we would set the left_delta to -106, putting the left edge of Button B 106 pixels to the left of Button A. We use a negative number to move left, and a positive number to move right.

Integer: left_delta="-106"

bottom

Optional. Sets the position in the vertical dimension of the element's bottom edge relative to the parent container's bottom edge. Positive and negative values are accepted. A negative value sets the element's bottom edge relative to the parent container's top edge. For example, given a floater with a height of 300 and a title 20 pixels tall and we want , we can set the bottom to 260 putting the bottom edge of the title 40 pixels away from the top border of the floater.

Integer: bottom="260"

top

Optional. Sets the position in the vertical dimension of the element's top edge relative to the container's top edge. Positive and negative values are accepted. A negative value will set the position relative to the top edge of the container. Best used to align something to the top of the parent container.

Integer: top="-20"

bottom_delta

Optional. (use instead of bottom) Sets the position in the vertical dimension of the element's bottom edge relative to the previous element's bottom edge, or, for the first widget, the bottom edge of the container. Positive and negative values are accepted. We use a negative number to move down, and a positive number to move up.

Integer: bottom_delta="-106"

follows

Optional. Sets which edge(s) an element follows when the containing element is resized. Specifying all edges results in an element that can dynamically resize itself with its container.

Values: "left", "top", "right", "bottom", "all". String multiple values together using pipes.

The following example sets an element to follow both the left and the top, such as a floater's title may be designed: String: follows="left|top"

rect_control

Optional. Gets "left," "right," "bottom," and "top" from the default configuration file, but the XML parameters will override this. For panels (and floaters, which are derived from panels) that are resized by the user, the resized values will be stored in the default configuration file.

String: rect_control="FloaterAdvancedSkyRect"

Text attributes

label

Optional. This is the text that is displayed on the element.

String: label="Oggetti scriptati"

font

Optional. Sets which size and style of the application font to use. The default is SansSerifSmall for text elements and SansSerif for controls (such as check_box and button.

Values: SansSerifSmall, SansSerif, SansSerifBig, SansSerifBold, Monospace

String: font="SansSerifSmall"

font.size

Optional. Sets the font size. The default size is defined by the font (e.g. SansSerifSmall is 'Small', SansSerif is 'Medium').

Values:

  • Monospace = 9 pt
  • Small = 9 pt
  • Medium = 10 pt
  • Large = 12 pt
  • Huge = 16 pt

String: font_size="Small"

font.style

Optional. Sets the font style. The default size is NORMAL.

Values:

  • BOLD
  • ITALIC
  • BOLD|ITALIC
  • UNDERLINE

Example: font.style="BOLD|ITALIC"

style

Deprecated.

halign

Optional. Controls horizontal alignment of label on button face. Options are "left", "center" and "right".

valign

Deprecated.