Skip to content
Download

Components (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. 21 functions, the newest from API 1.22.

Explanations and examples: Components, HTML/CSS overlays. Every function of the view 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_view_open cl.view.open client ANY 1.22
cl_view_mount cl.view.mount client ANY 1.22
cl_view_close cl.view.close client ANY 1.22
cl_view_is_open cl.view.is_open client ANY 1.22
cl_view_root cl.view.root client ANY 1.22
cl_view_begin cl.view.begin client ANY 1.22
cl_view_end cl.view.end client ANY 1.22
cl_view_node cl.view.node client ANY 1.22
cl_view_component cl.view.component client ANY 1.22
cl_view_prop_num cl.view.prop_num client ANY 1.22
cl_view_prop_str cl.view.prop_str client ANY 1.22
cl_view_get_num cl.view.get_num client ANY 1.22
cl_view_get_str cl.view.get_str client ANY 1.22
cl_view_state_num cl.view.state_num client ANY 1.22
cl_view_state_str cl.view.state_str client ANY 1.22
cl_view_set_state_num cl.view.set_state_num client ANY 1.22
cl_view_set_state_str cl.view.set_state_str client ANY 1.22
cl_view_invalidate cl.view.invalidate client ANY 1.22
cl_view_effect cl.view.effect client ANY 1.22
cl_view_get_stats cl.view.get_stats client ANY 1.22
cl_view_flush cl.view.flush client ANY 1.22

cl_view_open

cl_result cl_view_open(const cl_view_desc* desc, cl_view* out);

Opens a themed screen whose content is the view (closing either closes both).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.open
  • C++: clight::view::open(const cl_view_desc* desc) → Expected<View>
  • 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_view_mount

cl_result cl_view_mount(cl_screen s, const cl_view_desc* desc, cl_view* out);

Mounts a view into an open mod screen (cl_screen_open), over the screen’s own widgets, in the desc’s area.

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.mount, screen:mount(...)
  • C++: Screen::view_mount(const cl_view_desc* desc) → Expected<View>; clight::view::mount(Screen s, const cl_view_desc* desc) → Expected<View>
  • 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_view_close

cl_result cl_view_close(cl_view v);

Unmounts it (effect cleanups and on_unmount run; the screen of view_open closes).

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

cl_view_is_open

bool cl_view_is_open(cl_view v);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.is_open, view:is_open(...)
  • C++: View::is_open() → bool; clight::view::is_open(View v) → bool

cl_view_root

uint64_t cl_view_root(cl_view v);

The root component instance.

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.root, view:root(...)
  • C++: View::root() → uint64_t; clight::view::root(View v) → uint64_t

cl_view_begin

cl_result cl_view_begin(cl_view v, cl_view_kind kind, cl_str key);

Inside render: a container node (COLUMN, ROW, PANEL, LIST); its children follow until view_end. key: stable among its siblings (“” = by position).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.begin, view:begin(...)
  • C++: View::begin(cl_view_kind kind, std::string_view key) → Expected<void>; clight::view::begin(View v, cl_view_kind kind, std::string_view key) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_end

cl_result cl_view_end(cl_view v);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.end, view:end(...)
  • C++: View::end() → Expected<void>; clight::view::end(View v) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_node

cl_result cl_view_node(cl_view v, cl_view_kind kind, cl_str key);

Inside render: a leaf node (a widget).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.node, view:node(...)
  • C++: View::node(cl_view_kind kind, std::string_view key) → Expected<void>; clight::view::node(View v, cl_view_kind kind, std::string_view key) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_component

uint64_t cl_view_component(cl_view v, cl_str type, cl_str key);

Inside render: a child component; it renders after this one when it is new, marked dirty or its props changed. Returns its instance (0 on an error).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.component, view:component(...)
  • C++: View::component(std::string_view type, std::string_view key) → uint64_t; clight::view::component(View v, std::string_view type, std::string_view key) → uint64_t

cl_view_prop_num

cl_result cl_view_prop_num(cl_view v, cl_str name, double value);

A prop of the node or component just added (view_begin / view_node / view_component).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.prop_num, view:prop_num(...)
  • C++: View::prop_num(std::string_view name, double value) → Expected<void>; clight::view::prop_num(View v, std::string_view name, double value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_prop_str

cl_result cl_view_prop_str(cl_view v, cl_str name, cl_str value);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.prop_str, view:prop_str(...)
  • C++: View::prop_str(std::string_view name, std::string_view value) → Expected<void>; clight::view::prop_str(View v, std::string_view name, std::string_view value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_get_num

double cl_view_get_num(cl_view v, uint64_t comp, cl_str name, double fallback);

A prop the parent gave the component comp (fallback when it has none).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.get_num, view:get_num(...)
  • C++: View::get_num(uint64_t comp, std::string_view name, double fallback) → double; clight::view::get_num(View v, uint64_t comp, std::string_view name, double fallback) → double

cl_view_get_str

cl_result cl_view_get_str(cl_view v, uint64_t comp, cl_str name, char* buf, size_t cap, size_t* out_len);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.get_str, view:get_str(...)
  • C++: View::get_str(uint64_t comp, std::string_view name) → Expected<std::string>; clight::view::get_str(View v, uint64_t comp, std::string_view name) → 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_view_state_num

double cl_view_state_num(cl_view v, uint64_t comp, cl_str name, double initial);

Named state of a component (created with initial on the first call).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.state_num, view:state_num(...)
  • C++: View::state_num(uint64_t comp, std::string_view name, double initial) → double; clight::view::state_num(View v, uint64_t comp, std::string_view name, double initial) → double

cl_view_state_str

cl_result cl_view_state_str(cl_view v, uint64_t comp, cl_str name, cl_str initial, char* buf, size_t cap, size_t* out_len);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.state_str, view:state_str(...)
  • C++: View::state_str(uint64_t comp, std::string_view name, std::string_view initial) → Expected<std::string>; clight::view::state_str(View v, uint64_t comp, std::string_view name, std::string_view initial) → 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_view_set_state_num

cl_result cl_view_set_state_num(cl_view v, uint64_t comp, cl_str name, double value);

Sets state; the component renders again on the next frame, only when the value changed.

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.set_state_num, view:set_state_num(...)
  • C++: View::set_state_num(uint64_t comp, std::string_view name, double value) → Expected<void>; clight::view::set_state_num(View v, uint64_t comp, std::string_view name, double value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_set_state_str

cl_result cl_view_set_state_str(cl_view v, uint64_t comp, cl_str name, cl_str value);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.set_state_str, view:set_state_str(...)
  • C++: View::set_state_str(uint64_t comp, std::string_view name, std::string_view value) → Expected<void>; clight::view::set_state_str(View v, uint64_t comp, std::string_view name, std::string_view value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_invalidate

cl_result cl_view_invalidate(cl_view v, uint64_t comp);

Renders the component again on the next frame (for state the mod keeps itself; 0 = the root).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.invalidate, view:invalidate(...)
  • C++: View::invalidate(uint64_t comp) → Expected<void>; clight::view::invalidate(View v, uint64_t comp) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_effect

cl_result cl_view_effect(cl_view v, cl_str name, uint64_t deps);

Inside render: an effect of the component being rendered. on_effect runs it after the update when it is new or deps changed (a hash or counter of what it depends on).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.effect, view:effect(...)
  • C++: View::effect(std::string_view name, uint64_t deps) → Expected<void>; clight::view::effect(View v, std::string_view name, uint64_t deps) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_view_get_stats

cl_result cl_view_get_stats(cl_view v, cl_view_stats* out);
  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.get_stats, view:get_stats(...)
  • C++: View::get_stats() → Expected<cl_view_stats>; clight::view::get_stats(View v) → Expected<cl_view_stats>
  • 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_view_flush

cl_result cl_view_flush(cl_view v);

Runs pending re-renders now instead of on the next frame (tests; screens update by themselves).

  • Side: client. Context: ANY (any thread). Since: API 1.22.
  • Lua: cl.view.flush, view:flush(...)
  • C++: View::flush() → Expected<void>; clight::view::flush(View v) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.