Most of the Lua types, properties, and functions listed in this reference correspond directly to their C++ API equivalent, users are encouraged to take a look at the C++ Manual for more detailed descriptions.

All instantiable classes define a new() function which returns an object of that particular class. With the exception of this new() function, all members listed will be member functions.

Main Types

• Context
• Document
• Element
• Event
• rmlui

Utility

• Colourb
• Colourf
• ElementInstancer
• ElementPtr
• GlobalLuaFunctions
• Log
• Vector2f
• Vector2i

Special Elements

• ElementForm
• ElementFormControl
• ElementFormControlInput
• ElementFormControlSelect
• ElementFormControlTextArea
• ElementTabSet
• ElementText

Enumerations

• DocumentFocus
• DocumentModal

Proxy

• ContextDocumentsProxy
• ElementAttributesProxy
• ElementChildNodesProxy
• ElementStyleProxy
• EventParametersProxy
• RmlUiContextsProxy
• SelectOptionsProxy

---

Colourb

Inherits: nil

Constructs a colour with four channels, each from 0 to 255.

Properties

Name	Type
alpha	integer
blue	integer
green	integer
red	integer
rgba	integer, integer, integer, integer

Functions

Name	Return Type
new(integer red, integer green, integer blue, integer alpha)	Colourb

Metafunctions

Metafunctions
__add
__eq
__mul

Property Descriptions

alpha :: integer

Alpha channel

blue :: integer

Blue channel

green :: integer

Green channel

red :: integer

Red channel

rgba :: integer, integer, integer, integer

Function Descriptions

new(integer red, integer green, integer blue, integer alpha) → Colourb

Construct a new Colourb object

---

Colourf

Inherits: nil

Constructs a colour with four floating point channels.

Properties

Name	Type
alpha	number
blue	number
green	number
red	number
rgba	number, number, number, number

Functions

Name	Return Type
new(number red, number green, number blue, number alpha)	Colourf

Metafunctions

Metafunctions
__eq

Property Descriptions

alpha :: number

Alpha channel

blue :: number

Blue channel

green :: number

Green channel

red :: number

Red channel

rgba :: number, number, number, number

Function Descriptions

new(number red, number green, number blue, number alpha) → Colourf

Construct a new Colourf object.

---

Context

Inherits: nil

The Context class has no constructor; it must be instantiated through the CreateContext() function. It has the following functions and properties:

Properties

Name	Type
dimensions	Vector2i
documents	ContextDocumentsProxy
dp_ratio	number
focus_element	Element
hover_element	Element
name	string
root_element	Element

Functions

Name	Return Type
AddEventListener(string event, function, string script, Element element_context, boolean in_capture_phase)	nil
CreateDocument(string tag)	Document
IsMouseInteracting()	boolean
LoadDocument(string document_path)	Document
ProcessKeyDown(integer key_identifier, integer key_modifier_state)	boolean
ProcessKeyUp(integer key_identifier, integer key_modifier_state)	boolean
ProcessMouseButtonDown( integer button_index, integer key_modifier_state)	boolean
ProcessMouseButtonUp( integer button_index, integer key_modifier_state)	boolean
ProcessMouseLeave()	boolean
ProcessMouseWheel(number delta, integer key_modifier_state)	boolean
ProcessTextInput(string integer input)	boolean
Render()	boolean
UnloadAllDocuments()	nil
UnloadDocument(Document document)	nil
Update()	boolean

Property Descriptions

dimensions :: Vector2i

The dimensions of the context, as a Vector2i type.

documents :: ContextDocumentsProxy

Returns an array of the documents within the context. This can be looked up as an array or a dictionary. Read-only.

dp_ratio :: number

The density independent pixel ratio of the context. This value determines ratio between ‘dp’ and ‘px’ units.

focus_element :: Element

Returns the leaf of the context’s focus tree. Read-only.

hover_element :: Element

Returns the element under the context’s cursor. Read-only.

name :: string

The name of the context, specified at construction. Read-only.

root_element :: Element

Returns the context’s root element. Read-only.

