All pages
Powered by GitBook
1 of 27

Gui

Usage:

gui.{func_or_field}

Usage: gui.{func_or_field}

This table exposes the GUI system of the software.

All types and enums described in the child sections must be prefixed with gui..

ctx

Type: context

GUI context.

notify

Type: notification_system

Notification system.

input

Type: context_input

Input context.

make_control

Wraps a control into a layout consisting of a label and that specific control. You should add this new control to groupboxes if you want your control to be displayed nicely. Additionally, you can add any extra controls to the returned one - those will get stacked to the left side of your initial control.

Arguments

Name

Type

Description

text

string

Label value.

c

control

Control object.

Returns

Type

Description

layout

Layout object.

Example

local row = gui.make_control('Hello checkbox!', my_cb);

Types

In this section, the most common gui types are listed, that are not particularly bound to a specific part of the gui.

Use the left menu (or hamburger menu, if you are on mobile) to navigate between types.

bits

This type represents a bitset value.

Maximal bit number for this type is 63. Setting or getting any bits outside of that range will cause a crash.

reset

Resets the value.

Arguments

None.

Returns

Nothing.

Example

bits:reset();

get_raw

Returns the raw value.

Arguments

None.

Returns

Type

Description

int

Raw value.

Example

local raw = bits:get_raw();

set_raw

Sets the raw value.

Arguments

Name

Type

Description

val

int

Raw value.

Returns

Nothing.

Example

bits:set_raw(long_long_value);

none

Returns true if no bits are set.

Arguments

None.

Returns

Type

Description

bool

true if no bits are set.

Example

if bits:none() then
    -- ...
end

set

Enables a bit.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:set(5); -- set bit #5 (same as bit.bor(val, bit.lshift(1, 5)))

unset

Disables a bit.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:unset(5);

get

Returns bit state.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Type

Description

bool

Bit status.

Example

if bits:get(5) then
    -- ...
end

toggle

Toggles bit state.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:toggle(5);

control_id

This type represents a control ID.

__call

Constructs the ID structure.

Arguments

Name

Type

Description

id

string

ID.

Returns

Type

Description

control_id

ID structure.

Example

local id = gui.control_id('my_id');

id

Type: int

Hashed representation of the ID.

id_string

Type: string

Normal representation of the ID.

context

This type represents the GUI context.

find

Finds a control by ID.

Arguments

Name

Type

Description

id

string

Control ID.

Returns

Type

Description

<control>?

Casted control. Returns nil if the control was not found, or casting failed.

Example

local some_cb = ctx:find('some_cb');

user

Field

Type: user_t

User's basic information.

user_t

This type represents basic user information.

avatar

Type: texture?

User's avatar. May be nil.

username

Type: string

User's username.

context_input

This type represents the GUI input context.

You can use cursor, is_mouse_up, is_mouse_down, is_key_up and is_key_down methods outside input context. Using other methods will not make any sense, as the information will be outdated.

cursor

Returns current cursor position.

Arguments

None.

Returns

Type

Description

vec2

Cursor position.

Example

local cur = gui.input:cursor();

cursor_prev

Returns previous cursor position.

Arguments

None.

Returns

Type

Description

vec2

Previous cursor position.

Example

local prev = gui.input:cursor_prev();

cursor_delta

Delta value between previous and current cursor positions.

Arguments

None.

Returns

Type

Description

vec2

Cursor delta.

Example

local delta = gui.input:cursor_delta();

did_cursor_move

Returns true if the cursor did move since the last input.

Arguments

None.

Returns

Type

Description

bool

true if moved.

Example

if gui.input:did_cursor_move() then
    -- ...
end

did_wheel_move

Returns true if mouse scroll wheel did move since the last input.

Arguments

None.

Returns

Type

Description

bool

true if moved.

Example

if gui.input:did_wheel_move() then
    -- ...
end

did_process_mouse

Returns true if any mouse key's state had changed.

Arguments

None.

Returns

Type

Description

bool

true if processed.

Example

if gui.input:did_process_mouse() then
    -- ...
end

button_released

Returns true if any key was released since the last input.

Arguments

None.

Returns

Type

Description

bool

true if released.

Example

if gui.input:button_released() then
    -- ...
end

wheel_delta

Returns the amount of rows scrolled this input.

Arguments

None.

Returns

Type

Description

float

Rows scrolled.

