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

uicomponent:Id()
Returns the string name of this uicomponent.

Returns:

  1. string name

uicomponent:CallbackId()
Returns the callback id of this uicomponent.

Returns:

  1. string callback id

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

uicomponent:Layout()
Calls the layout function for the uicomponent, forcing it to refresh its display.

Returns:

  1. nil

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

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

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
Back to top

States

uicomponent:CurrentState()
Returns the name of the current state of the uicomponent.

Returns:

  1. string state name

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

uicomponent:NumStates()
Returns the number of states this uicomponent contains.

Returns:

  1. number number of states

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
Back to top

Position and Dimensions

uicomponent:Width()
Returns the current width of the uicomponent in pixels.

Returns:

  1. number width

uicomponent:Height()
Returns the current height of the uicomponent in pixels.

Returns:

  1. number height

uicomponent:Dimensions()
Returns the width and height of the uicomponent in pixels.

Returns:

  1. number width
  2. number height

uicomponent:Bounds()
Returns the maximum width and height of this uicomponent, including any of its children.

Returns:

  1. number width
  2. number height

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.

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

uicomponent:SetMoveable(boolean is moveable)

Sets this uicomponent to be moveable or not.

Parameters:

1

boolean

is moveable

Returns:

  1. nil

uicomponent:IsMoveable()
Returns whether this uicomponent is moveable or not.

Returns:

  1. boolean is moveable

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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())

uicomponent:Destroy()
Destroys this uicomponent.

Returns:

  1. nil

uicomponent:DestroyChildren()
Destroys and unloads all children of this uicomponent.

Returns:

  1. nil

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

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
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"));

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"));
Back to top

Text and Tooltips

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

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

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

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

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

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

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

uicomponent:NumImages()
Returns the number of images associated with the subject uicomponent.

Returns:

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

uicomponent:NumCurrentStateImages()
Returns the number of images associated with the current state of this uicomponent.

Returns:

  1. number number of images

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

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

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.

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.

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.

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

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

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

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

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

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

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.

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

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.

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

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.

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

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

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

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

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

uicomponent:SetVisible(boolean is visible)

Sets the visibility state of this uicomponent.

Parameters:

1

boolean

is visible

Returns:

  1. nil

uicomponent:PropagateVisibility(boolean is visible)

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

Parameters:

1

boolean

is visible

Returns:

  1. nil

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

Returns:

  1. number opacity

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

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

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

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

Returns:

  1. boolean is interactive

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

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

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

uicomponent:UnLockPriority()
Deactivates a priority lock on the uicomponent.

Returns:

  1. nil

uicomponent:Priority()
Returns the priority of this uicomponent.

Returns:

  1. number priority

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

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

uicomponent:RemoveTopMost()
De-registers this uicomponent from being drawn topmost.

Returns:

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

uicomponent:ShaderTechniqueGet()
Returns the key of the shader currently active on the uicomponent.

Returns:

  1. string shader key

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

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

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

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

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

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

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

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

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

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

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

uicomponent:HasInterface()
Returns whether this uicomponent provides any interface functions.

Returns:

  1. boolean has callback interface
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

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

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

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

uicomponent:SimulateMouseOn()
Simulates a mouse-on event on the uicomponent.

Returns:

  1. nil

uicomponent:SimulateMouseOff()
Simulates a mouse-off event on the uicomponent.

Returns:

  1. nil

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

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

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
Last updated 07/02/21 06:39:14