Function Descriptions

AddEventListener(string event, function, string script, Element element_context, boolean in_capture_phase) → nil

Adds the inline Lua script or a Lua function, script, as an event listener to the context. element_context is an optional Element; if it is not nil, then the script will be executed as if it was bound to that element.

CreateDocument(string tag) → Document

Creates a new document with the tag name of tag.

IsMouseInteracting() → boolean

Returns a hint on whether the mouse is currently interacting with any elements in this context.

LoadDocument(string document_path) → Document

Attempts to load a document from the RML file found at document_path. If successful, the document will be returned with a reference count of one.

ProcessKeyDown(integer key_identifier, integer key_modifier_state) → boolean

Sends a key down event into this context. key_identifier is the key pressed and the key_modifier_state is the state of key modifiers at the moment of the event. Returns true if the event was consumed, otherwise false.

ProcessKeyUp(integer key_identifier, integer key_modifier_state) → boolean

Sends a key release event into this context. key_identifier is the key released and the key_modifier_state is the state of key modifiers at the moment of the event. Returns true if the event was consumed, otherwise false.

ProcessMouseButtonDown(integer button_index, integer key_modifier_state) → boolean

Sends a mouse-button down event into this context. button_index is the the index of the button that was pressed (0 for the left button, 1 for right, and any others from 2 onwards), and the key_modifier_state is the state of key modifiers at the moment of the event. Returns true if the mouse is not interacting with any elements in the context, otherwise false.

ProcessMouseButtonUp(integer button_index, integer key_modifier_state) → boolean

Sends a mouse-button up event into this context. button_index is the the index of the button that was released (0 for the left button, 1 for right, and any others from 2 onwards), and the key_modifier_state is the state of key modifiers at the moment of the event. Returns true if the mouse is not interacting with any elements in the context, otherwise false.

ProcessMouseLeave() → boolean

Tells the context that the mouse has left the window. Returns true if the mouse is not interacting with any elements in the context, otherwise false.

ProcessMouseWheel(number delta, integer key_modifier_state) → boolean

Sends a mouse-wheel movement event into this context. wheel_delta is the mouse-wheel movement this frame, and the key_modifier_state is the state of key modifiers at the moment of the event. Returns true if the event was not consumed (ie, was prevented from propagating by an element), false if it was.

ProcessTextInput(string integer input) → boolean

Sends a text input event into the context. If the input type is integer, sends a single key event, if the input is string, sends this string as a text input event. Return true if the event was not consumed (ie, was prevented from propagating by an element), false if it was.

Render() → boolean

Renders the context.

UnloadAllDocuments() → nil

Closes all documents currently loaded with the context.

UnloadDocument(Document document) → nil

Unloads a specific document within the context.

Update() → boolean

Updates the context.

---

ContextDocumentsProxy

Inherits: nil

Table of documents with the ability to be iterated over or indexed by an integer or a string.

Metafunctions

Metafunctions
__index
__pairs

---

DocumentFocus

Inherits: nil

Enum type used as an argument to various functions requiring focus options.

Properties

Name	Type
None	integer
Document	integer
Keep	integer
Auto	integer

Property Descriptions

None :: integer

No focus.

Document :: integer

Document focus.

Keep :: integer

Keep focus.

Auto :: integer

Auto focus.

---

DocumentModal

Inherits: nil

Enum type used as an argument to various functions requiring modal options.

Properties

Name	Type
None	integer
Modal	integer
Keep	integer

Property Descriptions

None :: integer

No modal.

Modal :: integer

Modal.

Keep :: integer

Keep modal.

---

Document

Inherits: Element

Document derives from Element. Document has no constructor; it must be instantiated through a Context object instead, either by loading an external RML file or creating an empty document. It has the following functions and properties:

Properties

Name	Type
context	Context
title	string

Functions

Name	Return Type
Close()	nil
CreateElement(string tag_name)	ElementPtr
CreateTextNode(string text)	ElementPtr
Hide()	nil
PullToFront()	nil
PushToBack()	nil
Show(nil, DocumentModal modal, nil, DocumentFocus focus)	nil

