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 Battle loaded in battle
Loaded in Campaign loaded in campaign
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 576

uicomponent:Id()

Returns the string name of this uicomponent.

Returns:

  1. string name

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

uicomponent:CallbackId()

Returns the callback id of this uicomponent.

Returns:

  1. string callback id

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

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 624

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 637

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 650

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 667

uicomponent:SetContextObject(string context object id)

Sets the context object id of the uicomponent. This can set the uicomponent into a special mode where its state and values are tied to a game object.

Parameters:

1

string

context object id

Returns:

  1. nil

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

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 716

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 733

uicomponent:NumStates()

Returns the number of states this uicomponent contains.

Returns:

  1. number number of states

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

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 775

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 806

uicomponent:Height()

Returns the current height of the uicomponent in pixels.

Returns:

  1. number height

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

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 838

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 856

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 892

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 910

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 928

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 950

uicomponent:IsMoveable()

Returns whether this uicomponent is moveable or not.

Returns:

  1. boolean is moveable

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

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 982

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 1007

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 1031

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 1055

uicomponent:TextDimensions()

Returns the dimensions of the text displayed on the uicomponent, 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 1078

uicomponent:TextDimensionsForText(string text)

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

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 1097

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 1121

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 1158

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 1208

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 1263

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 1284

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 1311

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. nil

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

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 1431

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 1457

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 1485

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 1502

uicomponent:Adopt(address child, [number 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. If index >= 0 then the child will be inserted into that position; else it will be inserted as the last child

Parameters:

1

address

child

2

number

optional, default value=-1

index

Returns:

  1. nil

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

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 1612

Back to top

Component Creation

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 1641

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 1669

uicomponent:CreateFromComponent(uicomponent template, string name for the new component)

Creates a new uicomponent from the given temaplte as the child of the given uicomponent. A name for the new uicomponent must be supplied, as well as a parent component address and a component address for the 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

uicomponent

template

2

string

name for the new component

Returns:

  1. address address of created uicomponent

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

uicomponent:Destroy()

Destroys this uicomponent.

Returns:

  1. nil

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

uicomponent:DestroyChildren()

Destroys and unloads all children of this uicomponent.

Returns:

  1. nil

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

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 - effect.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 1778

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 - effect.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 1822

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

Sets the text on the current state of the uicomponent to the supplied text. If the text is too large, it will replace it with ... and set it as tooltip.

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 1866

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 1904

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 1931

uicomponent:SetTooltipTextWithRLSKey(string key, [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 is specified as a key for a record in the random_localisation_strings table.

Parameters:

1

string

Key for a record in the random_localisation_strings table.

2

boolean

optional, default value=false

Set all states.

Returns:

  1. nil

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

uicomponent:SetTooltipWithTitle(
  
string key for title,
  string
key for tooltip text,
  [boolean
set all states]
)

Sets the custom tooltip of the current state of this uicomponent.

Parameters:

1

string

Key for a record in the random_localisation_strings, campaign_localised_strings table.

2

string

this can be the list of strings, which will be concatenated, or they can be list of table { text = "key", params = {n1, n2, n3} } if you want to pass some format numbers

3

boolean

optional, default value=false

Set all states.

Returns:

  1. nil

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

uicomponent:AppendTooltipText(string key for localized tooltip text., [boolean set all states])

Appends to the tooltip of the current state of this uicomponent.

Parameters:

1

string

key for localized tooltip text.

2

boolean

optional, default value=false

Set all states.

Returns:

  1. nil

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

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 2186

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 2221

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

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

image

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.

Returns:

  1. nil

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

uicomponent:GetImagePath([image index])

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

Parameters:

1

image

optional, default value=0

Index of image to return the path of.

Returns:

  1. nil

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

uicomponent:NumImages()

Returns the number of images associated with the subject uicomponent.

Returns:

  1. nil

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

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 2341

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 2381

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 2399

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 2430

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 2460

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 2490

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 2520

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 2551

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 2584

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 2614

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 2644

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 2675

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 either the root or an orphaned parent, 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 2715

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 2738

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 2756

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 2774

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 2791

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 2808

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 2835

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 2864

uicomponent:SetDisabled(boolean is disabled)

Sets this uicomponent to be disabled or not. Disabled uicomponents cannot be clicked upon.

Parameters:

1

boolean

is disabled

Returns:

  1. nil

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

uicomponent:IsInteractive()

Returns whether this uicomponent is interactive or not. Non-interactive uicomponents cannot be clicked upon.

Returns:

  1. boolean is interactive

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

uicomponent:SetInteractive(boolean is interactive)

Sets this uicomponent to be interactive or not. Non-interactive uicomponents cannot be clicked upon.

Parameters:

1

boolean

is interactive

Returns:

  1. nil

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

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 2931

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 2948

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 2968

uicomponent:NumAnimations()

Returns the number of animations the uicomponent contains.

Returns:

  1. number animations

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

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 3007

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 3036

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 3065

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 3117

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 3153

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 3180

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 3207

uicomponent:UnLockPriority()

Deactivates a priority lock on the uicomponent.

Returns:

  1. nil

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

uicomponent:Priority()

Returns the priority of this uicomponent.

Returns:

  1. number priority

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

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 3262

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 3288

uicomponent:RemoveTopMost()

De-registers this uicomponent from being drawn topmost.

Returns:

  1. nil

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

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 3343

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 3388

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 3404

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 3457

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 3479

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 3512

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 3550

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 3575

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 3619

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 3650

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.

Parameters:

1

boolean

Set to truefalse to deactivate.

2

boolean

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

3

number

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 3672

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 3699

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

Activates a pulsing highlight effect on 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. If supplied, this applies the pulsing effect to only the specified state of the uicomponent.

Returns:

  1. nil

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

uicomponent:StopPulseHighlight([string state name])

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

Parameters:

1

string

optional, default value=nil

State name. If supplied, this stops the pulsing effect on only the specified state of the uicomponent.

Returns:

  1. nil

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

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 3790

uicomponent:HasInterface()

Returns whether this uicomponent provides any interface functions.

Returns:

  1. boolean has callback interface

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

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 3898

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 3919

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 3941

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 3963

uicomponent:SimulateMouseOn()

Simulates a mouse-on event on the uicomponent.

Returns:

  1. nil

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

uicomponent:SimulateMouseOff()

Simulates a mouse-off event on the uicomponent.

Returns:

  1. nil

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

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 4017

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 4225

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 4240

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 4255

Last updated 25/08/2021 12:07:51