Skip to content

luxe API (2025.1.2)

luxe: ui/control module

Control

import "luxe: ui/control" for Control

Class for managing controls on UI modifiers. Note that all UI elements are controls, including UIImage, UILabel, UIButton, etc...

  _ui = Entity.create(app.ui)
  UI.create(_ui, 0, 0, app.width, app.height, 0, app.ui_camera)

  var control = Control.create(_ui)

Control.create(ui_entity: Entity) returns Control

Create a "blank" control for layout or custom input/drawing. Returns the new Control.

Control.destroy(control: Control) returns None

Destroy an existing control.

  var control = Control.create(_ui)
  //do stuff and then later...
  Control.destroy(control)

Control.destroy_children(control: Control) returns None

Destroy the children of a control.

Control.valid(control: Control) returns Bool

Check if a control exists and has not been destroyed.

  var control = Control.create(_ui)
  Log.print(Control.valid(control)) //true
  Control.destroy(control)
  Log.print(Control.valid(control)) //false

Control.get_ui(control: Control) returns Entity

Get UI entity a control is part of.

  var control = Control.create(_ui)
  var control_ui = Control.get_ui(control)
  Log.print(control_ui == _ui) //true

Control.get(id: String) returns Control

Get a control by its id.

  var control = Control.create(_ui)
  Control.set_id(control, "test_id")
  var control_by_id = Control.get("test_id")
  Log.print(control == control_by_id) //true

Control.exists(id: String) returns Bool

Check if a control with a specific id exists.

Control.clear(control: Control, uiclear_action: UIClear) returns None

Clear the children of a control in a specific manner.

Control.press(control: Control, state: Bool) returns None

Send a press or release event to the control (in the center of the control)

Control.enter(control: Control, state: Bool) returns None

Send a enter or exit event to the control

Control.can_see(control: Control) returns Bool

Returns true if this control can be seen, or false if clipped.

Control.can_see_area(control: Control, area: Rect) returns Bool

Returns true if the area at this control can be seen or false if clipped.

Control.can_see_point(control: Control, point: Vec) returns Bool

Returns true if the point at this control can be seen or false if clipped.

Control.set_type(control: Control, type: String) returns unknown

no docs found

Control.get_type(control: Control) returns unknown

no docs found

Control.set_id(control: Control, id: String) returns unknown

Set the id of a control. Good for debugging and retrieving controls by their id. Must be unique, so adding ID.unique() to the id can be useful.

  var control = Control.create(_ui)
  Control.set_id(control, "good_recognizable_control_name_%(ID.unique())")

Control.get_id(control: Control) returns String

Retrieve the id of a control.

Control.get_bounds_abs(control: Control, into: List) returns None

Retrieve the bounds(position and size) of a control (relative to the UI modifier) into a list [x, y, width, height]. The passed list must have at least 4 elements and the function will write into the first 4. Passing a list into the function instead of returning a value is to avoid allocating memory where not needed.

  var parent = Control.create(_ui)
  Control.set_pos(parent, 50, 50)
  var child = Control.create(_ui)
  Control.child_add(parent, child)
  Control.set_pos(child, 100, 100)
  Control.set_size(child, 20, 20)
  var bounds = [0,0,0,0]
  Control.get_bounds_abs(child, bounds)
  Log.print(bounds) // [150, 150, 20, 20]

Control.get_bounds(control: Control, into: List) returns None

Retrieve the bounds(position and size) of a control (relative to their parent control or ui modifier if there is none) into a list [x, y, width, height]. The passed list must have at least 4 elements and the function will write into the first 4. Passing a list into the function instead of returning a value is to avoid allocating memory where not needed.

  var parent = Control.create(_ui)
  Control.set_pos(parent, 50, 50)
  var child = Control.create(_ui)
  Control.child_add(parent, child)
  Control.set_pos(child, 100, 100)
  Control.set_size(child, 20, 20)
  var bounds = [0,0,0,0]
  Control.get_bounds(child, bounds)
  Log.print(bounds) // [100, 100, 20, 20]

Control.set_allow_bounds_event(control: Control, state: Bool) returns None

Enables bounds events for the control. Since there are many controls that may be resized during layout events, only ones that ask for the event will receive it to save time.

Control.get_allow_bounds_event(control: Control) returns Bool

Returns true if this control sends bounds events.

Control.set_bounds_abs(control: Control, x: Num, y: Num, w: Num, h: Num) returns None

Set the control bounds(position and size) relative to the UI modifier.

Control.set_bounds(control: Control, x: Num, y: Num, w: Num, h: Num) returns None

Set the control bounds(position and size) relative to the parent control.

Control.set_pos_abs(control: Control, x: Num, y: Num) returns None

Set the control position relative to the UI modifier.

Control.set_pos(control: Control, x: Num, y: Num) returns None

Set the control position relative to the parent control, or UI modifier if no parent exists.

Control.set_system_cursor(control: Control, cursor: SystemCursor) returns None

If the control has input enabled, when entered it will set the system cursor to the given type.

Control.set_size(control: Control, w: Num, h: Num) returns None

Set the control size.

Control.get_pos_x(control: Control) returns Num

Get the control position x component relative to its parent control.

Control.get_pos_x_abs(control: Control) returns Num

Get the control position x component.

Control.get_pos_y(control: Control) returns Num

Get the control position y component relative to its parent control.

Control.get_pos_y_abs(control: Control) returns Num

Get the control position y component.

Control.get_width(control: Control) returns Num

Get the control width.

Control.get_height(control: Control) returns Num

Get the control height.

Control.contains(control: Control, x: Num, y: Num) returns Bool

Check whether the a point is within the control bounds

Control.get_entity(control: Control) returns Entity

Get the entity that has the UI modifier the control in.

Control.get_parent(control: Control) returns Control

Get the entity this entity is a child of or null if there isnt any.

Control.get_allow_input(control: Control) returns Bool

Get whether the control recieves input events in its set_process function.

Control.set_allow_input(control: Control, allow: Bool) returns None

Set whether the control recieves input events in its set_process function.

Control.set_allow_drag(control: Control, allow: Bool, tag: String) returns None

Set whether the control recieves drag events

Control.set_droppable_payload(control: Control, value: Handle) returns None

Set a value that will be passed through the drag event to the drop event on the other side. This value is a handle/number, so you can pass api handles, a number, a hashed string, or a block instance

Control.get_droppable_payload(control: Control) returns Handle

Get the drop payload for this control

Control.set_droppable_tags(control: Control, tags: List) returns None

Set the droppable tags that are allowed for this control, as an array of strings

Control.get_droppable_tags(control: Control) returns List

Get the droppable tags that are allowed for this control, as an array of strings

Control.get_allow_keys(control: Control) returns Bool

Get whether the control recieves key events in its set_process function.

Control.set_allow_keys(control: Control, allow: Bool) returns None

Set whether the control recieves key events in its set_process function.

Control.get_allow_tab(control: Control) returns Bool

Get whether the control can be "tabbed" to.

Control.set_allow_tab(control: Control, allow: Bool) returns None

Set whether the control can be "tabbed" to.

Control.get_visible(control: Control) returns Bool

Get whether a control is visible.

Control.set_visible(control: Control, visible: Bool) returns None

Set whether a control (or its children) is visible. Note that when a control is not visible, it also doesnt contribute to the layout.

Control.get_opacity(control: Control) returns Num

Get a control opacity value.

Control.set_opacity(control: Control, opacity: Num) returns None

Set a control opacity value. Affects children opacity as well.

Control.get_disabled(control: Control) returns Bool

Get whether a control is disabled. This refers to the "inputable" state of inputs like buttons or text fields.

Control.set_disabled(control: Control, disabled: Bool) returns None

Set whether a control is disabled. This refers to the "inputable" state of inputs like buttons or text fields.

Control.get_enabled(control: Control) returns Bool

Get whether a control is enabled. This refers to the "inputable" state of inputs like buttons or text fields.

Control.set_enabled(control: Control, enabled: Bool) returns None

Set whether a control is enabled. This refers to the "inputable" state of inputs like buttons or text fields.

Control.get_clip(control: Control) returns Bool

Get whether a control should clip its contents.

Control.set_clip(control: Control, clip: Bool) returns None

Set whether a control should clip its contents.

Control.get_nodes(control: Control) returns Num

Get how many child controls this control has recursively. So 1 if it doesnt have any children, 2 if it has 1 child, 3 if it has 2 children or if it has 1 child which itself has a child, etc... Only valid after UI.commit.