Example

local scroll = gui.input:wheel_delta();

is_mouse_up

Returns true if the mouse key is up (depressed).

Arguments

Name

Type

Description

mb

mouse_button

Mouse button.

Returns

Type

Description

bool

true if depressed.

Example

if gui.input:is_mouse_up(gui.mouse_button.left) then
    -- ...
end

is_mouse_down

Returns true if the mouse key is down (pressed).

Arguments

Name

Type

Description

mb

mouse_button

Mouse button.

Returns

Type

Description

bool

true if pressed.

Example

if gui.input:is_mouse_down(gui.mouse_button.left) then
    -- ...
end

is_mouse_clicked

Returns true if the mouse key is clicked (switched from depressed to pressed state).

Arguments

Name

Type

Description

mb

mouse_button

Mouse button.

Returns

Type

Description

bool

true if clicked.

Example

if gui.input:is_mouse_clicked(gui.mouse_button.left) then
    -- ...
end

is_mouse_released

Returns true if the mouse key is released (switched from pressed to depressed state).

Arguments

Name

Type

Description

mb

mouse_button

Mouse button.

Returns

Type

Description

bool

true if released.

Example

if gui.input:is_mouse_released(gui.mouse_button.left) then
    -- ...
end

did_process_key

Returns true if any key's state had changed.

Arguments

None.

Returns

Type

Description

bool

true if state changed.

Example

if gui.input:did_process_key() then
    -- ...
end

is_key_up

Returns true if a key is up (depressed).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if depressed.

Example

if gui.input:is_key_up(0x41) then -- 0x41 = "A"
    -- ...
end

is_key_down

Returns true if a key is down (pressed).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if pressed.

Example

if gui.input:is_key_down(0x41) then -- 0x41 = "A"
    -- ...
end

is_key_clicked

Returns true if a key is clicked (switched from depressed to pressed state).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if clicked.

Example

if gui.input:is_key_clicked(0x41) then -- 0x41 = "A"
    -- ...
end

is_key_released

Returns true if a key is released (switched from pressed to depressed state).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if released.

Example

if gui.input:is_key_released(0x41) then -- 0x41 = "A"
    -- ...
end

mouse_button

This enum represents mouse buttons.

left

Left mouse button.

right

Right mouse button.

middle

Middle (scroll wheel) mouse button

back

"Back" mouse button (side button 1).

forward

"Forward" mouse button (side button 2).

notification_system

This type represents a notification system.

add

Adds a notification to the list.

Arguments

Name

Type

Description

notif

notification

Notification object.

Returns

Nothing.

Example

notif:add(my_notification);

notification

This type represents a notification item.

__call

Constructs the notification.

Arguments

Name

Type

Description

hdr

string

Header (title).

txt

string

Text (body).

ico

texture?

Icon. Defaults to nil.

Returns

Type

Description

notification

Notification object.

Example

local notif = gui.notification('Hello', 'Lua works!');

control

This type represents an abstract GUI control.

id

Type: int

Control ID.

id_string

Type: string

String representation of control's ID. This may be empty for some controls.

is_visible

Type: bool

Control's visibility state.

parent

Type: control?

Parent control. Might be nil on some controls.

type

Type: control_type

Control's type.

inactive

Type: bool

If set to true, will mark this control to the inactive state.

inactive_text

Type: string

Tooltip replacement to show when control is inactive.

inactive_color

Type: color

Label color override for inactive controls.

tooltip

Type: string

Tooltip text.

aliases

Type: table[string]

Alias list for this control. Used in search box to support different naming (e.g. if a user searches for "Double tap", will find "Rapid fire" instead).

get_hotkey_state

Returns true if any of the control's hotkeys are active.

Arguments

None.

Returns

Type

Description

bool

true if any hotkey is active.

Example

if ctrl:get_hotkey_state() then
    -- ...
end

set_visible

Changes visibility state for this control.

Calling this method on controls that are located in layouts with large amount of other controls will inevitably cause performance issues due to auto-stacking.

Arguments

Name

Type

Description

val

bool

Visibility state.

Returns

Nothing.

Example

ctrl:set_visible(false);

add_callback

Adds a callback to this control.

Arguments

Name

Type

Description

cbk

function

Callback.

Returns

Nothing.

Example

ctrl:add_callback(function ()
    print('Callback invoked!');
end);

cast

