Campaign Documentation

context type id

Returns:

nil

Example:


								 local object_id = UIComponent("building_slot").GetContextObjectId("CcoCampaignBuildingSlot")

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

uicomponent:GetContextObject(string context type id)

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

Parameters:

uicomponent:AddScriptEventReporter()

context type id

Returns:

object context object (cco)

Example:


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

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

Returns:

nil

States

uicomponent:CurrentState()

Returns the name of the current state of the uicomponent.

Returns:

string state name

uicomponent:SetState(string state name)

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

Parameters:

uicomponent:NumStates()

state name

Returns:

boolean State was successfully set

Returns the number of states this uicomponent contains.

Returns:

number number of states

uicomponent:GetStateByIndex([number state index])

Returns the name of the state at the specified index.

Parameters:

uicomponent:Width()

optional, default value=0

state index

Returns:

string state name

Position and Dimensions

Returns the current width of the uicomponent in pixels.

Returns:

number width

uicomponent:Height()

Returns the current height of the uicomponent in pixels.

Returns:

number height

uicomponent:Dimensions()

Returns the width and height of the uicomponent in pixels.

Returns:

number width
number height

uicomponent:Bounds()

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

Returns:

number width
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:

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

uicomponent:RelativePosition()

Returns the relative position of the uicomponent

Returns:

number x, X co-ordinate in pixels.
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:

nil

uicomponent:SetMoveable(boolean is moveable)

Sets this uicomponent to be moveable or not.

Parameters:

uicomponent:IsMoveable()

is moveable

Returns:

nil

Returns whether this uicomponent is moveable or not.

Returns:

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:

New width of uicomponent in pixels.

New height of uicomponent in pixels.

optional, default value=true

Also resize children.

Returns:

nil

uicomponent:SetCanResizeHeight([boolean can resize ])

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

Parameters:

optional, default value=true

can resize

Returns:

nil

uicomponent:SetCanResizeWidth([boolean can resize])

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

Parameters:

uicomponent:TextDimensions()

optional, default value=true

can resize

Returns:

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:

nil

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

Returns:

number width in pixels
number height in pixels
number number of lines

uicomponent:TextDimensionsForText(string text)

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

Parameters:

text

Returns:

number width in pixels
number height in pixels
number number of lines

uicomponent:WidthOfTextLine(string text line)

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

Parameters:

uicomponent:TextXOffset()

text line

Returns:

number width in pixels

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:

number left offset
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:

number top offset
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:

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:

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:

uicomponent:GetTextHAlign()

horizontal text alignment

Returns:

nil

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

Returns:

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:

uicomponent:GetTextVAlign()

vertical text alignment

Returns:

nil

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

Returns:

string vertical text alignment

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 Point	Number
`DOCK_POINT_NONE`	0
`DOCK_POINT_TL`	1
`DOCK_POINT_TC`	2
`DOCK_POINT_TR`	3
`DOCK_POINT_CL`	4
`DOCK_POINT_C`	5
`DOCK_POINT_CR`	6
`DOCK_POINT_BL`	7
`DOCK_POINT_BC`	8
`DOCK_POINT_BR`	9

uicomponent:DockingPoint()

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

Returns:

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:

uicomponent:GetDockOffset()

dock point

Returns:

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:

nil

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

Returns:

number x offset in pixels.
number y offset in pixels.

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:

variable

Search target, identified by index number or string name.

uicomponent:SequentialFind(... identifiers)

optional, default value=true

Assert if no matching uicomponent could be found.

Returns:

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

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:

...

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

Returns:

address of found component

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:

script tag unique id that has been specified in the layout

Returns:

address of found component

Example:


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

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:

uicomponent:ChildCount()

GUID that has been specified in the layout

Returns:

address of found component

Example:


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

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:

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:

address parent address

Example:


								 uic_parent = UIComponent(uic_child:Parent())

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:

address

uicomponent address

uicomponent:Divorce(address child)

optional, default value=-1

insertion index

Returns:

nil

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:

address

child

Returns:

nil

Component Creation and Destruction

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

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

Parameters:

1	`string`	uicomponent name
2	`string`	file path

Returns:

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:

uicomponent:Destroy()

uicomponent name

Returns:

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

Destroys this uicomponent.

Returns:

nil

