Style Sheets¶

Overview¶

Style sheets bundle together multiple visual parameters for various component types in a single reusable object.

You can use style sheets to achieve a consistent visual across your plugin and the game, while also simplifying interface creation since you can just specify the style sheet to use instead of the individual sprites, margins, colours, etc, for each component.

Usage¶

It's straightforward to access or create stylesheets, only requiring the user to index into ui.StyleSheets with the ID of an built-in stylesheet (obtainable from id.StyleSheet), or with a new ID.

Once a stylesheet has been retrieved, you then use an entry from the ui.StyleValue table, which contains all of the currently available style properties, as an index into the stylesheet to retrieve or modify the value for that property.

Info

Currently style sheets can only be assigned integer properties.

Warning

While you can access/store properties other than those contained in the ui.StyleValue table, it is not recommended as those properties may clash with future additions to ui.StyleValue.

Example

Setting a component's style

myButtonComponent.stylesheetID = id.StyleSheet.BUTTON_DEFAULT

Accessing existing styles

local buttonTint = ui.StyleSheets[id.StyleSheet.BUTTON_DEFAULT][ui.StyleValue.button.tint.rgb]
print("Default button tint =", buttonTint)

Creating a new style

-- StyleSheet IDs are unique
local myStyleSheetID = 10000
ui.StyleSheets[myStyleSheetID][ui.StyleValue.button.tint.rgb] = 0xFF0000
ui.StyleSheets[myStyleSheetID][ui.StyleValue.button.tint.alpha] = 100

-- Can set parents dynamically, allowing a stylesheet to "inherit" properties
ui.StyleSheets[myStyleSheetID].parent = ui.StyleSheets[id.StyleSheet.BUTTON_DEFAULT]

-- Can then set the style on a component
component.stylesheetID = myStyleSheetID

-- Can also access style data manually and use it
local buttonTint = ui.StyleSheets[myStyleSheetID][ui.StyleValue.button.tint.rgb]
component.rgb = buttonTint

ui.StyleSheet¶

Methods¶

Index¶

ui.StyleSheet[property : Uint] -> Int?
ui.StyleSheet[property : Uint] = value : Int

Gets or sets the value for the specified property in this stylesheet.

Info

When retrieving the value for a missing entry, the entire parent hierarchy gets checked for that same property until it is found or there are no more parents.

Parameter	Type	Description
property	Uint	Number representing the style property to search for. Can be an arbitrary number but prefer using a property listed in the `ui.StyleValue` table for consistency and safety, as the underlying property IDs may change in the future.
value	Int	The value to set for that property.

Getter Returns	Description
Int?	The value of the specified property, or nil if not found.

GetValue¶

function ui.StyleSheet:GetValue(property : Uint) -> Int?

Attempts to retrieve the value for the specified property from this stylesheet, or if missing, from its parent.

Info

If an entry is missing, the entire parent hierarchy gets checked for that same property until it is found or there are no more parents.

Parameter	Type	Description
property	Uint	Number representing the style property to search for. Can be an arbitrary number but prefer using a property listed in the `ui.StyleValue` table for consistency and safety, as the underlying property IDs may change in the future.

Returns	Description
Int?	The value of the specified property, or nil if not found.

SetValue¶

function ui.StyleSheet:SetValue(property : Uint, value : Int)

Sets the value for the specified property on this stylesheet.

Warning

Currently, changing a property value will not update that stylesheet's users, and instead you must re-assign the stylesheet to trigger an update.

Parameter	Type	Description
property	Uint	Number representing the style property to search for. Can be an arbitrary number but prefer using a property listed in the `ui.StyleValue` table for consistency and safety, as the underlying property IDs may change in the future.
value	Int	The value to set for that property.

HasValue¶

function ui.StyleSheet:HasValue(property : Uint) -> Bool

Checks if the specified property exists on this stylesheet or its parents.

Info

If an entry is missing, the entire parent hierarchy gets checked for that same property until it is found or there are no more parents.