Property Descriptions

context :: Context

The context the document belongs to. Read-only.

title :: string

The title of the document, as initially set by the <title> tag in the document’s header.

Function Descriptions

Close() → nil

Hides and closes the document, destroying its contents.

CreateElement(string tag_name) → ElementPtr

Instances an element with a tag of tag_name.

CreateTextNode(string text) → ElementPtr

Instances a text element containing the string text.

Hide() → nil

Hides the document.

PullToFront() → nil

Pulls the document in front of other documents within its context with a similar z-index.

PushToBack() → nil

Pushes the document behind other documents within its context with a similar z-index.

Show(nil, DocumentModal modal, nil, DocumentFocus focus) → nil

Shows the document. Optional enum arguments to specify modal and focus mode. Defaults to DocumentModal.None and DocumentFocus.Auto.

---

Element

Inherits: nil

The Element class has no constructor; it must be instantiated through a Document object instead. It has the following functions and properties:

Properties

Name	Type
attributes	ElementAttributesProxy
child_nodes	ElementChildNodesProxy
class_name	string
client_height	number
client_left	number
client_top	number
client_width	number
first_child	nil, Element
id	string
inner_rml	string
last_child	nil, Element
next_sibling	nil, Element
offset_height	number
offset_left	number
offset_parent	Element
offset_top	number
offset_width	number
owner_document	Document
parent_node	nil, Element
previous_sibling	nil, Element
scroll_height	number
scroll_left	number
scroll_top	number
scroll_width	number
style	ElementStyleProxy
tag_name	string

Functions

Name	Return Type
AddEventListener(string event, function, string listener, boolean in_capture_phase)	nil
AppendChild(ElementPtr element)	nil, Element
Blur()	nil
Click()	nil
DispatchEvent(string event, table parameters)	nil
new(string tag)	Element
Focus()	nil
GetAttribute(string name)	Variant
GetElementById(string id)	Element
GetElementsByTagName(string tag_name)	table
HasAttribute(string name)	boolean
HasChildNodes()	boolean
InsertBefore(ElementPtr element, Element adjacent_element)	nil, Element
IsClassSet(string name)	boolean
QuerySelector(string selectors)	Element
QuerySelectorAll(string selectors)	table
Matches(string selectors)	boolean
RemoveAttribute(string name)	nil
RemoveChild(Element element)	boolean
ReplaceChild(ElementPtr inserted_element, Element replaced_element)	boolean
ScrollIntoView(boolean align_with_top)	nil
SetAttribute(string name, string value)	nil
SetClass(string name, boolean value)	nil

Property Descriptions

attributes :: ElementAttributesProxy

The array of attributes on the element. Each element has the read-only properties name and value. Read-only.

child_nodes :: ElementChildNodesProxy

The array of child nodes on the element. Read-only.

class_name :: string

The space-separated list of classes on the element.

client_height :: number

The height of the element’s client area. Read-only.

client_left :: number

The distance between the left border edge and the left client edge of the element. Read-only.

client_top :: number

The distance between the top border edge and the top client edge of the element. Read-only.

client_width :: number

The width of the element’s client area. Read-only.

first_child :: nil, Element

The first child of the element, or nil if the client has no children. Read-only.

id :: string

The ID of the element, or the empty string if the element has no ID.

inner_rml :: string

The element’s RML content.

last_child :: nil, Element

The last child of the element, or nil if the client has no children. Read-only.

next_sibling :: nil, Element

The element’s next sibling, or nil if it is the last sibling. Read-only.

offset_height :: number

The height of the element, excluding margins. Read-only.

offset_left :: number

The distance between the element’s offset parent’s left border edge and this element’s left border edge. Read-only.

offset_parent :: Element

The element’s offset parent. Read only.

offset_top :: number

The distance between the element’s offset parent’s top border edge and this element’s top border edge. Read-only.

offset_width :: number

The width of the element, excluding margins. Read-only.

owner_document :: Document

The document this element is part of. Read-only.

