UIComponents

Script objects called uicomponents may be obtained from the user-interface, from code functions such as battle_manager:ui_component or script functions like find_uicomponent. They represent visible components within the UI hierarchy.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Usage

Once a handle to a uicomponent is obtained, functions may be called on it to query or modify its state in the following form.

Example - Specification:

<object_name>:<function_name>(<args>)

Example - Creation and Usage:

local uic_root = core:get_ui_root()
local x, y = uic_root:Dimensions()        -- calling a function on the object once created
out("Screen resolution is [" .. x .. ", " .. y .. "]")
Screen resolution is [1600, 900]
Back to top

General Queries

uicomponent:IsValid()

Returns true if this UIComponent handle is valid (internal component ptr has NOT been deleted)

Returns:

  1. boolean is_valid

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 575

uicomponent:Id()

Returns the string name of this uicomponent.

Returns:

  1. string name

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 589

uicomponent:CallbackId()

Returns the callback id of this uicomponent.

Returns:

  1. string callback id

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 606

uicomponent:Address()

Returns the address of this uicomponent, which is used for certain other functions on this interface such as uicomponent:Adopt.

Returns:

  1. address uicomponent address

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 623

uicomponent:Layout()

Calls the layout function for the uicomponent, forcing it to refresh its display.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 636

uicomponent:IsDragged()

Returns whether this uicomponent is currently being dragged around the screen by the player left-clicking and dragging.

Returns:

  1. boolean is dragged

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 649

uicomponent:IsMouseOverChildren()

Returns whether or not the mouse cursor is currently over this uicomponent or any of its children.

Returns:

  1. boolean cursor over children

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 666

uicomponent:SetContextObject(cco Takes a cco to set on the component)

Sets a context object on a component, to initialise any ContextCallbacks to show information for the supplied cco

Parameters:

1

cco

Takes a cco to set on the component

Returns:

  1. nil

Example:

uic_example:SetContextObject(cco("CcoBattleUnit", "1001"));

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 683

uicomponent:GetContextObjectId(string context type id)

Gets the context object id for the supplied type that is stored on the component, to allow you to perform queries/commands on the context with (get_context_value/call_context_command).

Parameters:

1

string

context type id

Returns:

  1. nil

Example:

local object_id = UIComponent("building_slot").GetContextObjectId("CcoCampaignBuildingSlot")
local building_slot_tooltip = effect.get_context_value("CcoCampaignBuildingSlot", object_id, "Tooltip")

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 711

uicomponent:GetContextObject(string context type id)

Gets the context object (cco lua type) for the supplied type that is stored on the component

Parameters:

1

string

context type id

Returns:

  1. object context object (cco)

Example:

local cco_building_slot = uic_example:GetContextObject("CcoCampaignBuildingSlot");

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 743

uicomponent:AddScriptEventReporter()

Adds a ScriptEventReporter callback to the component to allow it to notify the script of more 'spammy' events such as ComponentMouseOn, ComponentMouseOff, an ComponentAnimationFinished

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 773

Back to top

States

uicomponent:CurrentState()

Returns the name of the current state of the uicomponent.

Returns:

  1. string state name

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 799

uicomponent:SetState(string state name)

Sets the state of the uicomponent to the specified state name.

Parameters:

1

string

state name

Returns:

  1. boolean State was successfully set

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 816

uicomponent:NumStates()

Returns the number of states this uicomponent contains.

Returns:

  1. number number of states

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 837

uicomponent:GetStateByIndex([number state index])

Returns the name of the state at the specified index.

Parameters:

1

number

optional, default value=0

state index

Returns:

  1. string state name

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 858

Back to top

Position and Dimensions

uicomponent:Width()

Returns the current width of the uicomponent in pixels.

Returns:

  1. number width

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 887

uicomponent:Height()

Returns the current height of the uicomponent in pixels.

Returns:

  1. number height

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 903

uicomponent:Dimensions()

Returns the width and height of the uicomponent in pixels.

Returns:

  1. number width
  2. number height

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 919

uicomponent:Bounds()

Returns the maximum width and height of this uicomponent, including any of its children.

Returns:

  1. number width
  2. number height

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 937

uicomponent:Position()

Returns the position of the top-left corner of the uicomponent, from the top-left corner of the game window/screen.

Returns:

  1. number x, X co-ordinate in pixels.
  2. number y, Y co-ordinate in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 973

uicomponent:RelativePosition()

Returns the relative position of the uicomponent

Returns:

  1. number x, X co-ordinate in pixels.
  2. number y, Y co-ordinate in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 992

uicomponent:MoveTo(number x, number y)

Sets the uicomponent to a new screen position, measured from the top-left corner of the game window/screen.

Parameters:

1

number

X co-ordinate in pixels.

2

number

Y co-ordinate in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1011

uicomponent:SetMoveable(boolean is moveable)

Sets this uicomponent to be moveable or not.

Parameters:

1

boolean

is moveable

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1032

uicomponent:IsMoveable()

Returns whether this uicomponent is moveable or not.

Returns:

  1. boolean is moveable

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1049

uicomponent:Resize(number width, number height, [boolean resize children])

Resizes the uicomponent. The uicomponent may be need to set to be resizeable before calling this - this can be done with uicomponent:SetCanResizeHeight and uicomponent:SetCanResizeWidth.

Parameters:

1

number

New width of uicomponent in pixels.

2

number

New height of uicomponent in pixels.

3

boolean

optional, default value=true

Also resize children.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1064

uicomponent:SetCanResizeHeight([boolean can resize ])

Allows or disallows the height of this uicomponent to be changed by code or script.

Parameters:

1

boolean

optional, default value=true

can resize    

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1089

uicomponent:SetCanResizeWidth([boolean can resize])

Allows or disallows the width of this uicomponent to be changed by code or script.

Parameters:

1

boolean

optional, default value=true

can resize

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1113

uicomponent:ResizeTextResizingComponentToInitialSize(number width, number height)