Control.get_depth(control: Control) returns Num

Get the depth generated for a control, not including the depth offset.

Control.get_depth_offset(control: Control) returns Num

Get the depth offset of a control.

Control.set_depth_offset(control: Control, depth_offset: Num) returns None

Set the depth offset for a control, allowing you to move it in front or behind other controls if the generated depth doesnt work for you

Control.get_input_inside(control: Control) returns Bool

Check whether the input (usually mouse cursor) is currently in a control. (In sync with UIEvent.enter and UIEvent.exit)

Control.get_input_pressed(control: Control) returns Bool

Check whether the input (usually mouse cursor) is currently in a control and any of its buttons are pressed.

Control.child_at_point(control: Control, x: Num, y: Num) returns Control

Get the top child control at a specific (absolute) point.

Control.child_count(control: Control) returns Num

Get the amount of children a control has.

Control.child_index(control: Control, child: Control) returns Num

Get the index of a child control.

Control.child_get(control: Control, index: Num) returns Child

Get a child control by its index.

Control.child_add(control: Control, child: Control, internal: Bool) returns None

Make a control the child control of another control. If you mark the child as internal, it wont be queried by other methods affecting children.

Control.child_add(control: Control, child: Control) returns None

Make a control the child control of another control. This means the childs position will be relative to its parent, layout depends a lot on those relationships and its used by functions like destroy_children.

  //create parent
  var parent = Control.create(_ui)
  Control.set_bounds(parent, 200, 200, 100, 100)
  //create child
  var child = Control.create(_ui)
  Control.set_bounds(child, 25, 25, 50, 50)

  //parent child to parent
  Control.child_add(parent, child)

  var bounds = [0,0,0,0]
  Control.get_bounds_abs(child, bounds)
  Log.print(bounds) //[225, 225, 50, 50]

  Control.clear(parent, UIClear.destroy)
  Log.print(Control.child_count(parent)) //0
  Log.print(Control.valid(child)) //false

  UI.commit(_ui)

Control.child_remove(control: Control, child: Control) returns None

Remove a child from a control, unparenting it.

Control.children_bounds(control: Control, into: List) returns None

Get the combined bounds of all children of a control into a list [x, y, width, height]. The passed list must have at least 4 elements and the function will write into the first 4. Passing a list into the function instead of returning a value is to avoid allocating memory where not needed.

Control.set_behave(control: Control, behave: UIBehave) returns None

Set how the control behaves in the layout as a child of its container. You can combine characteristics with a bit or operator (|).

Control.get_behave(control: Control) returns UIBehave

Returns the behave bitflags for the control

Control.set_contain(control: Control, contain: UIContain) returns None

Set how the control behaves in the layout as a container of its children. You can combine characteristics with a bit or operator (|).

Control.get_contain(control: Control) returns UIContain

Returns the contain bitflags for the control

Control.set_margin(control: Control, left: Num, top: Num, right: Num, bottom: Num) returns None

Set the margins of a control. Only the margins set in set_behave are actually observed.

Control.set_limits(control: Control, min_x: Num, min_y: Num, max_x: Num, max_y: Num) returns None

Set the min and max size of a control when using layout.

Control.get_margin(control: Control) returns List

Get the margins of a control.

Control.set_render(control: Control, fn: Fn) returns None

Set a custom render function with the arguments |control, state, x, y, w, h|. Useful for making your own controls.

Control.set_events(control: Control, fn: Fn) returns String

Add a function to handle events on a control. Returns an id for the newly added event that can be used to remove it.

  var btn = UIButton.create(ui)
  UIButton.set_text(btn, "click me!")
  Control.set_events(btn) {|event|
    if(event.type == UIEvent.release) {
      Log.print("clicked button")
    }
  }

Control.unset_events(control: Control, id: String) returns None

Remove an event handling function from a control. Takes in the id that was returned upon registering the function.

Control.set_process(control: Control, fn: Fn) returns None

Set a custom process function with the arguments |control, state, event, x, y, w, h|. Useful for making your own controls.

Control.get_state_data(control: Control) returns Any

Get the state data associated with this control.

Control.set_state_data(control: Control, data: Any) returns None

Set state data associated with this control. Can be any wren object.