parent_node :: nil, Element

The element this element is directly parented to. Read-only.

previous_sibling :: nil, Element

The element’s previous sibling, or None if it is the first sibling. Read-only.

scroll_height :: number

The height of this element’s content. This will be at least as high as the client height. Read-only.

scroll_left :: number

The offset between the left edge of this element’s client area and the left edge of the content area.

scroll_top :: number

The offset between the top edge of this element’s client area and the top edge of the content area.

scroll_width :: number

The width of this element’s content. This will be at least as wide as the client width. Read-only.

style :: ElementStyleProxy

An object used to access this element’s style information. Individual RCSS properties can be accessed by using the name of the property as a Lua property on the object itself (ie, element.style.width = “40px”).

tag_name :: string

The tag name used to instance this element. Read-only.

Function Descriptions

AddEventListener(string event, function, string listener, boolean in_capture_phase) → nil

NOTE: Events added from Lua cannot be removed.

AppendChild(ElementPtr element) → nil, Element

Appends element as a child to this element.

Blur() → nil

Removes input focus from this element.

Click() → nil

Fakes a click on this element.

DispatchEvent(string event, table parameters) → nil

Dispatches an event to this element. The event is a string value of the event type, without the ‘on’ prefix. Parameters to the event are given in the dictionary parameters; the dictionary must only contain string keys, and numeric, string or boolean values.

new(string tag) → Element

Construct new Element object.

Focus() → nil

Gives input focus to this element.

GetAttribute(string name) → Variant

Returns the value of the attribute named name. If no such attribute exists, the empty string will be returned.

GetElementById(string id) → Element

Returns the descendant element with an id of id.

GetElementsByTagName(string tag_name) → table

Returns a list of all descendant elements with the tag of tag_name. Returned table is indexable with integers.

HasAttribute(string name) → boolean

Returns true if the element has a value for the attribute named name, false if not.

HasChildNodes() → boolean

Returns true if the element has at least one child node, false if not.

InsertBefore(ElementPtr element, Element adjacent_element) → nil, Element

Inserts the element element as a child of this element, directly before adjacent_element in the list of children.

IsClassSet(string name) → boolean

Returns true if the class name is set on the element, false if not.

QuerySelector(string selectors) → Element

Returns the first descendant element matching the provided RCSS selector(s).

QuerySelectorAll(string selectors) → table

Returns a set of all descendant elements matching the provided RCSS selector(s). Returned table is indexable with integers.

Matches(string selectors) → boolean

Returns true if the element matches the provided RCSS selector(s), false if not.

RemoveAttribute(string name) → nil

Removes the attribute named name from the element.

RemoveChild(Element element) → boolean

Removes the child element element from this element.

ReplaceChild(ElementPtr inserted_element, Element replaced_element) → boolean

Replaces the child element replaced_element with inserted_element in this element’s list of children. If replaced_element is not a child of this element, inserted_element will be appended onto the list instead.

ScrollIntoView(boolean align_with_top) → nil

Scrolls this element into view if its ancestors have hidden overflow. If align_with_top is true, the element’s top edge will be aligned with the top (or as close as possible to the top) of its ancestors’ viewing windows. If false, its bottom edge will be aligned to the bottom.

SetAttribute(string name, string value) → nil

Sets the value of the attribute named name to value.

SetClass(string name, boolean value) → nil

Sets (if value is true) or clears (if value is false) the class name on the element.

---

ElementAttributesProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__pairs

---

ElementChildNodesProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__pairs
__len

---

ElementForm

Inherits: Element

ElementForm derives from Element. The form element has the following function:

Functions

Name	Return Type
Submit(nil, string name, nil, string submit_value)	nil

Function Descriptions

Submit(nil, string name, nil, string submit_value) → nil

Submits the form with name of name and a submit value of submit_value. name and value are optional and are empty by default.

---

ElementFormControl

Inherits: Element

Properties

Name	Type
disabled	boolean
name	string
value	string

Property Descriptions

disabled :: boolean

name :: string

value :: string

