eg-overlay-ui

local ui = require 'eg-overlay-ui'

Top Level Elements

• Windows

Layout Containers

• Box Layouts
• Grid Layouts

UI Elements

• Text Elements
• Buttons
• Scrollview Container
• Separator Element
• Text Entry Elements
• Menus
• Images

Colors

All colors in EG-Overlay are represented by 32bit integers in RGBA format. This may sound complicated, but it is actually incredibly convenient for module authors as colors can be specified in hex format, similar to CSS. For example, red at 100% opacity is 0xFF0000FF, green is 0x00FF00FF, and blue is 0x0000FFFF.

Fonts

Important

EG-Overlay uses FreeType2 to render glyphs onscreen. This means that any font that FreeType2 supports can be used, however module authors are encouraged to use the fonts configured in the overlay settings.

Due to the rendering and caching system, fonts are not directly exposed to Lua. Instead, all UI elements that use fonts take the following arguments on creation:

• Font path

• Font size

• Font weight

• Font slant

• Font width

The font path is the path to the actual font file. This can be a static/single font file or a variable font containing multiple styles. If a font does not support the given style parameters (weight, slant, width) they will be ignored. If style parameters are omitted, defaults will be used.

Implementation Detail

Fonts are rendered using a textured quad for each glyph. To attain useable performance, glyphs are pre-rendered to a texture array that is then used to render glyphs each frame.

Unlike many other UI frameworks, this pre-rendering is not static. Each font face, size, weight, slant, and width combination has a 512x512xN texture array, where N is a variable number of layers that are created as needed. When a unique font combination is requested a texture array with a single layer is created and pre-rendered with the standard ASCII glyphs.

Additional glyphs are pre-rendered the first time they are requested. This means that the UI may suffer a performance hit on the first frame a new glyph is rendered, but all subsequent frames should be unaffected.

UI Events

Most UI elements can send events to event handlers in Lua. Such elements implement addeventhandler and removeeventhandler methods. Some elements do not emit events by default and need to be enabled using an events method.

Event handler functions are passed a single argument, a string describing the event:

Value	Description
btn-down-left	Mouse button 1 (left) pressed.
btn-down-right	Mouse button 2 (right) pressed.
btn-down-middle	Mouse button 3 (middle) pressed.
btn-down-x1	Mouse button 4 pressed.
btn-down-x2	Mouse button 5 pressed.
btn-down-unk	An unknown mouse button is pressed.
btn-up-left	Mouse button 1 (left) released.
btn-up-right	Mouse button 2 (right) released.
btn-up-middle	Mouse button 3 (middle) released.
btn-up-x1	Mouse button 4 released.
btn-up-x2	Mouse button 5 released.
btn-up-unk	An unknown mouse button is released.
move	Mouse cursor moved (over the element).
wheel-up	Mouse wheel scrolled up.
wheel-down	Mouse wheel scrolled down.
wheel-left	Mouse wheel scrolled left.
wheel-right	Mouse wheel scrolled right.
enter	Mouse cursor entered the element area.
leave	Mouse cursor left the element area.
focus	Element now has focus (keyboard input).
unfocus	Element no longer has focus.

Note

Elements may send additional events not listed here.

Important

Events are sent to Lua like any other event, asynchronously. This means that there may be some delay between an event occurring and the event handler being called in Lua. However, events still should arrive in the same order that they occurred.

Core UI

class eg-overlay-ui.uielement

This is not an actual class accessible from Lua, but represents any UI Element.

Version History

Version	Notes
0.0.1	Added

eg-overlay-ui.addtoplevelelement(uielement)

Add an element to the list of top level elements. Top level elements are the only elements drawn automatically.

Note

Normally only windows are top level elements, however any UI element can be specified here to have it drawn independently of a window.

If uielement is already a top level element this function has no effect.

Parameters:

uielement – The UI element to draw.

Version History

Version	Notes
0.0.1	Added
0.1.0	Renamed from add_top_level_element to addtoplevelelement

eg-overlay-ui.removetoplevelelement(uielement)

Remove a top level element previously added with addtoplevelelement().

Parameters:

uielement – The UI element to hide.

Version History

Version	Notes
0.0.1	Added
0.1.0	Renamed from remove_top_level_element to removetoplevelelement

eg-overlay-ui.mouseposition()

Returns the x,y coordinates of the mouse cursor. These coordinates are relative to the overlay’s client rectangle, i.e. 0,0 is the top left.

Returns:

X,Y

Return type:

integer

Example

local x,y = ui.mouse_position()

Version History

Version	Notes
0.0.1	Added
0.1.0	Renamed from mouse_position to mouseposition

eg-overlay-ui.mousebuttonstate()

Returns the state of the left, middle, and right mouse buttons.

This function returns 3 boolean values, indicating if the left, middle, and right mouse button are pressed (true) or not (false).

Return type:

boolean

Version History

Version	Notes
0.1.0	Added