uicomponent:DestroyChildren()

Destroys all children of this uicomponent.

Returns:

nil

Text and Tooltips

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

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

Parameters:

1	`string`	Localised text.
2	`string`	source of text in format of a stringtable key (tablename_recordname_key)

Returns:

nil

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

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

Parameters:

1	`string`	Localised text.
2	`string`	source of text in format of a stringtable key (tablename_recordname_key)

Returns:

nil

uicomponent:GetStateText()

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

Returns:

string localised uicomponent text
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:

nil

uicomponent:GetTooltipText()

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

Returns:

string tooltip text
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

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:

nil

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

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

Parameters:

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

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.

optional, default value=false

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

Returns:

nil

uicomponent:GetImagePath([number image index])

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

Parameters:

optional, default value=0

Index of image to return the path of.

Returns:

nil

uicomponent:GetImageDimensions([number image index])

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

Parameters:

uicomponent:NumImages()

optional, default value=0

Index of image to return the path of.

Returns:

number image width
number image height

Returns the number of images associated with the subject uicomponent.

Returns:

nil

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:

uicomponent:NumCurrentStateImages()

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

Returns:

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

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

Returns:

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:

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:

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

Returns:

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:

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

Returns:

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:

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

Returns:

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:

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

Returns:

number width, Width in pixels.
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:

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:

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

Returns:

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:

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

Returns:

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:

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:

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:

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:

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

Returns:

number dock point, Dock point.