Many uicomponents are set to resize based on the text they are displaying. Despite this, it is sometimes desireable to resize these uicomponents (to set a different width for a text box that can grow, for example). However, any attempt by script to resize these uicomponents will be overriden by the text resizing behaviour.
This function provides a method of working around this, temporarily disabling the text-resizing behaviour so that the desired resize can be applied.

Parameters:

1

number

Width in pixels.

2

number

Height in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1137

uicomponent:TextDimensions()

Returns the dimensions of the text displayed on the uicomponent in its current state, if any.

Returns:

  1. number width in pixels
  2. number height in pixels
  3. number number of lines

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1160

uicomponent:TextDimensionsForText(string text)

Returns the dimensions of the some supplied text, were it to be displayed on the uicomponent in its current state.

Parameters:

1

string

text

Returns:

  1. number width in pixels
  2. number height in pixels
  3. number number of lines

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1179

uicomponent:WidthOfTextLine(string text line)

Returns the width of a text line on the current uicomponent.

Parameters:

1

string

text line

Returns:

  1. number width in pixels

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1203

uicomponent:TextXOffset()

Returns the text x offset values of the current state. This is the padding around the left and right side of any text displayed on the current state of the uicomponent. Offset values greater than 0 enforce a border around the edge of the text so that it does not run right up to the edge of the displayed component.

Returns:

  1. number left offset
  2. number right offset

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1225

uicomponent:TextYOffset()

Returns the text y offset values of the current state. This is the padding around the top and bottom of any text displayed on the current state of the uicomponent. Offset values greater than 0 enforce a border around the edge of the text so that it does not run right up to the edge of the displayed component.

Returns:

  1. number top offset
  2. number bottom offset

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1246

uicomponent:SetTextXOffset(number left offset, number right offset)

Sets the text x offset values of the current state. This is the padding around the left and right side of any text displayed on the current state of the uicomponent. Offset values greater than 0 enforce a border around the edge of the text so that it does not run right up to the edge of the displayed component.

Parameters:

1

number

left offset

2

number

right offset

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1267

uicomponent:SetTextYOffset(number top offset, number bottom offset)

Sets the text y offset values of the current state. This is the padding around the top and bottom of any text displayed on the current state of the uicomponent. Offset values greater than 0 enforce a border around the edge of the text so that it does not run right up to the edge of the displayed component.

Parameters:

1

number

top offset

2

number

bottom offset

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1291

uicomponent:SetTextHAlign(string horizontal text alignment)

Sets the horizontal text alignment setting of the current state to the supplied alignment. Valid string alignment values are "left", "centre" and "right".

Parameters:

1

string

horizontal text alignment

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1315

uicomponent:GetTextHAlign()

Returns the horizontal text alignment setting of the current state as a string. Valid alignment values are "left", "centre" and "right".

Returns:

  1. string horizontal text alignment

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1342

uicomponent:SetTextVAlign(string vertical text alignment)

Sets the vertical text alignment setting of the current state to the supplied alignment. Valid string alignment values are "top", "centre" and "bottom".

Parameters:

1

string

vertical text alignment

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1369

uicomponent:GetTextVAlign()

Returns the vertical text alignment setting of the current state as a string. Valid alignment values are "top", "centre" and "bottom".

Returns:

  1. string vertical text alignment

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1397

Back to top

Docking

The uicomponent:DockingPoint and uicomponent:SetDockingPoint functions both express docking points as integer values. The mapping between these values and the docking points is given here.

Docking PointNumber
DOCK_POINT_NONE0
DOCK_POINT_TL1
DOCK_POINT_TC2
DOCK_POINT_TR3
DOCK_POINT_CL4
DOCK_POINT_C5
DOCK_POINT_CR6
DOCK_POINT_BL7
DOCK_POINT_BC8
DOCK_POINT_BR9

uicomponent:DockingPoint()

Returns the docking point of this uicomponent. Valid returned values are given in the table at the top of this section.

Returns:

  1. number docking point

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1439

uicomponent:SetDockingPoint(number dock point)

Sets the docking point of the uicomponent to the specified value. Valid values are given in the table at the top of this section.

Parameters:

1

number

dock point

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1457

uicomponent:SetDockOffset(number x offset, number y offset)

Sets a docking offset for this component, which offsets where the component is drawn from the docking point set.

Parameters:

1

number

X offset in pixels.

2

number

Y offset in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1476

uicomponent:GetDockOffset()

Returns the docking offset set for this component, which offsets where the component is drawn from the docking point set.

Returns:

  1. number x offset in pixels.
  2. number y offset in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1497

Back to top

Searching and Hierarchy

uicomponent:Find(variable identifier, [boolean assert on fail])

Finds and returns a child of this uicomponent by string name or by numeric index. If a numeric index is supplied, the immediate child uicomponent corresponding to this number is returned. If a string name is supplied, a recursive search is made through all children/descendants of this uicomponent. The first that is found with a matching name is returned.
If the search target was not found then nil is returned. If it was found then it is returned as a component address, which must be cast to a uicomponent script object using the UIComponent function. The find_uicomponent function provided by the script libraries does this automatically, so it's recommended to use that function in place of this function.

Parameters:

1

variable

Search target, identified by index number or string name.

2

boolean

optional, default value=true

Assert if no matching uicomponent could be found.

Returns:

  1. nil

Example - Find a descendent of uic_parent with the name child_a:

local uic_child_a = uic_parent:Find("child_a")
if uic_child_a then
    uic_child_a = UIComponent(uic_child_a)
end

Example - Perform an operation on each immediate child of uic_parent:

for i = 0, uic_parent:ChildCount() - 1 do
    local uic_child = UIComponent(uic_parent:Find(i))
    -- do stuff
end

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1524

uicomponent:SequentialFind(... identifiers)

Finds and returns a child of this uicomponent by a series of string names and numeric indexes. The function will step through each argument, attempting to find the uicomponent specified, and using that as the parent from which to find the next. A numeric index argument finds an immediate child of the current search subject, whereas a string name initiates a recursive search through all children/descendants of this uicomponent.

Parameters:

1

...

One or more search targets in a sequence. Each search target should be an index number or string name.

Returns:

  1. address of found component

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1590

uicomponent:FindByScriptTag(string script tag unique id that has been specified in the layout)

Finds a component that has been tagged in a layout with the ScriptTag callback using the value of the Context Function id as the unique id to match against. It is a more robust mechanism of searching that sequential find as it is independant from layout order so is less likely to break from layout changes.

Parameters:

1

string

script tag unique id that has been specified in the layout

Returns:

  1. address of found component

Example:

uic = UIComponent(root:FindByScriptTag("example_tag"))

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1641

uicomponent:FindByGuid(string GUID that has been specified in the layout)

Finds a component via its guid (globally unique identifier). A 16 digit hex code that is guranteed to be unique across the game. No good for finding dynamic things, but useful for finding things that exist in layouts.

Parameters:

1

string

GUID that has been specified in the layout

Returns:

  1. address of found component

Example:

uic = UIComponent(root:FindByGuid("730A2C75-2C65-4337-BCB8189F0C65FAC2"))

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1666

uicomponent:ChildCount()

Returns the number of immediate children this uicomponent has. These children can be individually retrieved by using uicomponent:Find and supplying a numeric value.

Returns:

  1. number number of children

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1692

uicomponent:Parent()

Returns a link to the parent of the uicomponent. This is provided as a component address that must be cast to be a usable uicomponent script object using the UIComponent function.

Returns:

  1. address parent address

Example:

uic_parent = UIComponent(uic_child:Parent())

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1709

uicomponent:Adopt(address uicomponent address, [number insertion index])

Compels this uicomponent to adopt a supplied uicomponent, which will then become a child of this uicomponent. The supplied uicomponent is removed from its previous parent. The target uicomponent must be supplied by its address, which may be retrieved with uicomponent:Address.
An insertion index may optionally be supplied, which determines where in this uicomponent's list of children this new child will be inserted. This can determine the display order in certain circumstances. By default, the new child is added to the end of the list.

Parameters:

1

address

uicomponent address

2

number

optional, default value=-1

insertion index

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1791

uicomponent:Divorce(address child)

Divorces the supplied child uicomponent from the subject uicomponent. The child uicomponent should be supplied by its address, which may be retrieved with uicomponent:Address.
Once divorced, the child uicomponent is not destroyed but goes into an orphan list, from where it may later be adopted by another uicomponent. Orphaned uicomponents are not rendered.

Parameters:

1

address

child

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1819

Back to top

Component Creation and Destruction

uicomponent:CreateComponent(string uicomponent name, string file path)

Creates a new uicomponent as the child of this uicomponent. A name for the new uicomponent must be supplied, as well as a filepath to a layout file containing a template for the new uicomponent. The address of the new uicomponent is returned - this must be cast to be a uicomponent using the UIComponent function.

Parameters:

1

string

uicomponent name

2

string

file path

Returns:

  1. address address of created uicomponent

Example - Create the scripted subtitles uicomponent as a child of the root uicomponent:

local uic_scripted_subtitles = UIComponent(ui_root:CreateComponent("scripted_subtitles", "UI/Campaign UI/scripted_subtitles"));

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1847

uicomponent:CopyComponent(string uicomponent name)

Creates a copy of this uicomponent with the supplied name. The component is created as a sibling of the copied component, so they both share the same parent.

Parameters:

1

string

uicomponent name

Returns:

  1. address address of created uicomponent

Example - Create the scripted subtitles uicomponent as a child of the root uicomponent:

local uic_list_entry = UIComponent(uic_list_entry_template:CopyComponent("list_entry_1"));

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1879

uicomponent:Destroy()

Destroys this uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1919

uicomponent:DestroyChildren()

Destroys all children of this uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1932

Back to top

Text and Tooltips

uicomponent:SetText(string localised text, string text source)

Sets the text on all available states of the uicomponent to the supplied text. Localised text must be specified - common.get_localised_string can be used to look this up from anywhere in the database.

Parameters:

1

string

Localised text.

2

string

source of text in format of a stringtable key (tablename_recordname_key)

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 1964

uicomponent:SetStateText(string localised text, string text source)

Sets the text on the current state of the uicomponent to the supplied text. Localised text must be specified - common.get_localised_string can be used to look this up from anywhere in the database.

Parameters:

1

string

Localised text.

2

string

source of text in format of a stringtable key (tablename_recordname_key)

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2009

uicomponent:GetStateText()

Returns the text on the current state of the uicomponent along with its dimensions. This text will be localised.

Returns:

  1. string localised uicomponent text
  2. string text source for where text comes from in format of a stringtable key (tablename_recordname_key). Handy if getting text then setting again as require source for set, so can get from here to set it back again

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2054

uicomponent:SetTooltipText(string text, string text source, boolean set all states)

Sets the tooltip text of the current state of this uicomponent. An optional flag directs the function to apply this tooltip text to all states of the uicomponent. The text specified must already be localised - effect:get_localised_string can be used to retrieve localised text from anywhere in the database.

Parameters:

1

string

Localised tooltip text.

2

string

source of text in format of a stringtable key (tablename_recordname_key)

3

boolean

Set all states.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2081

uicomponent:GetTooltipText()

Returns the tooltip text of the current state of the uicomponent as a localised string.

Returns:

  1. string tooltip text
  2. string text source for where text comes from in format of a stringtable key (tablename_recordname_key). Handy if getting text then setting again as require source for set, so can get from here to set it back again

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2120

Back to top

Component Images

uicomponent:SetImageRotation(number image index, number rotation, [number pivot x], [number pivot y])

Performs a rotation of an image associated with the uicomponent. The image is specified by a 0-based numeric index of the images associated with this uicomponent. An optional pivot point can be specified, which sets a new pivot centre for the specified image.

Parameters:

1

number

Index value of image associated with uicomponent to rotate.

2

number

Amount by which to rotate the image in radians.

3

number

optional, default value=nil

