General

To get a general idea of how this works:

1. define a GuiClassDefinition
2. register it, making it available as a GuiClass
3. use the create function (or any of the add functions) to create a GuiClassInst of said class
4. use the destroy function to destroy that instance again

The biggest part is defining the GuiClassDefinition and the GuiClassInstDefinition in it's create function.

All functions are meant to be called wherever modifying the game state is fine, except the register_class and register_classes functions; They can technically be called at any time, but must be called in mod startup/initialization for proper on_load.

on_load

(the on_load is handled by the library, no on_load function needs calling)

All GuiClassInsts which existed when saving get their metatables set again and their event handlers resubscribed. This means all GuiClasses must exist before on_load.

Functions

• create(parent_element, class_name, name, ...) -> inst: creates a new GuiClassInst as a child of the given LuaGuiElement parent_element
• add_child(parent, class_name, name, ...) -> inst: creates a new GuiClassInst as a child of the given LuaGuiInst parent
• add_child_definition(parent, child) -> inst: creates a new GuiClassInst as a child of the given LuaGuiInst parent
• add_children(parent, children): calls add_child_definition for each GuiClassInstChildDefinition in children
• destroy(inst): destroys inst and all of it's children
• got_destroyed(inst): does the same as destroy, but you should use this instead when you would like to mark an inst as being destroyed because it's LuaGuiElement got invalidated
• register_class(class): registers a class, making it available to be created and added as GuiClassInsts
• register_classes(classes): registers all classes, making them available to be created and added as GuiClassInsts

Internal Functions

• create_base(parent_element, parent, class_name, name, parent_pass_count, ...) -> inst: the internal function used to create GuiClassInsts. This is here to not explain the same thing 3 times but always slightly different. Now instead it's just one - more complex - function, but 3 - less complex - functions

create_base

Signature

create_base(parent_element : LuaGuiElement, parent : GuiClassInst, class_name : string, name : nil | string, parent_pass_count : integer, ... : any) -> GuiClassInst

Parameters

• parent_element: The parent of the created GuiClassInst's elem
• parent: The parent of the created GuiClassInst
• class_name: The class_name of the GuiClass used to create the GuiClassInst
• name: The name of the created GuiClassInst
• parent_pass_count: How many parents (layers) to pass for the created GuiClassInst's passed_parent (1 means passed_parent will be inst.parent.parent)
• ...: Parameters which will get passed to the GuiClass.create(...) function

Returns

A new GuiClassInst.

Remarks

There is very little validation - the only thing validated is the class_name, if anything else has bad data, random errors will occur.

This function does the following in the following order:

• gets class using class_name
• calls local inst, passed_data = class.create(...)
• setmetatable(inst, class)
• local children = inst.children
• inst.children = {}
• inst.class_name = class_name
• inst.name = name
• inst.elem = parent_element.add(inst)
• inst.parent = parent
• writes passed_data to inst (if not nil)
• evaluates passed_parent
• if inst has a parent and a name then inst.passed_parent[name] = inst
• applies elem_mods
• applies style_mods
• calls class.on_elem_created(inst) if it exists
• subscribes event handlers (uses the GuiClass's event_conditions)
• calls add_children where parent is inst and children is children
• calls class.on_create(inst) if it exists
• returns inst

create

Signature

create(parent_element : LuaGuiElement, class_name : string, name : nil | string, ... : any) -> GuiClassInst

Parameters

• parent_element: The parent of the created GuiClassInst's elem
• class_name: The class_name of the GuiClass used to create the GuiClassInst
• name: The name of the created GuiClassInst
• ...: Parameters which will get passed to the GuiClass.create(...) function

Returns

A new GuiClassInst.

Remarks

Calls create_base with the following parameters:

• parent_element = parent
• parent = nil
• class_name = class_name
• name = name
• parent_pass_count = 0
• ... = ...

add_child

Signature

add_child(parent : GuiClassInst, class_name: string, name : nil | string, ... : any) -> GuiClassInst

Parameters

• parent: The parent of the created GuiClassInst (the inst.parent is parent and the inst.elem's parent is parent.elem)
• class_name: The class_name of the GuiClass used to create the GuiClassInst
• name: The name of the created GuiClassInst
• ...: Parameters which will get passed to the GuiClass.create(...) function

Returns

A new GuiClassInst.

Remarks

Calls create_base with the following parameters:

• parent_element = parent.elem
• parent = parent
• class_name = class_name
• name = name
• parent_pass_count = 0
• ... = ...

And afterwards

if name then
  parent.children[name] = inst
  parent[name] = inst
else
  table.insert(parent.children, inst)
end

add_child_definition

Signature

add_child_definition(parent : GuiClassInst, child : GuiClassInstChildDefinition) -> GuiClassInst

Parameters

• parent: The parent of the created GuiClassInst (the inst.parent is parent and the inst.elem.parent is parent.elem)
• child: The definition of the GuiClassInst to be created

Returns

A new GuiClassInst.

Remarks

Calls create_base with the following parameters:

• parent_element = parent.elem
• parent = parent
• class_name = child.class_name
• name = child.name
• parent_pass_count = child.parent_pass_count or 0
• ... = all values of child with integer keys starting at 1 ascending

And afterwards

if name then
  parent.children[name] = inst
  parent[name] = inst
else
  table.insert(parent.children, inst)
end

add_children

Signature

add_children(parent : GuiClassInst, children : GuiClassInstChildDefinition[])

Parameters

• parent: The parent of all created GuiClassInst (the inst.parent is parent and the inst.elem.parent is parent.elem)
• children: The definition of the GuiClassInsts to be created

Remarks

Essentially calls add_child_definition for every GuiClassInstChildDefinition in children

destroy

Signature

destroy(inst : GuiClassInst)

Parameters

• inst: The GuiClassInst to be destroyed

Remarks

• calls inst:on_destroy() on every child recursively (starting at the most inner child)
• destroys inst.elem if it is valid
• if inst has a parent GuiClassInst, removes inst from it's parent's children (and from parent and passed_parent directly if inst has a name)
• internal cleanup

got_destroyed

Signature

got_destroyed(inst : GuiClassInst)

Parameters

• inst: The GuiClassInst which has been destroyed, but has not cleaned up yet

Remarks

It simply calls destroy. However this should still be used instead whenever an inst's elem has been invalidated.

register_class

Signature

register_class(class : GuiClassDefinition)

Parameters

• class: The class to be registered and made available as a GuiClass

Remarks

Converts the given GuiClassDefinition to a GuiClass by modifying the table. Anything asking for a class_name now accepts this class' name as a valid class name.

register_classes

Signature

register_classes(classes : GuiClassDefinition[])

Parameters

• classes: The classes to be registered and made available as GuiClasses

Remarks

Calls register_class for each GuiClassDefinition in classes.