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
• DataFormatter
• DataSource
• ElementInstancer
• ElementPtr
• GlobalLuaFunctions
• Log
• Vector2f
• Vector2i

Special Elements

• ElementDataGrid
• ElementDataGridRow
• ElementForm
• ElementFormControl
• ElementFormControlDataSelect
• 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
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
LoadDocument(string document_path)	Document
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.

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.

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.

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

---

DataFormatter

Inherits: nil

Lua data formatting helper.

Properties

Name	Type
FormatData	function

Functions

Name	Return Type
new(nil, function format_data)	DataFormatter

Property Descriptions

FormatData :: function

Formatting function which returns a string

Function Descriptions

new(nil, function format_data) → DataFormatter

Construct a new DataFormatter object. Optional format_data argument which is a function which returns a string.

---

DataSource

Inherits: nil

Abstract DataSource Interface.

Functions

Name	Return Type
new(string name)	DataSource
GetNumRows(DataSource table_name)	integer
GetRow(DataSource table_name, lua_type index)	string
NotifyRowAdd(string table_name, integer first_row_added, integer num_rows_added)	nil
NotifyRowChange(string table_name, nil, integer first_row_changed, nil, integer num_rows_changed)	nil
NotifyRowRemove(string table_name, integer first_row_removed, integer num_rows_removed)	nil

Function Descriptions

new(string name) → DataSource

Construct a new DataSource object.

GetNumRows(DataSource table_name) → integer

Return the number of rows in the given table

GetRow(DataSource table_name, lua_type index) → string

Return a list of the column values in string form

NotifyRowAdd(string table_name, integer first_row_added, integer num_rows_added) → nil

Notify listeners that rows have been added to the data source.

NotifyRowChange(string table_name, nil, integer first_row_changed, nil, integer num_rows_changed) → nil

Notify listeners that all rows on the data source have changed. Optional arguments first_row_changed for specifying the first row number which changed and num_rows_changed for specifying how many rows changed after the first row.

NotifyRowRemove(string table_name, integer first_row_removed, integer num_rows_removed) → nil

Notify listeners that rows have been removed from the data source.

---

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
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
IsClassSet(string name)	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

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

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.

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

---

ElementDataGrid

Inherits: Element

ElementDataGrid derives from Element. The data grid has the following functions and properties:

Properties

Name	Type
rows	table

Functions

Name	Return Type
AddColumn(string fields, string formatter, number initial_width, string header_rml)	nil
SetDataSource(string data_source_name)	nil

Property Descriptions

rows :: table

Returns an array containing all the rows in the data grid.

Function Descriptions

AddColumn(string fields, string formatter, number initial_width, string header_rml) → nil

Adds a new column to the data grid. The column will read the columns fields (in CSV format) from the grid’s data source, processing it through the data formatter named formatter. header_rml specifies the RML content of the column’s header.

SetDataSource(string data_source_name) → nil

Sets the name and table of the new data source to be used by the data grid.

---

ElementDataGridRow

Inherits: Element

ElementDataGridRow derives from Element. The data grid row has the following properties:

Properties

Name	Type
parent_grid	ElementDataGrid
parent_relative_index	integer
parent_row	ElementDataGridRow
row_expanded	boolean
table_relative_index	integer

Property Descriptions

parent_grid :: ElementDataGrid

The data grid that this row belongs to.

parent_relative_index :: integer

The index of the row, relative to its parent row. So if you are the third row in your parent, then it will be 3.

parent_row :: ElementDataGridRow

The parent row of this row. None if it at the top level.

row_expanded :: boolean

The expanded state of the row, either true or false.

table_relative_index :: integer

The index of the row, relative to the data grid it is in. This takes into account all previous rows and their children.

---

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

---

ElementFormControlDataSelect

Inherits: ElementFormControlSelect

ElementFormControlDataSelect derives from ElementFormControlSelect. It has the following additional function:

Functions

Name	Return Type
SetDataSource(string data_source_name)	nil

Function Descriptions

SetDataSource(string data_source_name) → nil

Sets the name and table of the new data source to be used by the select box.

---

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

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.

---

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

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

---

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

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.

---

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

---