---

ElementFormControlInput

Inherits: ElementFormControl

ElementFormControlInput derives from IElementFormControl. The control has the following properties, only appropriate on the relevant types:

Properties

Name	Type
checked	boolean
max	integer
maxlength	integer
min	integer
size	integer
step	integer

Functions

Name	Return Type
GetSelection()	integer, integer, string
Select()	nil
SetSelection(integer selection_start, integer selection_end)	nil

Property Descriptions

checked :: boolean

Relevant for radio and checkbox types. The checked status of the input.

max :: integer

Relevant for range types. The value of the control on the bottom / right of the slider.

maxlength :: integer

min :: integer

Relevant for range types. The value of the control on the top / left of the slider.

size :: integer

Relevant for text types. The approximate number of characters the text field shows horizontally at once.

step :: integer

Relevant for range types. The step the control’s value changes in.

Function Descriptions

GetSelection() → integer, integer, string

Retrieves the selection range and text. If no text is selected, both offsets are equal to 1.

Select() → nil

Selects all text.

SetSelection(integer selection_start, integer selection_end) → nil

Selects the text in the given character range.

---

ElementFormControlSelect

Inherits: ElementFormControl

ElementFormControlSelect derives from IElementFormControl. The control has the following functions and properties:

Properties

Name	Type
options	SelectOptionsProxy
selection	integer

Functions

Name	Return Type
Add(string rml, string value, nil, integer before)	integer
Remove(integer index)	nil
RemoveAll()	nil

Property Descriptions

options :: SelectOptionsProxy

The array of options available in the select box. Each entry in the array has the property value, the string value of the option, and element, the root of the element hierarchy that represents the option in the list.

selection :: integer

The index of the currently selected option.

Function Descriptions

Add(string rml, string value, nil, integer before) → integer

Adds a new option to the select box. The new option has the string value of value and is represented by the elements created by the RML string rml. The new option will be inserted by the index specified by before; if this is out of bounds (the default), then the new option will be appended onto the list. The index of the new option will be returned.

Remove(integer index) → nil

Removes an existing option from the selection box.

RemoveAll() → nil

---

ElementFormControlTextArea

Inherits: ElementFormControl

ElementFormControlTextArea derives from IElementFormControl. The control has the following properties:

Properties

Name	Type
cols	integer
maxlength	integer
rows	integer
wordwrap	boolean

Functions

Name	Return Type
GetSelection()	integer, integer, string
Select()	nil
SetSelection(integer selection_start, integer selection_end)	nil

Property Descriptions

cols :: integer

The approximate number of characters the text area shows horizontally at once.

maxlength :: integer

rows :: integer

The number of lines the text area shows at once.

wordwrap :: boolean

Function Descriptions

GetSelection() → integer, integer, string

Retrieves the selection range and text. If no text is selected, both offsets are equal to 1.

Select() → nil

Selects all text.

SetSelection(integer selection_start, integer selection_end) → nil

Selects the text in the given character range.

---

ElementInstancer

Inherits: nil

Functions

Name	Return Type
new()	ElementInstancer
InstanceElement(ElementInstancer )	value

Function Descriptions

new() → ElementInstancer

InstanceElement(ElementInstancer ) → value

---

ElementPtr

Inherits: nil

Represents an owned element. This type is mainly used to modify the DOM tree by passing the object into other elements. For example Element.AppendChild().

A current limitation in the Lua plugin is that Element member properties and functions cannot be used directly on this type.

---

ElementStyleProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__newindex
__pairs

---

ElementTabSet

Inherits: Element

ElementTabSet derives from Element. The control has the following functions and properties:

Properties

Name	Type
active_tab	integer
num_tabs	integer

Functions

Name	Return Type
SetPanel(integer index, string rml)	nil
SetTab(integer index, string rml)	nil

Property Descriptions

active_tab :: integer

Index of the active panel.

num_tabs :: integer

The number of tabs in the tab set. Read-only.

Function Descriptions

SetPanel(integer index, string rml) → nil