uicomponent:SetCurrentStateImageDockOffset( number state image index, numberx offset in pixels., numbery 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:

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:

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

Returns:

number x offset in pixels.
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:

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:

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

Returns:

boolean is image tiled.

uicomponent:SetCurrentStateImageMargins( number state image index, numbertop margin, numberright margin, numberbottom margin, numberleft 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:

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:

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

Returns:

number top margin value in pixels
number right margin value in pixels
number bottom margin value in pixels
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:

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:

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:

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

Returns:

boolean is flipped horizontally.

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:

uicomponent:VisibleFromRoot()

optional, default value=false

Also test all parents up to the root.

Returns:

boolean is visible

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:

boolean is visible from root

uicomponent:SetVisible(boolean is visible)

Sets the visibility state of this uicomponent.

Parameters:

is visible

Returns:

nil

uicomponent:PropagateVisibility(boolean is visible)

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

Parameters:

uicomponent:Opacity()

is visible

Returns:

nil

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

Returns:

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:

opacity value

apply

optional, default value=false

to all states

Returns:

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:

uicomponent:IsDisabled()

opacity value

apply

optional, default value=false

to all states

Returns:

nil

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:

boolean is interactive

uicomponent:SetDisabled(boolean is disabled)

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

Parameters:

uicomponent:IsInteractive()

is disabled

Returns:

nil

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

Returns:

boolean is interactive

uicomponent:SetInteractive(boolean is interactive)

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

Parameters:

uicomponent:CurrentAnimationId()

is interactive

Returns:

nil

Animations

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:

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:

animation name

Returns:

nil

uicomponent:AnimationExists(string animation name)

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

Parameters:

uicomponent:NumAnimations()

animation name

Returns:

boolean animation exists

Returns the number of animations the uicomponent contains.

Returns:

number animations

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:

table numerically-indexed table of animation names

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:

animation name

Returns:

number animation frames

uicomponent:SetAnimationFrameProperty( string animation name, numberframe number, stringinterpolation type, numberfirst value, [numbersecond value], [numberthird value], [numberfourth 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:

nil

uicomponent:GetAnimationFrameProperty( string animation name, numberframe number, stringinterpolation 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:

nil

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:

property name

Returns:

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:

nil

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:

uicomponent:UnLockPriority()

optional, default value=nil

priority

Returns:

nil

Deactivates a priority lock on the uicomponent.

Returns:

nil

uicomponent:Priority()

Returns the priority of this uicomponent.

Returns:

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:

uicomponent:RegisterTopMost()

priority

Returns:

number old priority

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:

nil

uicomponent:RemoveTopMost()

De-registers this uicomponent from being drawn topmost.

Returns:

nil

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 Key	Shader Name	Shader Description	First Param	Second Param	Third Param	Fourth Param
`normal_t0`	Normal
`red_pulse_t0`	Pulsing Red	Pulsing saturation in the red channel using 1 second frequency.	Lower bound	Upper bound	Pulse frequency
`red_and_alpha_t0`	Reddened & Faded
`set_greyscale_t0`	Greyscale & Alpha	Linear interpolation of colour to greyscale.	Range: 0 to 1	Alpha level 0 to 1.
`brighten_t0`	Brighten	Colour saturation or desaturation.	-unlimited to +unlimited saturation value
`glow_pulse_t0`	Glowing Pulse	Pulsing 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_t0`	Cooldown	Cooldown for abilities, etc. Greys out and darkens in a clock like fashion based on percentage.	Percentage of cooldown (0-1)
`colourwheel_t0`	ColourWheel Spread
`verticalcolourspread_t0`	Vertical Colour Spread
`highlight_edge_t0`	Edge Highlight	Black/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_t0`	Drop Shadow	Places black drop shadow (made for text).	shadow x-offset	shadow y-offset	shadow alpha 0-1	colour index (see uied wiki for list of colours to indices)
`italic`	Italic Font	Italices text
`border_alpha_blend`	Border Alpha Blend	Should only be used when the component has a mask image to produce an alpha blended margin.	Left margin	Top margin	Right margin	Bottom margin
`multiply`	Multiply	Multiplies by colour.
`corner_clip`	Corner Clip	Used to clip just the corners of an image (like on radar in warhammer).	Clip percent (0-1)
`distortion`	Distortion	Animates 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_t0`	Overlay	Like the normal shader but additive blends
`edge_blend`	Edge blend	Used to blend out towards edges in rectangular fashion	Border start percent for blend (0-1), default is 0.01	Border end percent for blend (0-1), default is 0.006
`normal_map_t0`	Normal Map	Uses mask image as normal map	Light 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_t0`	Magic Aura	Uses 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:

variable

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

optional, default value=false

Apply the shader to all states of this uicomponent.

uicomponent:ShaderTechniqueGet()

optional, default value=true

Also apply the shader to the text of the uicomponent.

Returns:

nil

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

Returns:

string shader key

uicomponent:ShaderVarsSet( [number first value], [numbersecond value], [numberthird value], [numberfourth value], [booleanall states], [booleaninclude 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:

nil

uicomponent:ShaderVarsGet()

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

Returns:

number first value
number second value
number third value
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:

variable

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

uicomponent:TextShaderVarsGet()

optional, default value=false

Apply the shader to all states of this uicomponent.

Returns:

nil

uicomponent:TextShaderVarsSet( number first value, numbersecond value, numberthird value, numberfourth value, [booleanall 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:

nil

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

Returns:

number first value
number second value
number third value
number fourth value

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:

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.

optional, default value=nil

Key type to steal.

Returns:

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:

should steal

Returns:

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:

shortcut

Returns:

nil

Highlighting

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

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

Parameters:

Set to truefalse to deactivate.

optional, default value=false

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

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:

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:

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.

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:

nil

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

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

Parameters:

optional, default value=nil

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

optional, default value=nil

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

Returns:

nil

uicomponent:StopPulseHighlight([string state name])

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

Parameters:

uicomponent:HasInterface()

optional, default value=nil

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

Returns:

nil

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:

nil

Returns whether this uicomponent provides any interface functions.

Returns:

boolean has callback interface

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:

optional, default value=nil

X co-ordinate of click on component.

optional, default value=nil

Y co-ordinate of click on component.

Returns:

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:

optional, default value=nil

X co-ordinate of click on component.

optional, default value=nil

Y co-ordinate of click on component.

Returns:

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:

optional, default value=nil

X co-ordinate of click on component.

optional, default value=nil

Y co-ordinate of click on component.

Returns:

nil

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

Parameters:

optional, default value=nil

X co-ordinate of click on component.

uicomponent:SimulateMouseOn()

optional, default value=nil

Y co-ordinate of click on component.

Returns:

nil

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

Returns:

nil

uicomponent:SimulateMouseOff()

Simulates a mouse-off event on the uicomponent.

Returns:

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:

optional, default value=nil

X co-ordinate of event on component.

optional, default value=nil

Y co-ordinate of event on component.

Returns:

nil

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:

key id

Returns:

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:

key id

Returns:

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: