Skip to content
Download

Screens and widgets (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. 32 functions, the newest from API 1.23.

Explanations and examples: Screens and drawing. Every function of the screen 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_screen_open cl.screen.open client ANY 1.0
cl_screen_close cl.screen.close client ANY 1.0
cl_screen_is_open cl.screen.is_open client ANY 1.0
cl_screen_width cl.screen.width client ANY 1.0
cl_screen_height cl.screen.height client ANY 1.0
cl_widget_button cl.widget.button client ANY 1.0
cl_widget_checkbox cl.widget.checkbox client ANY 1.0
cl_widget_slider cl.widget.slider client ANY 1.0
cl_widget_text_field cl.widget.text_field client ANY 1.0
cl_widget_label cl.widget.label client ANY 1.0
cl_widget_remove cl.widget.remove client ANY 1.0
cl_widget_set_active cl.widget.set_active client ANY 1.0
cl_widget_set_visible cl.widget.set_visible client ANY 1.0
cl_widget_set_label cl.widget.set_label client ANY 1.0
cl_widget_set_tooltip cl.widget.set_tooltip client ANY 1.0
cl_widget_set_bounds cl.widget.set_bounds client ANY 1.0
cl_widget_value cl.widget.value client ANY 1.0
cl_widget_set_value cl.widget.set_value client ANY 1.0
cl_widget_text cl.widget.text client ANY 1.0
cl_widget_set_text cl.widget.set_text client ANY 1.0
cl_widget_toggle cl.widget.toggle client ANY 1.21
cl_widget_icon_button cl.widget.icon_button client ANY 1.21
cl_widget_dropdown cl.widget.dropdown client ANY 1.21
cl_widget_tabs cl.widget.tabs client ANY 1.21
cl_widget_list cl.widget.list client ANY 1.21
cl_widget_list_add cl.widget.list_add client ANY 1.21
cl_widget_list_clear cl.widget.list_clear client ANY 1.21
cl_widget_panel cl.widget.panel client ANY 1.21
cl_widget_card cl.widget.card client ANY 1.21
cl_widget_heading cl.widget.heading client ANY 1.21
cl_widget_color_picker cl.widget.color_picker client ANY 1.21
cl_widget_color_picker_alpha cl.widget.color_picker_alpha client ANY 1.23

cl_screen_open

cl_result cl_screen_open(const cl_screen_desc* desc, cl_screen* out);

Opens a custom screen (replacing the current one; the previous one is not kept).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.screen.open
  • C++: clight::screen::open(const cl_screen_desc* desc) → Expected<Screen>
  • 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_screen_close

cl_result cl_screen_close(cl_screen s);

Closes it if it is still the open screen (returns to the game, or the parent menu).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.screen.close, screen:close(...)
  • C++: Screen::close() → Expected<void>; clight::screen::close(Screen s) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_screen_is_open

bool cl_screen_is_open(cl_screen s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.screen.is_open, screen:is_open(...)
  • C++: Screen::is_open() → bool; clight::screen::is_open(Screen s) → bool

cl_screen_width

int32_t cl_screen_width(cl_screen s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.screen.width, screen:width(...)
  • C++: Screen::width() → int32_t; clight::screen::width(Screen s) → int32_t

cl_screen_height

int32_t cl_screen_height(cl_screen s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.screen.height, screen:height(...)
  • C++: Screen::height() → int32_t; clight::screen::height(Screen s) → int32_t

cl_widget_button

cl_result cl_widget_button(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str label, cl_widget_fn on_press, void* user, cl_widget* out);

Vanilla-look widgets owned by the screen (removed on re-init and close). Labels are literal text.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.button, screen:button(...), cl.screen.widget_button (old name)
  • C++: Screen::widget_button(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, cl_widget_fn on_press, void* user) → Expected<Widget>; clight::screen::widget_button(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, cl_widget_fn on_press, void* user) → Expected<Widget>
  • 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_widget_checkbox

cl_result cl_widget_checkbox(cl_screen s, int32_t x, int32_t y, cl_str label, bool checked, cl_widget_fn on_change, void* user, cl_widget* out);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.checkbox, screen:checkbox(...), cl.screen.widget_checkbox (old name)
  • C++: Screen::widget_checkbox(int32_t x, int32_t y, std::string_view label, bool checked, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_checkbox(Screen s, int32_t x, int32_t y, std::string_view label, bool checked, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_slider

cl_result cl_widget_slider(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str label, double min, double max, double value, double step, cl_widget_fn on_change, void* user, cl_widget* out);

value is clamped to min…max and snapped to step (0 = continuous); label is drawn as “label: value”.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.slider, screen:slider(...), cl.screen.widget_slider (old name)
  • C++: Screen::widget_slider(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, double min, double max, double value, double step, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_slider(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, double min, double max, double value, double step, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_text_field

cl_result cl_widget_text_field(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str hint, int32_t max_length, cl_widget_fn on_change, void* user, cl_widget* out);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.text_field, screen:text_field(...), cl.screen.widget_text_field (old name)
  • C++: Screen::widget_text_field(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view hint, int32_t max_length, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_text_field(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view hint, int32_t max_length, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_label

cl_result cl_widget_label(cl_screen s, int32_t x, int32_t y, cl_str label, cl_color argb, bool centered, cl_widget* out);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.label, screen:label(...), cl.screen.widget_label (old name)
  • C++: Screen::widget_label(int32_t x, int32_t y, std::string_view label, cl_color argb, bool centered) → Expected<Widget>; clight::screen::widget_label(Screen s, int32_t x, int32_t y, std::string_view label, cl_color argb, bool centered) → Expected<Widget>
  • 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_widget_remove

cl_result cl_widget_remove(cl_widget w);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.remove, widget:remove(...), cl.screen.widget_remove (old name)
  • C++: Widget::remove() → Expected<void>; clight::screen::widget_remove(Widget w) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_set_active

cl_result cl_widget_set_active(cl_widget w, bool active);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_active, widget:set_active(...), cl.screen.widget_set_active (old name)
  • C++: Widget::set_active(bool active) → Expected<void>; clight::screen::widget_set_active(Widget w, bool active) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_set_visible

cl_result cl_widget_set_visible(cl_widget w, bool visible);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_visible, widget:set_visible(...), cl.screen.widget_set_visible (old name)
  • C++: Widget::set_visible(bool visible) → Expected<void>; clight::screen::widget_set_visible(Widget w, bool visible) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_set_label

cl_result cl_widget_set_label(cl_widget w, cl_str label);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_label, widget:set_label(...), cl.screen.widget_set_label (old name)
  • C++: Widget::set_label(std::string_view label) → Expected<void>; clight::screen::widget_set_label(Widget w, std::string_view label) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_set_tooltip

cl_result cl_widget_set_tooltip(cl_widget w, cl_str tooltip);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_tooltip, widget:set_tooltip(...), cl.screen.widget_set_tooltip (old name)
  • C++: Widget::set_tooltip(std::string_view tooltip) → Expected<void>; clight::screen::widget_set_tooltip(Widget w, std::string_view tooltip) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_set_bounds

cl_result cl_widget_set_bounds(cl_widget w, int32_t x, int32_t y, int32_t w2, int32_t h);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_bounds, widget:set_bounds(...), cl.screen.widget_set_bounds (old name)
  • C++: Widget::set_bounds(int32_t x, int32_t y, int32_t w2, int32_t h) → Expected<void>; clight::screen::widget_set_bounds(Widget w, int32_t x, int32_t y, int32_t w2, int32_t h) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_value

double cl_widget_value(cl_widget w);

Slider value, checkbox (1/0).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.value, widget:value(...), cl.screen.widget_value (old name)
  • C++: Widget::value() → double; clight::screen::widget_value(Widget w) → double

cl_widget_set_value

cl_result cl_widget_set_value(cl_widget w, double v);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_value, widget:set_value(...), cl.screen.widget_set_value (old name)
  • C++: Widget::set_value(double v) → Expected<void>; clight::screen::widget_set_value(Widget w, double v) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_text

cl_result cl_widget_text(cl_widget w, char* buf, size_t cap, size_t* out_len);

Text field contents.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.text, widget:text(...), cl.screen.widget_text (old name)
  • C++: Widget::text() → Expected<std::string>; clight::screen::widget_text(Widget w) → 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_widget_set_text

cl_result cl_widget_set_text(cl_widget w, cl_str s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.widget.set_text, widget:set_text(...), cl.screen.widget_set_text (old name)
  • C++: Widget::set_text(std::string_view s) → Expected<void>; clight::screen::widget_set_text(Widget w, std::string_view s) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_toggle

cl_result cl_widget_toggle(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str label, bool on, cl_widget_fn on_change, void* user, cl_widget* out);

Kit widgets: like the widgets of 1.0 they belong to the screen, but they draw in the player’s style and theme (vanilla widgets in Vanilla, the design system in Fancy). Values: widget_value (toggle 1/0, dropdown / tabs / list: the selected index, colour picker: the ARGB colour), widget_set_value.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.toggle, screen:toggle(...), cl.screen.widget_toggle (old name)
  • C++: Screen::widget_toggle(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, bool on, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_toggle(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, bool on, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_icon_button

cl_result cl_widget_icon_button(cl_screen s, int32_t x, int32_t y, int32_t size, cl_str icon, cl_str tooltip, cl_widget_fn on_press, void* user, cl_widget* out);

A square button with an icon (icon set name) and a tooltip.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.icon_button, screen:icon_button(...), cl.screen.widget_icon_button (old name)
  • C++: Screen::widget_icon_button(int32_t x, int32_t y, int32_t size, std::string_view icon, std::string_view tooltip, cl_widget_fn on_press, void* user) → Expected<Widget>; clight::screen::widget_icon_button(Screen s, int32_t x, int32_t y, int32_t size, std::string_view icon, std::string_view tooltip, cl_widget_fn on_press, void* user) → Expected<Widget>
  • 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_widget_dropdown

cl_result cl_widget_dropdown(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str label, cl_str choices, int32_t selected, cl_widget_fn on_change, void* user, cl_widget* out);

choices: one per line (“Small\nMedium\nLarge”); selected: the index.

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.dropdown, screen:dropdown(...), cl.screen.widget_dropdown (old name)
  • C++: Screen::widget_dropdown(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, std::string_view choices, int32_t selected, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_dropdown(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, std::string_view choices, int32_t selected, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_tabs

cl_result cl_widget_tabs(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str tabs, int32_t selected, cl_widget_fn on_change, void* user, cl_widget* out);

A row of tabs (one per line in tabs); on_change gets the newly selected tab (widget_value).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.tabs, screen:tabs(...), cl.screen.widget_tabs (old name)
  • C++: Screen::widget_tabs(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view tabs, int32_t selected, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_tabs(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view tabs, int32_t selected, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_list

cl_result cl_widget_list(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, int32_t row_height, cl_widget_fn on_select, void* user, cl_widget* out);

A scrolling list of rows (title, detail line, optional icon); on_select gets the clicked row (widget_value).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.list, screen:list(...), cl.screen.widget_list (old name)
  • C++: Screen::widget_list(int32_t x, int32_t y, int32_t w, int32_t h, int32_t row_height, cl_widget_fn on_select, void* user) → Expected<Widget>; clight::screen::widget_list(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, int32_t row_height, cl_widget_fn on_select, void* user) → Expected<Widget>
  • 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_widget_list_add

int32_t cl_widget_list_add(cl_widget w, cl_str title, cl_str detail, cl_str icon);

Adds a row; returns its index (-1: not a list).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.list_add, widget:list_add(...), cl.screen.widget_list_add (old name)
  • C++: Widget::list_add(std::string_view title, std::string_view detail, std::string_view icon) → int32_t; clight::screen::widget_list_add(Widget w, std::string_view title, std::string_view detail, std::string_view icon) → int32_t

cl_widget_list_clear

cl_result cl_widget_list_clear(cl_widget w);
  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.list_clear, widget:list_clear(...), cl.screen.widget_list_clear (old name)
  • C++: Widget::list_clear() → Expected<void>; clight::screen::widget_list_clear(Widget w) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_widget_panel

cl_result cl_widget_panel(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_widget* out);

A container drawn under later widgets (no input).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.panel, screen:panel(...), cl.screen.widget_panel (old name)
  • C++: Screen::widget_panel(int32_t x, int32_t y, int32_t w, int32_t h) → Expected<Widget>; clight::screen::widget_panel(Screen s, int32_t x, int32_t y, int32_t w, int32_t h) → Expected<Widget>
  • 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_widget_card

cl_result cl_widget_card(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str title, cl_str body, cl_str icon, cl_widget_fn on_press, void* user, cl_widget* out);

A card: icon, title and wrapped body text; clickable when on_press is set (0 = static).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.card, screen:card(...), cl.screen.widget_card (old name)
  • C++: Screen::widget_card(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view title, std::string_view body, std::string_view icon, cl_widget_fn on_press, void* user) → Expected<Widget>; clight::screen::widget_card(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view title, std::string_view body, std::string_view icon, cl_widget_fn on_press, void* user) → Expected<Widget>
  • 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_widget_heading

cl_result cl_widget_heading(cl_screen s, int32_t x, int32_t y, cl_str text, int32_t level, cl_widget* out);

A heading (level 1…3: H1, H2, H3).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.heading, screen:heading(...), cl.screen.widget_heading (old name)
  • C++: Screen::widget_heading(int32_t x, int32_t y, std::string_view text, int32_t level) → Expected<Widget>; clight::screen::widget_heading(Screen s, int32_t x, int32_t y, std::string_view text, int32_t level) → Expected<Widget>
  • 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_widget_color_picker

cl_result cl_widget_color_picker(cl_screen s, int32_t x, int32_t y, int32_t w, int32_t h, cl_str label, cl_color argb, cl_widget_fn on_change, void* user, cl_widget* out);

A colour swatch with its label; clicking opens a picker (palette, hue, brightness, hex).

  • Side: client. Context: ANY (any thread). Since: API 1.21.
  • Lua: cl.widget.color_picker, screen:color_picker(...), cl.screen.widget_color_picker (old name)
  • C++: Screen::widget_color_picker(int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, cl_color argb, cl_widget_fn on_change, void* user) → Expected<Widget>; clight::screen::widget_color_picker(Screen s, int32_t x, int32_t y, int32_t w, int32_t h, std::string_view label, cl_color argb, cl_widget_fn on_change, void* user) → Expected<Widget>
  • 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_widget_color_picker_alpha

cl_result cl_widget_color_picker_alpha(cl_widget w, bool on);

A colour picker with an opacity bar (and 8-digit hex codes); widget_value then carries the alpha in its top byte.

  • Side: client. Context: ANY (any thread). Since: API 1.23.
  • Lua: cl.widget.color_picker_alpha, widget:color_picker_alpha(...), cl.screen.widget_color_picker_alpha (old name)
  • C++: Widget::color_picker_alpha(bool on) → Expected<void>; clight::screen::widget_color_picker_alpha(Widget w, bool on) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.