Skip to content
Download

UI kit and theme tokens (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 25 functions, the newest from API 1.24.

Explanations and examples: The UI kit, Theme tokens, Appearance pages. Every function of the ui module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function Lua Side Context Since
cl_ui_fancy cl.ui.fancy client ANY 1.21
cl_ui_hud_fancy cl.ui.hud_fancy client ANY 1.21
cl_ui_theme cl.ui.theme client ANY 1.21
cl_ui_color cl.ui.color client ANY 1.21
cl_ui_length cl.ui.length client ANY 1.21
cl_ui_text_width cl.ui.text_width client ANY 1.21
cl_ui_line_height cl.ui.line_height client ANY 1.21
cl_ui_generation cl.ui.generation client ANY 1.21
cl_ui_has_icon cl.ui.has_icon client ANY 1.21
cl_ui_page_register cl.ui.page_register client ANY 1.21
cl_ui_page_remove cl.ui.page_remove client ANY 1.21
cl_ui_page_group cl.ui.page_group client ANY 1.21
cl_ui_page_note cl.ui.page_note client ANY 1.21
cl_ui_page_option cl.ui.page_option client ANY 1.21
cl_ui_page_choice cl.ui.page_choice client ANY 1.21
cl_ui_page_color cl.ui.page_color client ANY 1.21
cl_ui_page_button cl.ui.page_button client ANY 1.21
cl_ui_page_hud_element cl.ui.page_hud_element client ANY 1.21
cl_ui_page_open cl.ui.page_open client ANY 1.21
cl_ui_feature_register cl.ui.feature_register client ANY 1.23
cl_ui_feature_remove cl.ui.feature_remove client ANY 1.23
cl_ui_ease cl.ui.ease client ANY 1.24
cl_ui_anim_step cl.ui.anim_step client ANY 1.24
cl_ui_anim_enabled cl.ui.anim_enabled client ANY 1.24
cl_ui_anim_duration cl.ui.anim_duration client ANY 1.24

cl_ui_fancy

bool cl_ui_fancy(void);

True while the calling mod’s screens draw in the Fancy style (the player’s global style, or the override of Appearance > Menus > Mod screens). Use it only for your own drawing: kit widgets switch by themselves.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.fancy
  • C++: clight::ui::fancy() → bool

cl_ui_hud_fancy

bool cl_ui_hud_fancy(void);

True while the HUD draws in the Fancy style.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.hud_fancy
  • C++: clight::ui::hud_fancy() → bool

cl_ui_theme

cl_result cl_ui_theme(char* buf, size_t cap, size_t* out_len);

The theme in use: a preset id (“night”, “aurora”, …) or a custom “CT2-…” code.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.theme
  • C++: clight::ui::theme() → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_color

cl_color cl_ui_color(cl_str name);

A colour token of the current theme by name (“panel”, “on_surface”, “on_surface_2”, “accent”, “control”, “control_hover”, “hud_panel”, “danger”, “warn”, “ok”, …). 0 for an unknown name.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.color
  • C++: clight::ui::color(std::string_view name) → cl_color

cl_ui_length

float cl_ui_length(cl_str name);

A length token in design px (1 design px = 1/4 GUI px): “radius.ctl”, “radius.box”, “space.4”, “button_h”, … 0 if unknown.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.length
  • C++: clight::ui::length(std::string_view name) → float

cl_ui_text_width

float cl_ui_text_width(cl_str s, cl_ui_text style);

The width of text in a kit style, in GUI px at the current GUI scale (the font the current style uses).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.text_width
  • C++: clight::ui::text_width(std::string_view s, cl_ui_text style) → float

cl_ui_line_height

float cl_ui_line_height(cl_ui_text style);

The line height of a kit style in GUI px.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.line_height
  • C++: clight::ui::line_height(cl_ui_text style) → float

cl_ui_generation

uint32_t cl_ui_generation(void);

Changes whenever the style, the theme or a token changes (a cache key for your own cached drawing).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.generation
  • C++: clight::ui::generation() → uint32_t

cl_ui_has_icon

bool cl_ui_has_icon(cl_str name);

True when the icon set has the icon (“search”, “folder”, “settings”, … the names in Mod_Docs 41_Theme_Tokens).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.has_icon
  • C++: clight::ui::has_icon(std::string_view name) → bool

cl_ui_page_register

cl_result cl_ui_page_register(const cl_ui_page_desc* desc, cl_ui_page* out);
  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_register
  • C++: clight::ui::page_register(const cl_ui_page_desc* desc) → Expected<UiPage>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_remove

cl_result cl_ui_page_remove(cl_ui_page page);
  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_remove, ui_page:remove(...)
  • C++: UiPage::remove() → Expected<void>; clight::ui::page_remove(UiPage page) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_group

cl_result cl_ui_page_group(cl_ui_page page, cl_str label);

A group heading.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_group, ui_page:group(...)
  • C++: UiPage::group(std::string_view label) → Expected<void>; clight::ui::page_group(UiPage page, std::string_view label) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_note

cl_result cl_ui_page_note(cl_ui_page page, cl_str text);

A line of text.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_note, ui_page:note(...)
  • C++: UiPage::note(std::string_view text) → Expected<void>; clight::ui::page_note(UiPage page, std::string_view text) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_option

cl_result cl_ui_page_option(cl_ui_page page, cl_str config_path, cl_str label, cl_str description);

A row bound to an option of the mod’s client config (cl_config_define_*): a toggle (bool), a slider (number with a range) or a text field. The value is saved in the config file and the mod gets config.reloaded.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_option, ui_page:option(...)
  • C++: UiPage::option(std::string_view config_path, std::string_view label, std::string_view description) → Expected<void>; clight::ui::page_option(UiPage page, std::string_view config_path, std::string_view label, std::string_view description) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_choice

cl_result cl_ui_page_choice(cl_ui_page page, cl_str config_path, cl_str label, cl_str description, cl_str choices);

A text option shown as a choice (choices one per line; the stored value is the choice text).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_choice, ui_page:choice(...)
  • C++: UiPage::choice(std::string_view config_path, std::string_view label, std::string_view description, std::string_view choices) → Expected<void>; clight::ui::page_choice(UiPage page, std::string_view config_path, std::string_view label, std::string_view description, std::string_view choices) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_color

cl_result cl_ui_page_color(cl_ui_page page, cl_str config_path, cl_str label, cl_str description);

A colour option (a text option holding “#RRGGBB”): a swatch with a picker.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_color, ui_page:color(...)
  • C++: UiPage::color(std::string_view config_path, std::string_view label, std::string_view description) → Expected<void>; clight::ui::page_color(UiPage page, std::string_view config_path, std::string_view label, std::string_view description) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_button

cl_result cl_ui_page_button(cl_ui_page page, cl_str key, cl_str label, cl_str description, cl_str button);

A row with a button; pressing it calls on_change(page, key).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_button, ui_page:button(...)
  • C++: UiPage::button(std::string_view key, std::string_view label, std::string_view description, std::string_view button) → Expected<void>; clight::ui::page_button(UiPage page, std::string_view key, std::string_view label, std::string_view description, std::string_view button) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_hud_element

cl_result cl_ui_page_hud_element(cl_ui_page page, cl_hud_element element);

The rows of one of the mod’s HUD elements (show, style, scale) and a button to the HUD editor.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_hud_element, ui_page:hud_element(...)
  • C++: UiPage::hud_element(HudElement element) → Expected<void>; clight::ui::page_hud_element(UiPage page, HudElement element) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_page_open

cl_result cl_ui_page_open(cl_ui_page page);

Opens Appearance at the page.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.ui.page_open, ui_page:open(...)
  • C++: UiPage::open() → Expected<void>; clight::ui::page_open(UiPage page) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_feature_register

cl_result cl_ui_feature_register(const cl_ui_feature_desc* desc, cl_ui_feature* out);
  • Side: client. Context: ANY (any thread). Since: API 1.23.
  • Lua: cl.ui.feature_register
  • C++: clight::ui::feature_register(const cl_ui_feature_desc* desc) → Expected<UiFeature>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_feature_remove

cl_result cl_ui_feature_remove(cl_ui_feature feature);
  • Side: client. Context: ANY (any thread). Since: API 1.23.
  • Lua: cl.ui.feature_remove, ui_feature:remove(...)
  • C++: UiFeature::remove() → Expected<void>; clight::ui::feature_remove(UiFeature feature) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ui_ease

float cl_ui_ease(cl_ui_easing kind, float t);

t (0…1, clamped) through an easing curve.

  • Side: client. Context: ANY (any thread). Since: API 1.24.
  • Lua: cl.ui.ease
  • C++: clight::ui::ease(cl_ui_easing kind, float t) → float

cl_ui_anim_step

float cl_ui_anim_step(float p, bool show, float dt, float in_seconds, float out_seconds);

Moves an appear / disappear progress p (0 hidden … 1 shown) towards shown (show = true) or hidden by dt seconds; in_seconds / out_seconds are the full durations (0 = instant). Frame-rate independent; turning round mid-way continues from where it is. Draw with ui_ease(kind, p) as the opacity, offset or scale.

  • Side: client. Context: ANY (any thread). Since: API 1.24.
  • Lua: cl.ui.anim_step
  • C++: clight::ui::anim_step(float p, bool show, float dt, float in_seconds, float out_seconds) → float

cl_ui_anim_enabled

bool cl_ui_anim_enabled(void);

True when the player turned Animations on (and Reduce Motion is off). Animate your HUD elements and screens only then; otherwise show and hide them at once.

  • Side: client. Context: ANY (any thread). Since: API 1.24.
  • Lua: cl.ui.anim_enabled
  • C++: clight::ui::anim_enabled() → bool

cl_ui_anim_duration

float cl_ui_anim_duration(bool menus);

The player’s animation duration in seconds: the HUD’s (menus = false) or the menus’ (true).

  • Side: client. Context: ANY (any thread). Since: API 1.24.
  • Lua: cl.ui.anim_duration
  • C++: clight::ui::anim_duration(bool menus) → float