Attempts to downcast the control to the correct type.

Due to Lua engine's limitations, it is impossible to automatically downcast variables. Usually there is no need to call this method, unless you found some control that wasn't somehow already cast to the desired type. find() methods automatically perform the cast to the correct type.

Arguments

None.

Returns

Type

Description

<control>

New type, if any.

Example

local checkbox = maybe_checkbox:cast();

reset

Resets control's state. This action is usually required if you change control's value directly by interacting with value_param.

You also should call this method on layouts if you add multiple controls into them.

Arguments

None.

Returns

Nothing.

Example

ctrl:reset();

control_type

This enum determines the current control's type.

You can only construct types that are listed below in the navigation, and only if those have a constructor.

default

Default control. You are very unlikely to ever stumble upon this type.

button

Button control.

checkbox

Checkbox control.

child_tab

Child tab control. Only possible to find within tab_layout controls.

color_picker

Color picker control.

combo_box

Combo box control.

control_container

Default control with a container. You are very unlikely to ever stumble upon this type.

group

Groupbox control.

hotkey

Hotkey input control.

hsv_slider

HSB slider (Saturation/Brightness box, Hue slider and Opacity slider).

label

Label control.

layout

Layout control.

list

Listbox control.

loading

Loading spinner.

notification_control

Notification item control. One of the types in the core UI framework, never actually used within Fatality.

popup

Basic popup window.

selectable

Basic selectable item.

slider

Slider item. This type doesn't tell the internal value type used.

spacer

Spacer control.

tab

Horizontal or vertical tab.

tabs_layout

A variant of layout that is used specifically to operate tabs.

weapon_tabs_layout

A variant of layout that is used specifically to operate weapon tabs.

text_input

Text input control.

toggle_button

A variant of button that looks like button, but works like a checkbox.

window

Basic window control.

widget

Basic widget control.

settings

Settings control.

image

Image control.

value_param

This type represents a value data used by some control types.

Note, that this part: <type> is used to designate what exact type the instance of this type is holding. For example, when it says value_param<bool>, it means that get will return a bool value, and set will accept only the type bool as it's val parameter.

get

Returns the value.

Arguments

None.

Returns

Type

Description

<type>

Value.

Example

ctrl:get_value():get();

get_direct

Returns the value disrgarding any active keybinds.

Arguments

None.

Returns

Type

Description

<type>

Value.

Example

ctrl:get_value():get_direct();

set

Sets the value.

It is advised to use set_value method of the control, if any.

Arguments

Name

Type

Description

val

<type>

Value.

Returns

Nothing.

Example

ctrl:get_value():set(123);

get_hotkey_state

Returns true if there's any active hotkeys.

Arguments

None.

Returns

Type

Description

bool

true if any hotkey is active.

Example

if ctrl:get_value():get_hotkey_state() then
    -- ...
end

disable_hotkeys

Disables all active hotkeys. This allows you to override the value.

Arguments

None.

Returns

Nothing.

Example

ctrl:get_value():disable_hotkeys();

checkbox

This type represents a checkbox control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the checkbox.

Arguments

Name

Type

Description

id

control_id

ID.

Returns

Type

Description

checkbox

Checkbox instance.

Example

local cb = gui.checkbox(gui.control_id('my_id'));

get_value

Returns checkbox' value.

Arguments

None.

Returns

Type

Description

value_param<bool>

Value data.

Example

local val = cb:get_value():get();

set_value

Sets checkbox' value.

It is advised to use this method instead of value_param's set method.

Arguments

Name

Type

Description

val

bool

New value.

Returns

Nothing.

Example

cb:set_value(true);

slider

This type represents a slider control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the slider.

Arguments

Name

Type

Description

id

control_id

Control ID.

low

float

Minimum value.

high

float

Maximum value.

fmt

table[...]

Format. Defaults to {'%.0f'}.

step

float

Step value. Defaults to 1.0.

Format Table

Format table can either be a single string with the desired format, or multiple elements with different minimum actuators. You have to pass multiple values in the descendant order, starting from the highest value to the lowest value. min and add values are both optional, but it makes no sense to leave either of them out.

Formatting uses standard printf syntax. Documentation

Passing invalid format will lead to an undefined behavior.

1. Single Formatting.

Type

Description

string

Format string.

2. Multi Formatting.

Name

Type

Description

min

float?

Minimal value.