Sets the contents of a panel to the RML content rml. If index is out-of-bounds, a new panel will be added at the end.

SetTab(integer index, string rml) → nil

Sets the contents of a tab to the RML content rml. If index is out-of-bounds, a new tab will be added at the end.

---

ElementText

Inherits: Element

Properties

Name	Type
text	string

Property Descriptions

text :: string

---

Event

Inherits: nil

The Event class has no constructor; it is generated internally. It has the following functions and properties:

Properties

Name	Type
current_element	Element
parameters	EventParametersProxy
target_element	Element
type	string

Functions

Name	Return Type
StopPropagation()	nil
StopImmediatePropagation()	nil

Property Descriptions

current_element :: Element

The element the event has propagated to. Read-only.

parameters :: EventParametersProxy

A dictionary like object containing all the parameters in the event.

target_element :: Element

The element the event was originally targeted at. Read-only.

type :: string

The string name of the event. Read-only.

Function Descriptions

StopPropagation() → nil

Stops the propagation of the event through the event cycle, if allowed.

StopImmediatePropagation() → nil

Stops the propagation of the event through the event cycle, including to any other listeners on the current element.

---

EventParametersProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__pairs

---

GlobalLuaFunctions

Inherits: nil

Functions

Name	Return Type
print(... output)	nil

Function Descriptions

print(... output) → nil

Overrides the Lua print method and redirects it to the RmlUi logging system, which can eg. be accessed through the RmlUi debugger.

---

Log

Inherits: nil

Log messages through RmlUi.

Properties

Name	Type
logtype	table

Functions

Name	Return Type
Message(Log.logtype type, string str)	nil

Property Descriptions

logtype :: table

Enum table for specifying the type of log.

• Log.logtype.always
• Log.logtype.error
• Log.logtype.warning
• Log.logtype.info
• Log.logtype.debug

Function Descriptions

Message(Log.logtype type, string str) → nil

Log a message with a type.

---

rmlui

Inherits: nil

rmlui exposes some general RmlUi functionality globally in Lua. Access with the global table rmlui.

Properties

Name	Type
contexts	RmlUiContextsProxy
key_identifier	table
key_modifier	table

Functions

Name	Return Type
CreateContext(string name, Vector2i dimensions)	nil Context
LoadFontFace(string path)	boolean
RegisterTag(string tag)	nil

Property Descriptions

contexts :: RmlUiContextsProxy

Table of active contexts indexable with integers and context name strings.

key_identifier :: table

Enum containing all input key identifiers.

key_modifier :: table

Enum containing all input key modifiers.

Function Descriptions

CreateContext(string name, Vector2i dimensions) → Context, Context

Create RmlUi context with specified dimensions.

LoadFontFace(string path) → boolean

Load font face at path

RegisterTag(string tag) → nil

Register tag to element instancer.

---

RmlUiContextsProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__pairs

---

SelectOptionsProxy

Inherits: nil

Metafunctions

Metafunctions
__index
__pairs

---

Vector2f

Inherits: nil

Constructs a two-dimensional floating-point vector.

Properties

Name	Type
magnitude	number
x	number
y	number

Functions

Name	Return Type
DotProduct(Vector2f other)	number
Normalise()	Vector2f
Rotate(number angle)	Vector2f
new(number x, number y)	Vector2f

Metafunctions

Metafunctions
__add
__div
__eq
__mul
__sub

Property Descriptions

magnitude :: number

x :: number

y :: number

Function Descriptions

DotProduct(Vector2f other) → number

Normalise() → Vector2f

Rotate(number angle) → Vector2f

new(number x, number y) → Vector2f

---

Vector2i

Inherits: nil

Constructs a two-dimensional integral vector.

Properties

Name	Type
magnitude	number
x	integer
y	integer

Functions

Name	Return Type
new(integer x, integer y)	Vector2i

Metafunctions

Metafunctions
__add
__div
__eq
__mul
__sub

Property Descriptions

magnitude :: number

x :: integer

y :: integer

Function Descriptions

new(integer x, integer y) → Vector2i

---