ui.Component¶

Overview¶

Base type common to all user interface elements. The following components inherit from this:

• Decorative: Line, Rectangle, Text, Sprite, Model, Model Group
• Interactive: Button, Check, List, Input Field, Slider, Combo Field, Carousel, Radio Group
• Layout: Layer, Panel, Grid Paged Layer, Group Box, Paged Carousel
  • See also Component Collection for methods and properties shared by these components

Examples¶

-- Resize a component to 100x200 interface units and move it to 50 units from the top left of its parent
component:SetPos(50, 50)
component:SetSize(100, 200)

-- Centre the component on its parent and resize it to 300x150 interface units
component:SetPos(0, 0, 0.5, 0.5, -0.5, -0.5)
component:SetSize(300, 150)

-- Resize a component to 30% of the parent's width and 100% of the height, and place it in the centre
component:SetPos(0, 0, 0.3, 1.0, -0.5, 0.0)
component:SetSize(0, 0, 0.3, 1.0)

-- Use a specific style
component.stylesheetID = myStyleID
-- Change the colour to red with a slight transparency
component.colour = Vector4.new(1.0, 0.0, 0.0, 0.7)
-- Make it more transparent
component.alpha = component.alpha - 50
-- Set the colour to blue using a hex colour code
component.rgba = 0x0000FF77

Positioning and Layout¶

Methods¶

SetX/SetY/SetPos¶

function Component:SetX(x : Int, parentPercentageX : Float?, selfPercentageX : Float?)
function Component:SetY(y : Int, parentPercentageY : Float?, selfPercentageY : Float?)

function Component:SetPos(
    x : Int, y : Int,
    parentPercentageX : Float?, parentPercentageY : Float?,
    selfPercentageX : Float?, selfPercentageY : Float?)

Moves this component's origin to the provided coordinates, optionally taking into account the parent's dimensions, and this component's own dimensions.

-- Move the component to 100 units from the left and 50 units from the top
component:SetX(100)
component:SetY(50)

-- Place the component's origin on the parent's center and offset it 50 units to the left
component:SetX(-50, 0.5)
component:SetY(0, 0.5)

-- Right-align the component on its parent, assuming it has a width of 125
component:SetX(-125, 1.0)

-- Right-align the component on its parent, taking into account its actual width
component:SetX(0, 1.0, -1.0)

-- Center the component on its parent
component:SetX(0, 0.5, -0.5)
component:SetY(0, 0.5, -0.5)

-- Right-align the component to the parent's center
component:SetX(0, 0.5, -1.0)
component:SetY(0, 0.5, -0.5)

SetWidth/SetHeight/SetSize¶

function Component:SetWidth(x : Int, parentPercentageX : Float?)
function Component:SetHeight(y : Int, parentPercentageY : Float?)
function Component:SetSize(x : Int, y : Int, parentPercentageX : Float?, parentPercentageY : Float?)

Sets the width/height for this component, optionally taking into account the parent's dimensions.

-- Resize this component to 100x50
component:SetWidth(100)
component:SetHeight(50)
-- or
component:SetSize(-50, 50)

-- Resize this component to 50% of the parent's dimensions, but make it 50 interface units narrower
component:SetWidth(-50, 0.5)
component:SetHeight(0, 0.5)
-- or
component:SetSize(-50, 0, 0.5, 0.5)

SetAspectRatio¶

function Component:SetAspectRatio(widthRatio : Int, heightRatio : Int, mode : ui.AspectRatioMode)

Sets the target aspect ratio the component should follow, and how it should be applied. Can also be used to disable aspect ratio scaling.

-- Set the component to a standard 16:9 aspect ratio, scaling its width
component:SetAspectRatio(16, 9, ui.AspectRatioMode.SCALE_WIDTH)

-- Disable aspect ratio scaling
component:SetAspectRatio(1, 1, ui.AspectRatioMode.NONE)

Destroy¶

function Component:Destroy()

Destroys this component, along with any other components that might have been attached to it.

MoveToFront/MoveToBack¶

function Component:MoveToFront()
function Component:MoveToBack()

Moves this component to the front/back of the render order, causing it to draw on top/below of components that have the same parent.

UpdateLayout¶

function Component:UpdateLayout()

Triggers a layout update on this component.

Properties¶

Handling Events¶

Components can set as listeners for certain events, allowing developers to trigger actions in response. These range from events triggered on that component, such as mouse clicks, to global events, such as variable transmissions.

ui.Hook¶

The ui.Hook table contains a list of all potential event hooks that can be attached to a component.

Subscribe¶

function Component:Subscribe(hook : ui.Hook, callback : function (...) -> Bool?)
function Component:Subscribe(hook : ui.Hook, id : String, callback : function (...) -> Bool?)

Subscribes a listener for an event hook, setting a callback to be triggered whenever this event occurs, and optionally assigning it an ID allowing it to be referenced to in the future.

local myComponent = ...
myComponent:Subscribe(ui.Hook.ONCLICK, "a", function () log("Hello") return true end)
-- Or
myComponent:Subscribe(ui.Hook.ONCLICK, "b", function () log("World") return true end)

-- Clicks yield "Hello World"

local myComponent = ...
myComponent:Subscribe(ui.Hook.ONCLICK, "a", function () log("Hello") return true end)
-- Or
myComponent:Subscribe(ui.Hook.ONCLICK, "a", function () log("World") return true end)

-- Clicks yield "World"

local myComponent = ...
myComponent:Subscribe(ui.Hook.ONCLICK, "a", function () log("Hello") return false end)
-- Or
myComponent:Subscribe(ui.Hook.ONCLICK, "b", function () log("World") return true end)

-- Clicks yield "Hello"

Unsubscribe¶

function Component:Unsubscribe(hook : ui.Hook)
function Component:Unsubscribe(hook : ui.Hook, id : String)

Removes the listener set for the specified hook with the provided ID, or the default listener for that hook if omitted, from that component.

local myComponent = ...
myComponent:Subscribe(ui.Hook.ONCLICK, "myHookName", function () log("Hello World") end)
-- Later on
myComponent:Unsubscribe(ui.Hook.ONCLICK, "myHookName")

UnsubscribeAll¶

function Component:UnsubscribeAll(hook : ui.Hook)

Removes all event listeners of the specified type from this component associated with the current plugin.

Visual Properties¶

State Properties¶

The following properties relate to how the user interacts with the component and how the component reacts to said interactions.

Interface Properties¶

Restricted Components¶

In some cases, components may be flagged as restricted, preventing certain operations from working from the Lua-side, or resulting in them yielding default values instead.

Components can be intentionally tagged as restricted through the Component:FlagRestricted() function, with the restricted status being verifiable via component.isRestricted.