Common Types¶

Overview¶

The types listed here represent core types used throughout the UI system.

Types¶

ui.Pos¶

Used to represent positions, taking into account absolute horizontal and vertical offsets, as well as a specific percent of an arbitrary parent component's width and height, and a component's own width and height.

Since position objects just store offsets and percentages, it's only when associated with a component that they can be used to calculate a final position value.

-- Initialised to zeros
local zero = ui.Pos.new()

-- Set to 50,-20
local offsets = ui.Pos.new(50, -20)

-- Centred on the parent, with a 50,-20 offset
local mixed = ui.Pos.new(50, -20, 0.5, 0.5)

-- Right-aligned on the parent, and centred vertically on itself
local rightAligned = ui.Pos.new(0, 0, 1.0, 0.0, -1.0, 0.5)

Constructor¶

function ui.Pos.new() -> Pos
function ui.Pos.new(other : Pos) -> Pos
function ui.Pos.new(x : Int, y : Int) -> Pos
function ui.Pos.new(x : Int, y : Int, xParentPc : Float, yParentPc : Float) -> Pos
function ui.Pos.new(x : Int, y : Int, xParentPc : Float, yParentPc : Float, xSelfPc : Float, ySelfPc : Float) -> Pos

Creates a new position object.

Properties¶

ui.Size¶

Used to represent sizes, taking into account absolute horizontal and vertical offsets, as well as a specific percent of an arbitrary parent component's width and height, as well of a component's own width and height.

Since size objects just store offsets and percentages, it's only when associated with a component that they can be used to calculate a final size value.

-- Initialised to zeros
local zero = ui.SizePos.new()

-- Set to 50,20
local offsets = ui.Size.new(50, 20)

-- Covering 50% of the parent's area, plus 50 units horizontally, and shrunk vertically by 20 units
local mixed = ui.Size.new(50, -20, 0.5, 0.5)

-- Spans the entire parent horizontally, with a 50 interface unit height
local spanHorizontal = ui.Size.new(0, 50, 1.0, 0.0)

Constructor¶

function ui.Size.new() -> Size
function ui.Size.new(other : Size) -> Size
function ui.Size.new(width : Int, height : Int) -> Size
function ui.Size.new(width : Int, height : Int, widthParentPc : Float, heightParentPc : Float) -> Size

Creates a new position object.

Properties¶

ui.TextData¶

Used to represent a text element within a UI component. These contain properties necessary for drawing text, as well as the actual text to draw.

ui.TextDataConfig¶

TextDataConfigs are simplified versions of TextData, containing only the properties necessary for drawing text, allowing them to be initialised separately and shared across components.

Essentially they contain all of the same properties and data, except the content property is omitted and no methods are available.

local reusableTextCfg = ui.TextDataConfig.new()
reusableTextCfg.font = museo_sans_15pt_regular
reusableTextCfg.alignHorizontal = ui.AlignMode.CENTRE
reusableTextCfg.alignVertical = ui.AlignMode.CENTRE
reusableTextCfg.colour = Vector4.new(0.0, 1.0, 0.7, 1.0)

aComponent.text:SetConfig(reusableTextCfg)
anotherComponent.text:SetConfig(reusableTextCfg)

Methods¶

AlignTo¶

function ui.TextData:AlignTo(alignment : ui.AlignMode)
function ui.TextData:AlignTo(horizontalAlignment : ui.AlignMode, verticalAlignment : ui.AlignMode)

Sets the alignment for this text.

SetConfig¶

function ui.TextData:SetConfig(config : ui.TextDataConfig)

Sets this TextData's properties based on the provided config values.

GetConfigCopy¶

function ui.TextData:GetConfigCopy() -> ui.TextDataConfig

Returns a copy of this TextData's config, allowing it to be used elsewhere.

Properties¶

ui.SpriteData¶

Used to represent a sprite element within a UI component. These contain properties necessary for drawing sprite, as well as the actual sprite resource to draw.

Sprite resources can contained tiled visuals, or be split into multiple segments, up to a 3x3 segmented sprite, containing segments for the four sides, the 4 corners, and the centre region.

ui.SpriteDataConfig¶

SpriteDataConfigs are simplified versions of SpriteData, containing only the properties necessary for drawing a sprite, allowing them to be initialised separately and shared across components.

Essentially they contain all of the same properties and data, except the sprite, spriteID, and runtimeSprite properties are omitted and no methods are available.

RuntimeSprite¶

An opaque object representing a sprite generated at runtime.

These are generally sprites representing objects associated with the containing components, such as those used for inventory icons.

Image Layout¶

Sprites can be split into segments via the visualMargin property.

For example by specifying left and right margins you obtain a 3x1 segments sprite, with the left and right segments having a fixed width and stretching vertically, while the middle one stretches horizontally and vertically:

While by specifying top and bottom margins you obtain a 1x3 segments sprite, with the top and bottom segments having a fixed height and stretch horizontally, while the middle one stretches horizontally and vertically:

Or you can specify all margins, resulting in a 3x3 segments sprite, where the corners don't stretch at all, and the edges stretch only in one direction, while the middle segment stretches horizontally and vertically:

Methods¶

SetConfig¶

function ui.SpriteData:SetConfig(config : ui.SpriteDataConfig)

Sets this SpriteData's properties based on the provided config values.

GetConfigCopy¶

function ui.SpriteData:GetConfigCopy() -> ui.SpriteDataConfig

Returns a copy of this SpriteData's config, allowing it to be used elsewhere.

Properties¶

ui.Margin¶

Margins are used to represent distances from the sides of a region.

They're commonly used when defining slices for 3x3 sprites, or specifying the content regions for UI components.

Constructors¶

function ui.Margin.new() -> Margin
function ui.Margin.new(allSides : uint8) -> Margin
function ui.Margin.new(left : uint8, top : uint8, right : uint8, bottom : uint8) -> Margin

Constructs a new margin object with the provided values, or with all sides initialised to zero if omitted.

Properties¶

ui.ScrollBar¶

Provides controls for scrolling a component's contents.

Properties¶

Enumerations¶

ui.ComponentType¶

Enumeration representing a component's type.

ui.AlignMode¶

Enumeration identifying how an element should be aligned.

ui.AspectRatioMode¶

Enumeration identifying how an element should be scaled based on its aspect ratio.