API Reference

The field-by-field reference for LVGL Safe v0.1.0 - the rules every widget follows, the defaults each one starts from, and the error codes every function returns.

The field-by-field reference for LVGL Safe v0.1.0. For the concepts behind it - the widget lifecycle, rendering, colors, input - start with How it works; to build and run an application, see Build and run.

Three rules hold for every widget in this reference:

  1. ls_widget_common_t is always the first member, named common.
  2. You configure a widget by assigning its fields directly, after ls_<widget>_create(). There are no setters or getters, and create overwrites the struct, so it must come first.
  3. create leaves the widget in a visible state - opaque, with a placeholder color - so in practice you only have to set geometry and content. The two exceptions are listed under Defaults after create.

Widgets

Core types

Widget common, display, screen

Rectangle

ls_rectangle_t

Label

ls_label_t

Button

ls_button_t

Image

ls_image_t

Image button

ls_image_button_t

Arc

ls_arc_t

Defaults after create

All sizes and positions start at 0, and focus_index at UINT32_MAX (never focused). Beyond that:

WidgetDefaults
ls_rectangle_t#cccccc fill, opaque; black border of width 0 (no border)
ls_label_tblack text, opaque, left-aligned, letter_space 1, no font
ls_button_t#666666 and opaque in all five unchecked states; the five checked states are fully transparent
ls_image_topaque, no rotation, black a8_color, src is NULL
ls_image_button_tall ten sources are NULL
ls_arc_tblue, opaque, center 30,30, radius 30, thickness 5, sweeping 30°→90°

The NULL ones are not silent: a label without a font, an image without a src, or an image button whose current state has no source makes ls_render() return LS_ERROR_CODE_INVALID_CONFIGURATION for the whole frame. A widget that draws nothing without an error is one that is hidden, still sized 0, or a checked button state that was never given a color and opacity.

Error handling

Every public function returns an ls_error_code_t (ls_error_codes.h) - check it at the call site:

CodeValueMeaning
LS_ERROR_CODE_OK0Success
LS_ERROR_CODE_INTERNAL_ERROR1Unexpected internal failure
LS_ERROR_CODE_INVALID_ARGUMENT2NULL / out-of-range argument
LS_ERROR_CODE_INVALID_CONFIGURATION3Inconsistent configuration
LS_ERROR_CODE_MEMORY_CORRUPTION4Inconsistent internal data
LS_ERROR_CODE_RENDER_FAILED5Rendering failed

Not a widget, but part of the API

HeaderWhat it gives you
ls_color.hls_color_t, LS_COLOR_MAKE, LS_COLOR_HEX, ls_color_to_u16(), LS_BYTE_PER_PIXEL
ls_render.hls_render(), ls_render_clear_frame_buffer(), ls_render_goto_frame_buffer_px(), LS_OPA_COVER
ls_input.hls_indev_process(), input states, event types, callback typedefs
ls_font.hls_font_t - a generated glyph-bitmap font descriptor
ls_translation.hls_translation_init(), ls_translation_set_language(), ls_translation_get()
ls_math.hls_sin(), ls_cos() - integer trig, so no libm dependency
ls_conf.hCompile-time feature switches. Do not edit in the preview - its values are already baked into the shipped library

Last updated on

Assets

Fonts, images, and translations. Everything a widget draws is converted ahead of time and compiled in - nothing is loaded or decoded at runtime.

Core Types

The three types every LVGL Safe program uses - the widget header every widget embeds, the display that owns the framebuffer, and the screen that owns the widget list.

On this page

WidgetsDefaults after createError handlingNot a widget, but part of the API