X co-ordinate in pixels of the new pivot point of the image, relative to the top-left corner of the uicomponent.

4

number

optional, default value=nil

Y co-ordinate in pixels of the new pivot point of the image, relative to the top-left corner of the uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2155

uicomponent:SetImagePath(string image path, [number image index], [boolean resize])

Sets a new image path for an image associated with the uicomponent, replacing the original image with something new. Multiple images can be associated with a uicomponent - the index of the image to overwrite can be set with the second parameter or by setting a "script_icon_index" user property on the uicomponent with uicomponent:SetProperty. If an index value is not set with either of these methods then the first image, image 0, is swapped.
The uicomponent:GetImagePath and uicomponent:NumImages functions can be used to query images related to a uicomponent.

Parameters:

1

string

Path of image to load, from the working data folder.

2

number

optional, default value=0

Index of image associated with this uicomponent to overwrite the path of. This takes precedence over any set "script_icon_index" property.

3

boolean

optional, default value=false

Resize the image metric to the size of the image being specified. If this is not set, the incoming image will take the size of the old.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2186

uicomponent:GetImagePath([number image index])

Returns the path of an image associated with the subject uicomponent. The image is specified by a 0-based index.

Parameters:

1

number

optional, default value=0

Index of image to return the path of.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2227

uicomponent:GetImageDimensions([number image index])

Returns the width and height in pixels of an image associated with the subject uicomponent. The image is specified by a 0-based index.

Parameters:

1

number

optional, default value=0

Index of image to return the path of.

Returns:

  1. number image width
  2. number image height

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2258

uicomponent:NumImages()

Returns the number of images associated with the subject uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2290

Back to top

Component State Images

To be drawn on a uicomponent, an image has to first be associated with that uicomponent, and then further associated with a state. Only when the uicomponent is set to that state is the image drawn. Once associated with the uicomponent that image can then be associated with multiple states, with its position, colourisation and other parameters customised for each state. The functions in the previous section allow parameters of the image's association with the uicomponent, which would affect each component state that the image is displayed with, to be queried and changed. The parameters of an image's association with a particular state may be changed using the functions in this section.

In the source code, an image's association with the uicomponent is called a ComponentImage, and a ComponentImage's association with a particular state is called a ComponentImageMetrics. The functions described in this section relate to ComponentImageMetrics, therefore.

uicomponent:GetCurrentStateImageIndex(number state image index)

Returns the index of an image's association with this uicomponent, based on the index of that image's association with the current state. All indexes are 0-based.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number The index of this image on the uicomponent itself. This can be plugged into uicomponent:GetImagePath and other functions.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2315

uicomponent:NumCurrentStateImages()

Returns the number of images associated with the current state of this uicomponent.

Returns:

  1. number number of images

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2355

uicomponent:SetCurrentStateImageOpacity(number state image index, number opacity)

Sets the opacity of a specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

number

Desired opacity value, from 0-255.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2373

uicomponent:GetCurrentStateImageOpacity(number state image index)

Returns the opacity of a specified image associated with the current state of the uicomponent. The returned value will be between 0 and 255.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number Current opacity

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2404

uicomponent:GetCurrentStateImageWidth(number state image index)

Returns the width of a specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number width, Width in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2434

uicomponent:GetCurrentStateImageHeight(number state image index)

Returns the height of a specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number height, Height in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2464

uicomponent:GetCurrentStateImageDimensions(number state image index)

Returns the width and height of a specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number width, Width in pixels.
  2. number height, Height in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2494

uicomponent:ResizeCurrentStateImage(number state image index, number width, number height)

Sets the width and height of a specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

number

Width in pixels.

3

number

Height in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2525

uicomponent:CanResizeCurrentStateImageWidth(number state image index)

Returns whether the width can be resized of the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. boolean can resize width

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2558

uicomponent:CanResizeCurrentStateImageHeight(number state image index)

Returns whether the height can be resized of the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. boolean can resize height

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2588

uicomponent:SetCanResizeCurrentStateImageWidth(number state image index, boolean can resize)

Sets whether the width can be resized of the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

boolean

Can resize.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2618

uicomponent:SetCanResizeCurrentStateImageHeight(number state image index, boolean can resize)

Sets whether the height can be resized of the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

boolean

Can resize.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2649

uicomponent:SetCurrentStateImageDockingPoint(number state image index, number dock point)

Sets the docking point of the specified image associated with the current state of the uicomponent. Valid values are given in the table in the Docking section of this documentation.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

number

Dock point.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2680

uicomponent:GetCurrentStateImageDockingPoint(number state image index)

Gets the docking point of the specified image associated with the current state of the uicomponent. The value is returned as a number. Valid number values are given in the table in the Docking section of this documentation.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number dock point, Dock point.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2716

uicomponent:SetCurrentStateImageDockOffset(
  
number state image index,
  number
x offset in pixels.,
  number
y offset in pixels.
)

Sets the docking offset of the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

number

x offset in pixels.

3

number

y offset in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2752

uicomponent:GetCurrentStateImageDockOffset(number state image index)

Returns the docking offset set for the specified image associated with the current state of the uicomponent.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number x offset in pixels.
  2. number y offset in pixels.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2790

uicomponent:SetCurrentStateImageTiled(number state image index, boolean is tiled)

Sets whether the specified image associated with the current state of the uicomponent is tiled or not.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

boolean

is tiled

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2830

uicomponent:GetCurrentStateImageTiled(number state image index)

Returns whether the specified image associated with the current state of the uicomponent is tiled or not.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. boolean is image tiled.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2866

uicomponent:SetCurrentStateImageMargins(
  
number state image index,
  number
top margin,
  number
right margin,
  number
bottom margin,
  number
left margin
)

Sets the margin values for the specified image associated with the current state of the uicomponent. This affects how the image resizes, allowing a border around the image to stay a static size while the centre portion of the image scales.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

number

The size of the top margin in pixels.

3

number

The size of the right margin in pixels.

4

number

The size of the bottom margin in pixels.

5

number

The size of the left margin in pixels.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2902

