Class Frame

A Region that can contain other regions and react to events.

This class, which is at the core of the UI design, can contain other Frames as "children", and LayeredRegions sorted by layers (text, images, ...). A frame can also react to events, and register callbacks to be executed on particular events (key presses, etc.) or on every tick.

Each frame has an optional "title region", which can be used to define and draw a title bar. This title bar can then be used to move the frame around the screen using mouse click and drag. Furthermore, frames have optional support for resizing by click and drag on corners or edges (opt in).

Frames can either move freely on the screen, or be "clamped" to the screen so they cannot be partly outside of their render area.

Rendering. Frames are grouped into different "strata", which are rendered sequentially. Frames in a high strata will always be rendered above frames in a low strata. Then, within a strata, frames are further sorted by "level"; within this particular strata, a frame with a high level will always be rendered above all frames with a lower level, but it will still remain below other frames in a higher strata. The level of a frame is automatically set to the maximum level inside the strata when the frame is clicked, which effectively brings the frame to the front.

Children and layered regions. See the Region documentation for details about parent-child relationships. Note that, when reading from a layout file, LayeredRegions are parsed before children Frames. Therefore, a LayeredRegion cannot specify an anchor to a child in the layout file. Likewise, children are parsed in order of declaration; a child may only anchor to another child if that other child was declared first. This type of anchor must be set programmatically, for example in the OnLoad event of the parent frame. This does not affect regions created in C++ or Lua, only regions defined in layout files.

Events. Frames can react to events. For this to happen, a callback function must be registered to handle the corresponding event. There are two types of events. First: hard-coded UI events such as OnKeyPress or OnUpdate, which are automatically triggered by lxgui. Second: generic events, which can be triggered from various sources and all forwarded to the OnEvent callback. Generic events are typically generated by whatever application is being driven by lxgui (i.e., your game), and they enable application-specific behavior (for example: changing the UI when the player is under attack will likely require an "UNDER_ATTACK" event).

To use the first type of events (hard-coded events), all you have to do in general is register a callback function using Frame:add_script or Frame:set_script. However, some hard-coded events require explicit enabling. In particular:

To use the second type of events (generic events), you have to register a callback for OnEvent and register the frame for each generic event you wish to listen to. This is done with Frame:register_event.

Some events provide arguments to the registered callback function. For example, the application can fire a "UNIT_ATTACKED" event when a unit is under attack, and pass the ID of the attacked unit as a first argument, and the ID of the attacker as a second argument. If a callback function is registered using Frame:add_script or Frame:set_script, these arguments can be handled and named like regular function parameters. In layout files "scripts" handlers, they can be accessed with the hard-coded generic names arg1, arg2, etc.