Parameter	Type	Description
property	Uint	Number representing the style property to search for. Can be an arbitrary number but prefer using a property listed in the `ui.StyleValue` table for consistency and safety, as the underlying property IDs may change in the future.

Returns	Description
Bool	True if the property exists, false otherwise.

Properties¶

Name	Type	Description
id	Int	Numeric ID associated with this stylesheet.
parent	ui.StyleSheet	Parent stylesheet for this.
parentID	Int	Numeric ID associated with the parent for this stylesheet, or `-1` if no parent is specified.

ui.StyleSheets¶

The container of all available stylesheets, can be indexed into using IDs to retrieve existing stylesheets or create new ones.

Methods¶

Index¶

ui.StyleSheets[styleSheetID : Int] -> ui.StyleSheet

Retrieves the existing stylesheet associated with the provided ID, or creates a new one if missing.

Parameter	Type	Description
styleSheetID	Int	Numeric ID associated with the stylesheet to be retrieved.

Returns	Description
ui.StyleSheet	The existing or newly created stylesheet, associated with the provided ID.

Find¶

function ui.StyleSheets:Find(styleSheetID : Int) -> ui.StyleSheet?

Attempts to retrieve the existing stylesheet associated with the provided ID.

Parameter	Type	Description
styleSheetID	Int	Numeric ID associated with the stylesheet to be retrieved.

Returns	Description
ui.StyleSheet	The stylesheet associated with the provided ID, or nil if missing.

Contains¶

ui.function StyleSheets:Contains(styleSheetID : Int) -> Bool

Checks whether a stylesheet associated with the provided ID already exists.

Parameter	Type	Description
styleSheetID	Int	Numeric ID associated with the stylesheet to check.

Returns	Description
Bool	True if there's already a stylesheet with the provided ID, false otherwise.

While there are a large number of styles available which can be accessed through the id.StyleSheet table, the following represent good defaults for plugins to use:

Component Type	Recommended Style	Alternative Styles
Button	id.StyleSheet.BUTTON_DEFAULT	id.StyleSheet.BUTTON_CORNERED_BOLD_NEUTRAL id.StyleSheet.BUTTON_CORNERED_BOLD_POSITIVE id.StyleSheet.BUTTON_CORNERED_BOLD_NEGATIVE
Check	id.StyleSheet.CHECKBOX_DEFAULT	id.StyleSheet.CHECKBOX_DEFAULT_LEFT_ALIGNED id.StyleSheet.CHECKBOX_DEFAULT_RIGHT_ALIGNED
InputField	id.StyleSheet.INPUT_DEFAULT	-
RadioGroup	id.StyleSheet.RADIO_DEFAULT	-
List	id.StyleSheet.DROPDOWN_DEFAULT¹	-
ComboField	id.StyleSheet.COMBO_DEFAULT	-
GroupBox	id.StyleSheet.GROUPBOX_DEFAULT	-
Carousel	id.StyleSheet.CAROUSEL_DEFAULT	-
PagedCarousel	id.StyleSheet.PAGED_CAROUSEL_DEFAULT	id.StyleSheet.PAGED_CAROUSEL_FULL id.StyleSheet.PAGED_CAROUSEL_SINGLE id.StyleSheet.PAGED_CAROUSEL_TRIPLE
PagedLayer	id.StyleSheet.PAGED_LAYER_DEFAULT	-
RadialProgressOverlay	id.StyleSheet.RADIAL_DEFAULT	id.StyleSheet.RADIAL_CIRCLE id.StyleSheet.RADIAL_SQUARE
Slider	id.StyleSheet.SLIDER_DEFAULT	id.StyleSheet.SLIDER_WIDE

Although this is a dropdown style, you can just set the maximum number of dropdown entries to 0 to display the component's contents as a regular list instead. ↩

Style Sheets¶

Overview¶

Usage¶

ui.StyleSheet¶

Methods¶

Index¶

GetValue¶

SetValue¶

HasValue¶

Properties¶

ui.StyleSheets¶

Methods¶

Index¶

Find¶

Contains¶

Recommend Built-in Styles¶