uicomponent:GetCurrentStateImageMargins(number state image index)

Returns the margin values for the specified image associated with the current state of the uicomponent. The margins affect how the image resizes, allowing a border around the image to stay a static size while the centre portion of the image scales.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. number top margin value in pixels
  2. number right margin value in pixels
  3. number bottom margin value in pixels
  4. number left margin value in pixels

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2940

uicomponent:SetCurrentStateImageXFlip(number state image index, boolean flip)

Sets the x-flipped value for the specified image associated with the current state of the uicomponent. If set, this flips the image horizontally.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

boolean

Image should be horizontally flipped.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 2981

uicomponent:SetCurrentStateImageYFlip(number state image index, boolean flip)

Sets the y-flipped value for the specified image associated with the current state of the uicomponent. If set, this flips the image vertically.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

2

boolean

Image should be vertically flipped.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3016

uicomponent:GetCurrentStateImageFlip(number state image index)

Returns the x-flipped value for the specified image associated with the current state of the uicomponent. If set, this flips the image horizontally.

Parameters:

1

number

The index of the image's association with the current uicomponent state.

Returns:

  1. boolean is flipped horizontally.

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3051

Back to top

Visibility and Interactivity

uicomponent:Visible([boolean recursive])

Returns the visibility flag of this uicomponent. An optional argument also performs the test on all parent uicomponents up to the root, which will detect whether this uicomponent is visible but a parent is not.

Parameters:

1

boolean

optional, default value=false

Also test all parents up to the root.

Returns:

  1. boolean is visible

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3099

uicomponent:VisibleFromRoot()

Returns whether this uicomponent is visible, all its parents are visible, and the hierarchy is attached to the ui root. If the supplied parent (or an ancestor of it) is orphaned from the ui root this function will return false where uicomponent:Visible may return true, as the uicomponent would not be displayed if not attached to the ui root.

Returns:

  1. boolean is visible from root

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3129

uicomponent:SetVisible(boolean is visible)

Sets the visibility state of this uicomponent.

Parameters:

1

boolean

is visible

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3147

uicomponent:PropagateVisibility(boolean is visible)

Sets the visibility state of this uicomponent and all its children.

Parameters:

1

boolean

is visible

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3165

uicomponent:Opacity()

Returns the current opacity of the uicomponent. The returned value will be a number from 0-255.

Returns:

  1. number opacity

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3182

uicomponent:SetOpacity(number opacity value, [apply to all states])

Sets the opacity of the uicomponent. This should be specified as a number between 0 (transparent) and 255 (fully opaque). An optional flag also applies the opacity setting to all states of the uicomponent, as opposed to just the current state.

Parameters:

1

number

opacity value

2

apply

optional, default value=false

to all states

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3199

uicomponent:PropagateOpacity(number opacity value, [apply to all states])

Sets the opacity of this uicomponent and propagates the change to all its children. The opacity value should be specified as a number between 0 (transparent) and 255 (fully opaque). An optional flag also applies the opacity setting to all states of each uicomponent, as opposed to just the current state.

Parameters:

1

number

opacity value

2

apply

optional, default value=false

to all states

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3227

uicomponent:IsDisabled()

Returns whether this uicomponent is disabled or not. Disabled uicomponents do not respond to mouse clicks but still respond to the mouse cursor being placed over them.

Returns:

  1. boolean is interactive

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3256

uicomponent:SetDisabled(boolean is disabled)

Sets this uicomponent to be disabled or not. Disabled uicomponents do not respond to mouse clicks but still respond to the mouse cursor being placed over them.

Parameters:

1

boolean

is disabled

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3271

uicomponent:IsInteractive()

Returns whether this uicomponent is interactive or not. Non-interactive uicomponents do not respond to any mouse events.

Returns:

  1. boolean is interactive

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3288

uicomponent:SetInteractive(boolean is interactive)

Sets this uicomponent to be interactive or not. Non-interactive uicomponents do not respond to any mouse events.

Parameters:

1

boolean

is interactive

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3303

Back to top

Animations

uicomponent:CurrentAnimationId()

Returns the string name of the animation currently playing on this uicomponent. If no animation is currently playing then a blank string is returned.

Returns:

  1. string animation name

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3323

uicomponent:TriggerAnimation(string animation name)

Starts an animation on the uicomponent by name. Available animations on a given uicomponent can be seen in the ui editor.

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3340

uicomponent:AnimationExists(string animation name)

Returns whether the uicomponent contains an animation with the supplied name.

Parameters:

1

string

animation name

Returns:

  1. boolean animation exists

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3360

uicomponent:NumAnimations()

Returns the number of animations the uicomponent contains.

Returns:

  1. number animations

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3381

uicomponent:GetAnimationNames()

Returns a table containing the names of each animation contained by the uicomponent. The table is indexed by number, but the ordering of animation names within the table is not guaranteed between different calls to this function.

Returns:

  1. table numerically-indexed table of animation names

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3399

uicomponent:NumAnimationFrames(string animation name)

Returns the number of frames in an animation of the specified name. If no animation with the supplied name could be found on the uicomponent then -1 is returned.

Parameters:

1

string

animation name

Returns:

  1. number animation frames

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3428

uicomponent:SetAnimationFrameProperty(
  
string animation name,
  number
frame number,
  string
interpolation type,
  number
first value,
  [number
second value],
  [number
third value],
  [number
fourth value]
)

Sets an animation frame property. Different interpolation types require different numbers of arguments. See UiEd animation menu.

Parameters:

1

string

Animation name.

2

number

Frame number. This number is 0-based, so a value of 1 would specify the second frame in the animation.

3

string

Interpolation type string. Valid values are "colour", "position", "scale", "shader_values", "rotation", "image", "opacity", "text", "interpolation_time", "font_scale" and "material_params".

4

number

First property value.

5

number

optional, default value=0

Second property value.

6

number

optional, default value=0

Third property value.

7

number

optional, default value=0

Fourth property value.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3457

uicomponent:GetAnimationFrameProperty(
  
string animation name,
  number
frame number,
  string
interpolation type
)