Hard-coded events available to all Frames:

  • OnChar: Triggered whenever a character is typed and the frame has focus (see Frame:set_focus).
  • OnDoubleClick: Triggered when the frame is double-clicked.
  • OnDragStart: Triggered when one of the mouse button registered for dragging (see frame::enable_drag) has been pressed inside the area of the screen occupied by the frame, and a mouse movement is first recorded. This event provides four argument to the registered callback: a number identifying the mouse button that started the drag, the human-readable name of this button, and the mouse X and Y position.
  • OnDragMove: Triggered after OnDragStart, each time the mouse moves, until OnDragStop is triggered. This event provides four argument to the registered callback: the amount of mouse movement in X and Y since the last call to OnDragMove (or since OnDragStart if this is the first call), and the mouse X and Y position.
  • OnDragStop: Similar to OnDragStart, but triggered when the mouse button is released after OnDragStart.
  • OnEnter: Triggered when the mouse pointer enters into the area of the screen occupied by the frame. Note: this only takes into account the position and size of the frame and its title region, but not the space occupied by its children or layered regions. Will not trigger if the frame is hidden.
  • OnEvent: Triggered when a registered generic event occurs. See Frame:register_event. To allow distinguishing which event has just been fired, the registered callback function is always provided with a first argument that is set to a string matching the event name. Further arguments can be passed to the callback and are handled as for other events.
  • OnFocusGained: Triggered when the frame gains focus, see Frame:set_focus.
  • OnFocusLost: Triggered when the frame looses focus, see Frame:set_focus.
  • OnHide: Triggered when Region:hide is called, or when the frame is hidden indirectly (for example if its parent is itself hidden). This will only fire if the frame was previously shown.
  • OnKeyDown: Triggered when a keyboard key is pressed. Will only trigger if the frame is shown and either has focus (see Frame:set_focus) or if the key has been registered for capture using Frame:enable_key_capture. If no keyboard-enabled frame is focused, only the topmost frame with Frame:enable_key_capture will receive the event. If no frame has captured the key, then the key is tested for existing key bindings (see GUI.register_key_binding). This event provides five arguments to the registered callback: a number identifying the main key being pressed, three boolean flags for "Shift", "Ctrl", and "Alt, and finally the human-readable name of the key combination being pressed (e.g., "Shift+A").
  • OnKeyRepeat: Similar to OnKeyDown, but triggered when a key has been long-pressed and the operating system generated repeat events.
  • OnKeyUp: Similar to OnKeyDown, but triggered when a keyboard key is released.
  • OnLeave: Triggered when the mouse pointer leaves the area of the screen occupied by the frame. Note: this only takes into account the position and size of the frame and its title region, but not the space occupied by its children or layered regions. Will not trigger if the frame is hidden, unless the frame was just hidden with the mouse previously inside the frame. Finally, this will trigger whenever the mouse enters another mouse-enabled frame with a higher level/strata, even if the mouse is still technically within this frame's region.
  • OnLoad: Triggered just after the frame is created. This is where you would normally register for events and specific inputs, set up initial states for extra logic, or do localization.
  • OnMouseDown: Triggered when a mouse button is pressed and this frame is the topmost mouse-click-enabled frame under the mouse pointer. Will not trigger if the frame is hidden. This event provides four arguments to the registered callback: a number identifying the mouse button, a string containing the human-readable name of this button ("LeftButton", "RightButton", or "MiddleButton"), and the mouse X and Y position.
  • OnMouseMove: Triggered when the mouse moves over this frame, after OnEnter and until OnLeave. This event provides four argument to the registered callback: the amount of mouse movement in X and Y since the last call to OnMouseMove (or since the last position before the mouse entered this frame), and the mouse X and Y position.
  • OnMouseUp: Similar to OnMouseDown, but triggered when the mouse button is released. This event provides two extra argument compared to OnMouseDown: a boolean flag indicating whether the mouse was released after a drag operation (true) or not (false), and another boolean flag indicating whether the mouse button was initially pressed on this frame (true) or not (false).
  • OnMouseWheel: Triggered when the mouse wheel is moved and this frame is the topmost mouse-wheel-enabled frame under the mouse pointer. This event provides three arguments to the registered callback. The first is a number indicating by how many "notches" the wheel has turned in this event. A positive value means the wheel has been moved "away" from the user (this would normally scroll up in a document). The other two arguments are the mouse X and Y position.
  • OnMouseWheel: Triggered when the mouse wheel is moved and this frame is the topmost mouse-wheel-enabled frame under the mouse pointer. Will not trigger if the frame is hidden. This event provides one argument to the registered callback: a number indicating by how many "notches" the wheel has turned in this event. A positive value means the wheel has been moved "away" from the user (this would normally scroll up in a document).
  • OnReceiveDrag: Triggered when the mouse pointer was previously dragged onto the frame, and when one of the mouse button registered for dragging (see Frame:enable_drag) is released. This enables the "drop" in "drag and drop" operations.
  • OnShow: Triggered when Region:show is called, or when the frame is shown indirectly (for example if its parent is itself shown). This will only fire if the frame was previously hidden.
  • OnSizeChanged: Triggered whenever the size of the frame changes, either directly or indirectly. Be very careful not to call any function that could change the size of the frame inside this callback, as this would generate an infinite loop.
  • OnUpdate: Triggered on every tick of the game loop, if the frame is shown. This event provides one argument to the registered callback: a floating point number indicating how much time has passed since the last call to OnUpdate (in seconds). For optimal performance, prefer using other events types whenever possible. OnUpdate callbacks will be executed over and over again, and can quickly consume a lot of resources if user unreasonably. If you have to use OnUpdate, you can mitigate performance problems by reducing the update rate using Frame:set_update_rate.

Generic events fired natively by lxgui:

  • "LUA_ERROR": Triggered whenever a callback function or an addon script file generates a Lua error. This event provides one argument to the registered callback: a string containing the error message.
  • "ADDON_LOADED": Triggered when an addon is fully loaded. This event provides one argument to the registered callback: a string containing the name of the loaded addon.
  • "ENTERING_WORLD": Triggered once at the start of the program, at the end of the first update tick.

Virtual frames. Virtual frames are not displayed on the screen, and technically are not part of the interface. They are only available as "templates" that can be reused by other (virtual or non-virtual) frames. This is useful for defining a few frame templates with a particular style, and then reuse these templates across the interface to ensure a consistent look. When inheriting from a virtual frame, the inheriting frame will copy all the registered callbacks, all the child frames, and all the layered regions of the virtual frame.

This inheritance mechanism can be chained: a virtual frame itself can inherit from another virtual frame. It is also possible to inherit from multiple virtual frames at once, which will copy their respective content in the order they are specified.

Inherits all methods from: Region.

Child classes: Button, CheckButton, EditBox, ScrollFrame, Slider, StatusBar.

Methods