add

float?

Add step.

fmt

string

Format string.

Returns

Type

Description

slider

Slider object.

Example

local slider = gui.slider(id, 0, 100, {'%.0f%%'});

get_value

Returns slider' value.

Arguments

None.

Returns

Type

Description

value_param<float>

Value data.

Example

local val = slider:get_value():get();

label

This type represents a label control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the label.

Arguments

Name

Type

Description

id

control_id

Control ID.

str

string

Label string.

col

color?

Label color. Defaults to nil.

bold

bool

Whether to use bold font. Defaults to false.

Returns

Type

Description

label

Label object.

Example

local lab = gui.label(id, 'Hello!');

set_text

Sets the new text.

Arguments

Name

Type

Description

str

string

New text.

Returns

Nothing.

Example

lab:set_text('New hello!');

selectable

This type represents a selectable control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the selectable.

Arguments

Name

Type

Description

id

control_id

Control ID.

str

string

Text string.

Returns

Type

Description

selectable

Selectable object.

Example

local sel = gui.selectable(id, 'Hello!');

button

This type represents a button control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the button.

Arguments

Name

Type

Description

id

control_id

Control ID.

str

string

Text string.

Returns

Type

Description

button

Button object.

Example

local btn = gui.button(id, 'Hello!');

color_picker

This type represents a color picker control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the color picker.

Arguments

Name

Type

Description

id

control_id

Control ID.

allow_alpha

bool

Whether to enable alpha channel. Defaults to true.

Returns

Type

Description

color_picker

Color picker object.

Example

local picker = gui.color_picker(id);

get_value

Returns color picker' value.

Arguments

None.

Returns

Type

Description

value_param<color>

Value data.

Example

local val = picker:get_value():get();

spacer

This type represents a spacer control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the spacer.

Arguments

Name

Type

Description

id

control_id

ID.

Returns

Type

Description

spacer

Spacer instance.

Example

local sp = gui.spacer(gui.control_id('my_id'));

text_input

This type represents a text input control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the text input.

Arguments

Name

Type

Description

id

control_id

ID.

Returns

Type

Description

text_input

Text input instance.

Example

local sp = gui.text_input(gui.control_id('my_id'));

placeholder

Type: string

Placeholder text.

value

Type: string

Value.

set_value

Sets the new text.

Arguments

Name

Type

Description

str

string

New value.

Returns

Nothing.

Example

input:set_value('Hello!');

combo_box

This type represents a combo box control.

This type inherits control_container type. All of its base methods and fields are also available in this type.

add method expects an instance of selectable. Passing other control types will not add them to the list.

Value bits are toggled in order of selectables. That means if the first element is toggled, so will be the first bit, etc.

__call

Constructs the combo box.

Arguments

Name

Type

Description

id

control_id

ID.

Returns

Type

Description

combo_box

Combo box instance.

Example

local cb = gui.combo_box(gui.control_id('my_id'));

allow_multiple

Type: bool

If set to true, the checkbox will be able to toggle multiple selectables.

get_value

Returns combo box' value.

Arguments

None.

Returns

Type

Description

value_param<bits>

Value data.

Example

local val = cb:get_value():get();

image

This type represents an image control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the image.

Arguments

Name

Type

Description

id

control_id

ID.

tex

texture

Texture.

Returns

Type

Description

image

Image instance.

Example

local img = gui.image(gui.control_id('my_id'));

container

This type represents an abstract container.

add

Adds a control to the container.

Arguments

Name

Type

Description

ctrl

control

Control to add.

Returns

Nothing.

Example

container:add(my_control);

remove

Removes a control from the container.

Arguments

Name

Type

Description

ctrl

control

Control to remove.

Returns

Nothing.

Example

container:remove(my_control);

find

Finds a control by ID.

Arguments

Name

Type

Description

id

string

Control ID.

Returns

Type

Description

<control>?

Casted control. Returns nil if the control was not found, or casting failed.

Example

local some_cb = container:find('some_cb');

control_container

This type represents an abstract control with a container.

This type inherits control type. All of its base methods and fields are also available in this type.

This type inherits container type. All of its base methods and fields are also available in this type.

layout

This type represents a layout control.

This type inherits control_container type. All of its base methods and fields are also available in this type.

group

This type represents a groupbox control.

This type inherits control_container type. All of its base methods and fields are also available in this type.