Gets an animation frame property. Different interpolation types return different numbers of arguments. See UiEd animation menu.

Parameters:

1

string

Animation name.

2

number

Frame number. This number is 0-based, so a value of 1 would specify the second frame in the animation.

3

string

Interpolation type string. Valid values are "colour", "position", "scale", "shader_values", "rotation", "image", "opacity", "text", "interpolation_time", "font_scale" and "material_params".

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3509

Back to top

Properties

uicomponent:GetProperty(string property name)

Returns the value of the specified uicomponent property. The names of properties on any given uicomponent may be looked up in the ui editor.

Parameters:

1

string

property name

Returns:

  1. variable property value

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3545

uicomponent:SetProperty(string property name, variable property value)

Returns the value of the specified uicomponent property. The names of properties on any given uicomponent may be looked up in the ui editor.

Parameters:

1

string

property name

2

variable

property value

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3567

Back to top

Priority and Locking

The priority of a uicomponent is referred to when a priority lock is activated. When this occurs, any uicomponent with a priority less than the priority of the lock becomes inactive and visually desaturated. The priority of the lock is usually, but not always, equal to the priority of the uicomponent on which the lock is activated.

Priority is also used to sort the immediate children of the root uicomponent, as well as any uicomponents set to be topmost with uicomponent:RegisterTopMost.

uicomponent:LockPriority([number priority])

Activates a priority lock on the uicomponent. This disables all uicomponents with a priority value less than the priority of the lock. A priority may optionally be specified - if not, the uicomponent's own priority is used.
uicomponent:UnLockPriority must be called after calling this function to restore normal ui functionality.

Parameters:

1

number

optional, default value=nil

priority

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3594

uicomponent:UnLockPriority()

Deactivates a priority lock on the uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3615

uicomponent:Priority()

Returns the priority of this uicomponent.

Returns:

  1. number priority

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3628

uicomponent:PropagatePriority(number priority)

Sets the component priority of this uicomponent and all its children to the supplied value. The old priority of the uicomponent is returned.

Parameters:

1

number

priority

Returns:

  1. number old priority

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3644

uicomponent:RegisterTopMost()

Registers this uicomponent to be drawn topmost. Topmost uicomponents are drawn outside of the normal hierarchy on the top of all other uicomponents. This setting is useful for uicomponents such as tooltips that must always be drawn over the top of other visible parts of the UI.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3670

uicomponent:RemoveTopMost()

De-registers this uicomponent from being drawn topmost.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3685

Back to top

Shader Techniques

The functions in this section allow shader techniques to be applied to uicomponents and the text they display. The list of supported shaders and their related parameters is as follows:

Shader KeyShader NameShader DescriptionFirst ParamSecond ParamThird ParamFourth Param
normal_t0Normal
red_pulse_t0Pulsing RedPulsing saturation in the red channel using 1 second frequency.Lower boundUpper boundPulse frequency
red_and_alpha_t0Reddened & Faded
set_greyscale_t0Greyscale & AlphaLinear interpolation of colour to greyscale.Range: 0 to 1Alpha level 0 to 1.
brighten_t0BrightenColour saturation or desaturation.-unlimited to +unlimited saturation value
glow_pulse_t0Glowing PulsePulsing saturation.0 to unlimited, lowest intensity.0 to unlimited, highest intensity.Greater than 0 to unlimited, pulse interval.Time offset, pass in current real time to make it start from 0 intensity and blend in
cooldown_t0CooldownCooldown for abilities, etc. Greys out and darkens in a clock like fashion based on percentage.Percentage of cooldown (0-1)
colourwheel_t0ColourWheel Spread
verticalcolourspread_t0Vertical Colour Spread
highlight_edge_t0Edge HighlightBlack/White selection edge highlight effect. Additional Requirements: Single image in state whose dimensions must match that of the image.Image and state width.Image and state height.
drop_shadow_t0Drop ShadowPlaces black drop shadow (made for text).shadow x-offsetshadow y-offsetshadow alpha 0-1colour index (see uied wiki for list of colours to indices)
italicItalic FontItalices text
border_alpha_blendBorder Alpha BlendShould only be used when the component has a mask image to produce an alpha blended margin.Left marginTop marginRight marginBottom margin
multiplyMultiplyMultiplies by colour.
corner_clipCorner ClipUsed to clip just the corners of an image (like on radar in warhammer).Clip percent (0-1)
distortionDistortionAnimates with a kind of distortion similar to sinking shader (think like being under water).Distort amount, higher the more distortion (typical value 0.04).Speed, higher the slower (default value is 2.0 if not set)
overlay_t0OverlayLike the normal shader but additive blends
edge_blendEdge blendUsed to blend out towards edges in rectangular fashionBorder start percent for blend (0-1), default is 0.01Border end percent for blend (0-1), default is 0.006
normal_map_t0Normal MapUses mask image as normal mapLight X pos within component (0-1)Light Y pos within component (0-1)Ambient light weight (defaults to 0.35)Directional light weight (defaults to 1)
magic_aura_t0Magic AuraUses mask image to make a glowing border

uicomponent:ShaderTechniqueSet(variable shader, [boolean all states], [boolean include text])

Sets the active shader technique on the uicomponent, applying a custom graphical shader effect. The shader may be specified as a string key or a number. Valid shader keys are given in the table at the top of this section.

Parameters:

1

variable

Shader to apply. This may be a string key or a number.

2

boolean

optional, default value=false

Apply the shader to all states of this uicomponent.

3

boolean

optional, default value=true

Also apply the shader to the text of the uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3725

uicomponent:ShaderTechniqueGet()

Returns the key of the shader currently active on the uicomponent.

Returns:

  1. string shader key

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3770

uicomponent:ShaderVarsSet(
  [
number first value],
  [number
second value],
  [number
third value],
  [number
fourth value],
  [boolean
all states],
  [boolean
include text]
)