frame:add_script()
frame:clear_focus()
frame:create_font_string()
frame:create_texture()
frame:create_title_region()
frame:disable_drag()
frame:disable_draw_layer()
frame:disable_key_capture()
frame:disable_keyboard()
frame:disable_mouse()
frame:disable_mouse_click()
frame:disable_mouse_move()
frame:disable_mouse_wheel()
frame:enable_drag()
frame:enable_draw_layer()
frame:enable_key_capture()
frame:enable_keyboard()
frame:enable_mouse()
frame:enable_mouse_click()
frame:enable_mouse_move()
frame:enable_mouse_wheel()
frame:get_backdrop()
frame:get_backdrop_border_color()
frame:get_backdrop_color()
frame:get_children()
frame:get_effective_alpha()
frame:get_effective_scale()
frame:get_level()
frame:get_strata()
frame:get_strata()
frame:get_hit_rect_insets()
frame:get_max_dimensions()
frame:get_min_dimensions()
frame:get_child_count()
frame:get_layered_region_count()
frame:get_scale()
frame:get_script()
frame:get_title_region()
frame:get_update_rate()
frame:has_script()
frame:is_auto_focus()
frame:is_clamped_to_screen()
frame:is_mouse_click_enabled()
frame:is_mouse_move_enabled()
frame:is_mouse_wheel_enabled()
frame:is_keyboard_enabled()
frame:is_key_capture_enabled()
frame:is_movable()
frame:is_resizable()
frame:is_top_level()
frame:is_user_placed()
frame:raise()
frame:register_event()
frame:set_auto_focus()
frame:set_backdrop()
frame:set_backdrop_border_color()
frame:set_backdrop_color()
frame:set_clamped_to_screen()
frame:set_drag_enabled()
frame:set_draw_layer_enabled()
frame:set_focus()
frame:set_keyboard_enabled()
frame:set_key_capture_enabled()
frame:set_level()
frame:set_mouse_wheel_enabled()
frame:set_mouse_enabled()
frame:set_mouse_click_enabled()
frame:set_mouse_move_enabled()
frame:set_strata()
frame:set_hit_rect_insets()
frame:set_max_dimensions()
frame:set_min_dimensions()
frame:set_max_width()
frame:set_max_height()
frame:set_min_width()
frame:set_min_height()
frame:set_movable()
frame:set_resizable()
frame:set_scale()
frame:set_script()
frame:set_top_level()
frame:set_update_rate()
frame:set_user_placed()
frame:start_moving()
frame:start_sizing()
frame:stop_moving_or_sizing()
frame:unregister_event()


Methods

frame:add_script()
frame:clear_focus()
frame:create_font_string()
frame:create_texture()
frame:create_title_region()
frame:disable_drag()
frame:disable_draw_layer()
frame:disable_key_capture()
frame:disable_keyboard()
frame:disable_mouse()
frame:disable_mouse_click()
frame:disable_mouse_move()
frame:disable_mouse_wheel()
frame:enable_drag()
frame:enable_draw_layer()
frame:enable_key_capture()
frame:enable_keyboard()
frame:enable_mouse()
frame:enable_mouse_click()
frame:enable_mouse_move()
frame:enable_mouse_wheel()
frame:get_backdrop()
frame:get_backdrop_border_color()
frame:get_backdrop_color()
frame:get_children()
frame:get_effective_alpha()
frame:get_effective_scale()
frame:get_level()
frame:get_strata()
frame:get_strata()
frame:get_hit_rect_insets()
frame:get_max_dimensions()
frame:get_min_dimensions()
frame:get_child_count()
frame:get_layered_region_count()
frame:get_scale()
frame:get_script()
frame:get_title_region()
frame:get_update_rate()
frame:has_script()
frame:is_auto_focus()
frame:is_clamped_to_screen()
frame:is_mouse_click_enabled()
frame:is_mouse_move_enabled()
frame:is_mouse_wheel_enabled()
frame:is_keyboard_enabled()
frame:is_key_capture_enabled()
frame:is_movable()
frame:is_resizable()
frame:is_top_level()
frame:is_user_placed()
frame:raise()
frame:register_event()
frame:set_auto_focus()
frame:set_backdrop()
frame:set_backdrop_border_color()
frame:set_backdrop_color()
frame:set_clamped_to_screen()
frame:set_drag_enabled()
frame:set_draw_layer_enabled()
frame:set_focus()
frame:set_keyboard_enabled()
frame:set_key_capture_enabled()
frame:set_level()
frame:set_mouse_wheel_enabled()
frame:set_mouse_enabled()
frame:set_mouse_click_enabled()
frame:set_mouse_move_enabled()
frame:set_strata()
frame:set_hit_rect_insets()
frame:set_max_dimensions()
frame:set_min_dimensions()
frame:set_max_width()
frame:set_max_height()
frame:set_min_width()
frame:set_min_height()
frame:set_movable()
frame:set_resizable()
frame:set_scale()
frame:set_script()
frame:set_top_level()
frame:set_update_rate()
frame:set_user_placed()
frame:start_moving()
frame:start_sizing()
frame:stop_moving_or_sizing()
frame:unregister_event()
generated by LDoc 1.5.0 Last updated 2023-10-08 09:07:54