Sets variables on the shader technique currently active on the uicomponent. What values can be set and what they do is specific to each shader - see the documented list at the top of this section. Up to four shader values can be specified, each one being a number.

Parameters:

1

number

optional, default value=nil

First shader value.

2

number

optional, default value=nil

Second shader value.

3

number

optional, default value=nil

Third shader value.

4

number

optional, default value=nil

Fourth shader value.

5

boolean

optional, default value=false

Apply the shader to all states of this uicomponent.

6

boolean

optional, default value=true

Also apply the shader to the text of the uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3786

uicomponent:ShaderVarsGet()

Returns the variables of the shader currently active on the uicomponent.

Returns:

  1. number first value
  2. number second value
  3. number third value
  4. number fourth value

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3839

uicomponent:TextShaderTechniqueSet(variable shader, [boolean all states])

Sets the active shader technique on just the text of the uicomponent, applying a custom graphical shader effect. The shader may be specified as a string key or a number. Valid shader keys are given in the table at the top of this section.

Parameters:

1

variable

Shader to apply. This may be a string key or a number.

2

boolean

optional, default value=false

Apply the shader to all states of this uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3861

uicomponent:TextShaderVarsSet(
  
number first value,
  number
second value,
  number
third value,
  number
fourth value,
  [boolean
all states]
)

Sets variables on the text shader technique currently active on the uicomponent. What values can be set and what they do is specific to each shader - see the documented list at the top of this section. Up to four shader values can be specified, each one being a number.

Parameters:

1

number

First shader value.

2

number

Second shader value.

3

number

Third shader value.

4

number

Fourth shader value.

5

boolean

optional, default value=false

Apply the shader to all states of this uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3894

uicomponent:TextShaderVarsGet()

Returns the variables of the text shader currently active on the uicomponent.

Returns:

  1. number first value
  2. number second value
  3. number third value
  4. number fourth value

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3932

Back to top

Keyboard Shortcuts

uicomponent:StealShortcutKey(boolean should steal, [string key type])

Instructs this uicomponent to steal a game shortcut key, so that keypresses of that type are redirected to this uicomponent which will handle them. If a shortcut is stolen it must be released again at some suitable later time for the default keypress behaviour to be restored.
Keyboard shortcuts are listed in data\text\default_keys.xml.

Parameters:

1

boolean

If set to true, the key must be specified as the second argument. If false, all keys stolen by this uicomponent will be released so no second argument is required.

2

string

optional, default value=nil

Key type to steal.

Returns:

  1. boolean success

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 3957

uicomponent:StealInputFocus(boolean should steal)

Instructs this uicomponent to steal all keyboard input. All keypresses are therefore redirected to this uicomponent which will handle them. If input focus is stolen by a uicomponent then standard keyboard behaviour will be overridden until it is released with a second call to this function.

Parameters:

1

boolean

should steal

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4003

uicomponent:TriggerShortcut(string shortcut)

Triggers a keyboard shortcut on the uicomponent, by name. Keyboard shortcuts are listed in data\text\default_keys.xml.

Parameters:

1

string

shortcut

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4034

Back to top

Highlighting

uicomponent:Highlight(boolean should highlight, [boolean square], [number priority lock])

Highlights or unhighlights the uicomponent to the player with a flashing ring.

Parameters:

1

boolean

Set to truefalse to deactivate.

2

boolean

optional, default value=false

Set to true to show a square highlight, or false to show a circular highlight.

3

number

optional, default value=0

Activates a priority lock along with the highlight with the specified priority. While a priority lock is active, any interactive uicomponents with a priority less than the supplied lock level will be rendered non-interactive. See the Priority and Locking section for more information.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4056

uicomponent:FullScreenHighlight([string highlight text], [boolean once only])

Activates a fullscreen highlight around the subject uicomponent. This places a nearly opaque layer over the screen except for a window over the subject uicomponent, leaving it prominently displayed. Text may optionally be specified that gets displayed over the opaque layer.

Parameters:

1

string

optional, default value=nil

Text to display over the fullscreen highlight. If used, this should be set to the key of an entry from the random_localisation_strings table.

2

boolean

optional, default value=false

Displays this fullscreen highlight once only. If this flag is set, an entry is stored in the registry when this fullscreen highlight is displayed, preventing it from ever being displayed again.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4089

uicomponent:StartPulseHighlight([number pulse strength], [string state name])

Activates a pulsing highlight effect on a particular state of the subject uicomponent. This is useful for unobtrusively highlighting components with an area such as buttons and panels, but doesn't work so well for highlighting text. The script function pulse_uicomponent wraps this function.

Parameters:

1

number

optional, default value=nil

Pulse strength override. A typical value might be a number between 1 and 10.

2

string

optional, default value=nil

State name to apply the pulsing effect to. If this is not supplied, the effect is applied to the current state.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4118

uicomponent:StopPulseHighlight([string state name])

Deactivates a pulsing highlight effect on a particular state of the subject uicomponent that was previously started with uicomponent:StartPulseHighlight.

Parameters:

1

string

optional, default value=nil

State name to stop the pulsing effect on. If this is not supplied then the current state is used.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4155

Back to top

Interface Methods

uicomponent:InterfaceFunction(string function name, ... varargs)

Calls an interface function on the uicomponent, by string name. Interface functions are provided by some uicomponents to allow the script to activate specific functionality related to the uicomponent. Along with the string name of the interface function, multiple arguments to pass to that function may be specified.

Parameters:

1

string

Name of interface function to call.

2

...

zero or more additional arguments to pass to the interface function.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4180

uicomponent:HasInterface()

Returns whether this uicomponent provides any interface functions.

Returns:

  1. boolean has callback interface

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4205

Back to top

Simulating Mouse Events

uicomponent:SimulateLClick([number x], [number y])

Simulates a left-click on the uicomponent. Relative co-ordinates at which the click is simulated on the component may optionally be specified. Both arguments must be supplied to specify a position.

Parameters:

1

number

optional, default value=nil

X co-ordinate of click on component.

2

number

optional, default value=nil

Y co-ordinate of click on component.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4297

uicomponent:SimulateRClick([number x], [number y])

Simulates a right-click on the uicomponent. Relative co-ordinates at which the click is simulated on the component may optionally be specified. Both arguments must be supplied to specify a position.

Parameters:

1

number

optional, default value=nil

X co-ordinate of click on component.

2

number

optional, default value=nil

Y co-ordinate of click on component.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4323

uicomponent:SimulateDblLClick([number x], [number y])

Simulates a double-left-click on the uicomponent. Relative co-ordinates at which the click is simulated on the component may optionally be specified. Both arguments must be supplied to specify a position.

Parameters:

1

number

optional, default value=nil

X co-ordinate of click on component.

2

number

optional, default value=nil

Y co-ordinate of click on component.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4350

uicomponent:SimulateDblRClick([number x], [number y])

Simulates a double-left-click on the uicomponent. Relative co-ordinates at which the click is simulated on the component may optionally be specified. Both arguments must be supplied to specify a position.

Parameters:

1

number

optional, default value=nil

X co-ordinate of click on component.

2

number

optional, default value=nil

Y co-ordinate of click on component.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4377

uicomponent:SimulateMouseOn()

Simulates a mouse-on event on the uicomponent. You MUST call SimulateMouseOff when done otherwise mouse on will be stuck on. Also note that you might have to wait a tick before expected functionality occurs (say a panel opening on mousing over this component), as some callbacks work by checking for mouseover each update tick and dont use OnMouseOn

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4404

uicomponent:SimulateMouseOff()

Simulates a mouse-off event on the uicomponent.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4421

uicomponent:SimulateMouseMove([number x], [number y])

Simulates a mouse-move event on the uicomponent. Relative co-ordinates at which the mouse move event is simulated on the component may optionally be specified. Both arguments must be supplied to specify a position.

Parameters:

1

number

optional, default value=nil

X co-ordinate of event on component.

2

number

optional, default value=nil

Y co-ordinate of event on component.

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4438

Back to top

Simulating Keyboard Events

The functions in this section allow scripts to simulate keyboard events. With each, a keyboard event must be specified. Valid keyboard events are as follows:

  • "ESCAPE"
  • "1"
  • "2"
  • "3"
  • "4"
  • "5"
  • "6"
  • "7"
  • "8"
  • "9"
  • "MINUS"
  • "EQUALS"
  • "BACK"
  • "TAB"
  • "Q"
  • "W"
  • "E"
  • "R"
  • "T"
  • "Y"
  • "U"
  • "I"
  • "O"
  • "P"
  • "LBRACKET"
  • "RBRACKET"
  • "RETURN"
  • "LCONTROL"
  • "A"
  • "S"
  • "D"
  • "F"
  • "G"
  • "H"
  • "J"
  • "K"
  • "L"
  • "SEMICOLON"
  • "APOSTROPHE"
  • "GRAVE"
  • "LSHIFT"
  • "BACKSLASH"
  • "Z"
  • "X"
  • "C"
  • "V"
  • "B"
  • "N"
  • "M"
  • "COMMA"
  • "PERIOD"
  • "SLASH"
  • "RSHIFT"
  • "MULTIPLY"
  • "LALT"
  • "SPACE"
  • "CAPITAL"
  • "F1"
  • "F2"
  • "F3"
  • "F4"
  • "F5"
  • "F6"
  • "F7"
  • "F8"
  • "F9"
  • "F10"
  • "NUMLOCK"
  • "SCROLL"
  • "NUMPAD7"
  • "NUMPAD8"
  • "NUMPAD9"
  • "SUBTRACT"
  • "NUMPAD4"
  • "NUMPAD5"
  • "NUMPAD6"
  • "ADD"
  • "NUMPAD1"
  • "NUMPAD2"
  • "NUMPAD3"
  • "NUMPAD0"
  • "DECIMAL"
  • "OEM_102"
  • "F11"
  • "F12"
  • "F13"
  • "F14"
  • "F15"
  • "KANA"
  • "ABNT_C1"
  • "CONVERT"
  • "NOCONVERT"
  • "YEN"
  • "ABNT_C2"
  • "NUMPADEQUALS"
  • "PREVTRACK"
  • "AT"
  • "COLON"
  • "UNDERLINE"
  • "KANJI"
  • "STOP"
  • "AX"
  • "NEXTTRACK"
  • "NUMPADENTER"
  • "RCONTROL"
  • "MUTE"
  • "CALCULATOR"
  • "PLAYPAUSE"
  • "MEDIASTOP"
  • "VOLUMEDOWN"
  • "VOLUMEUP"
  • "WEBHOME"
  • "NUMPADCOMMA"
  • "DIVIDE"
  • "SYSRQ"
  • "RALT"
  • "PAUSE"
  • "HOME"
  • "UP"
  • "PAGE_UP"
  • "LEFT"
  • "RIGHT"
  • "END"
  • "DOWN"
  • "PAGE_DOWN"
  • "INSERT"
  • "DELETE"
  • "LWIN"
  • "RWIN"
  • "APPS"
  • "POWER"
  • "SLEEP"
  • "WAKE"
  • "WEBSEARCH"
  • "WEBFAVORITES"
  • "WEBREFRESH"
  • "WEBSTOP"
  • "WEBFORWARD"
  • "WEBBACK"
  • "MYCOMPUTER"
  • "MAIL"
  • "MEDIASELECT"

uicomponent:SimulateKey(string key id)

Simulates a keypress on the uicomponent. A string key id must be specified from the list documented at the top of this section.

Parameters:

1

string

key id

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4645

uicomponent:SimulateKeyDown(string key id)

Simulates a keypress-down on the uicomponent. A string key id must be specified from the list documented at the top of this section.

Parameters:

1

string

key id

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4665

uicomponent:SimulateKeyUp(string key id)

Simulates a keypress-up on the uicomponent. A string key id must be specified from the list documented at the top of this section.

Parameters:

1

string

key id

Returns:

  1. nil

defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 4685

Last updated 12/08/2022 11:56:58