lv_observer.h

Typedefs

typedef void (*lv_observer_cb_t)(lv_observer_t *observer, lv_subject_t *subject)

Callback called to notify Observer that Subject's value has changed

Param observer:: pointer to Observer
Param subject:: pointer to Subject being observed

Enums

enum lv_subject_type_t

Values for lv_subject_t's type field

Values:

enumerator LV_SUBJECT_TYPE_INVALID: indicates Subject not initialized yet

enumerator LV_SUBJECT_TYPE_NONE: a null value like None or NILt

enumerator LV_SUBJECT_TYPE_INT: an int32_t

enumerator LV_SUBJECT_TYPE_POINTER: a void pointer

enumerator LV_SUBJECT_TYPE_COLOR: an lv_color_t

enumerator LV_SUBJECT_TYPE_GROUP: an array of Subjects

enumerator LV_SUBJECT_TYPE_STRING: a char pointer

Functions

void lv_subject_init_int(lv_subject_t *subject, int32_t value)

Initialize an integer-type Subject.

Parameters:

subject – pointer to Subject
value – initial value

void lv_subject_set_int(lv_subject_t *subject, int32_t value)

Set value of an integer Subject and notify Observers.

Parameters:

subject – pointer to Subject
value – new value

int32_t lv_subject_get_int(lv_subject_t *subject)

Get current value of an integer Subject.

Parameters:: subject – pointer to Subject
Returns:: current value

int32_t lv_subject_get_previous_int(lv_subject_t *subject)

Get previous value of an integer Subject.

Parameters:: subject – pointer to Subject
Returns:: current value

void lv_subject_init_string(lv_subject_t *subject, char *buf, char *prev_buf, size_t size, const char *value)

Initialize a string-type Subject.

Note

A string Subject stores its own copy of the string, not just the pointer.

Parameters:

subject – pointer to Subject
buf – pointer to buffer to store string
prev_buf – pointer to buffer to store previous string; can be NULL if not used
size – size of buffer(s)
value – initial value of string, e.g. "hello"

void lv_subject_copy_string(lv_subject_t *subject, const char *buf)

Copy a string to a Subject and notify Observers if it changed.

Parameters:

subject – pointer to Subject
buf – new string

void lv_subject_snprintf(lv_subject_t *subject, const char *format, ...)

Format a new string, updating Subject, and notify Observers if it changed.

Parameters:

subject – pointer to Subject
format – format string

const char *lv_subject_get_string(lv_subject_t *subject)

Get current value of a string Subject.

Parameters:: subject – pointer to Subject
Returns:: pointer to buffer containing current value

const char *lv_subject_get_previous_string(lv_subject_t *subject)

Get previous value of a string Subject.

Note

NULL will be returned if NULL was passed in lv_subject_init_string() as prev_buf.

Parameters:: subject – pointer to Subject
Returns:: pointer to buffer containing previous value

void lv_subject_init_pointer(lv_subject_t *subject, void *value)

Initialize a pointer-type Subject.

Parameters:

subject – pointer to Subject
value – initial value

void lv_subject_set_pointer(lv_subject_t *subject, void *ptr)

Set value of a pointer Subject and notify Observers (regardless of whether it changed).

Parameters:

subject – pointer to Subject
ptr – new value

const void *lv_subject_get_pointer(lv_subject_t *subject)

Get current value of a pointer Subject.

Parameters:: subject – pointer to Subject
Returns:: current value

const void *lv_subject_get_previous_pointer(lv_subject_t *subject)

Get previous value of a pointer Subject.

Parameters:: subject – pointer to Subject
Returns:: previous value

void lv_subject_init_color(lv_subject_t *subject, lv_color_t color)

Initialize a color-type Subject.

Parameters:

subject – pointer to Subject
color – initial value

void lv_subject_set_color(lv_subject_t *subject, lv_color_t color)

Set value of a color Subject and notify Observers if it changed.

Parameters:

subject – pointer to Subject
color – new value

lv_color_t lv_subject_get_color(lv_subject_t *subject)

Get current value of a color Subject.

Parameters:: subject – pointer to Subject
Returns:: current value

lv_color_t lv_subject_get_previous_color(lv_subject_t *subject)

Get previous value of a color Subject.

Parameters:: subject – pointer to Subject
Returns:: previous value

void lv_subject_init_group(lv_subject_t *group_subject, lv_subject_t *list[], uint32_t list_len)

Initialize a Group-type Subject.

Parameters:

group_subject – pointer to Group-type Subject
list – list of other Subject addresses; when any of these have values updated, Observers of group_subject will be notified.
list_len – number of elements in list[]

void lv_subject_deinit(lv_subject_t *subject)

Remove all Observers from a Subject and free allocated memory, and delete any associated Widget-Binding events. This leaves subject "disconnected" from all Observers and all associated Widget events established through Widget Binding.

Note

This can safely be called regardless of whether any Observers added with lv_subject_add_observer_obj() or bound to a Widget Property with one of the ..._bind_...() functions.

Parameters:: subject – pointer to Subject

lv_subject_t *lv_subject_get_group_element(lv_subject_t *subject, int32_t index)

Get an element from Subject Group's list.

Parameters:

subject – pointer to Group-type Subject
index – index of element to get

Returns:

pointer to indexed Subject from list, or NULL if index is out of bounds

lv_observer_t *lv_subject_add_observer(lv_subject_t *subject, lv_observer_cb_t observer_cb, void *user_data)

Add Observer to Subject. When Subject's value changes observer_cb will be called.

Parameters:

subject – pointer to Subject
observer_cb – notification callback
user_data – optional user data

Returns:

pointer to newly-created Observer

lv_observer_t *lv_subject_add_observer_obj(lv_subject_t *subject, lv_observer_cb_t observer_cb, lv_obj_t *obj, void *user_data)

Add Observer to Subject for a Widget. When the Widget is deleted, Observer will be unsubscribed from Subject automatically.

Note

Do not call lv_observer_remove() on Observers created this way. Only clean up such Observers by either:

deleting the Widget, or
calling lv_subject_deinit() to gracefully de-couple and remove all Observers.

Parameters:

subject – pointer to Subject
observer_cb – notification callback
obj – pinter to Widget
user_data – optional user data

Returns:

pointer to newly-created Observer

lv_observer_t *lv_subject_add_observer_with_target(lv_subject_t *subject, lv_observer_cb_t observer_cb, void *target, void *user_data)

Add an Observer to a Subject and also save a target pointer.

Parameters:

subject – pointer to Subject
observer_cb – notification callback
target – any pointer (NULL is okay)
user_data – optional user data

Returns:

pointer to newly-created Observer

void lv_observer_remove(lv_observer_t *observer)

Remove Observer from its Subject.

Parameters:: observer – pointer to Observer

void lv_obj_remove_from_subject(lv_obj_t *obj, lv_subject_t *subject)

Remove Observers associated with Widget obj from specified subject or all Subjects.

Note

This function can be used e.g. when a Widget's Subject(s) needs to be replaced by other Subject(s)

Parameters:

obj – pointer to Widget whose Observers should be removed
subject – Subject to remove Widget from, or NULL to remove from all Subjects

void *lv_observer_get_target(lv_observer_t *observer)

Get target of an Observer.

Parameters:: observer – pointer to Observer
Returns:: pointer to saved target

lv_obj_t *lv_observer_get_target_obj(lv_observer_t *observer)

Get target Widget of Observer. This is the same as lv_observer_get_target(), except it returns target as an lv_obj_t *.

Parameters:: observer – pointer to Observer
Returns:: pointer to saved Widget target

void *lv_observer_get_user_data(const lv_observer_t *observer)

Get Observer's user data.

Parameters:: observer – pointer to Observer
Returns:: void pointer to saved user data

void lv_subject_notify(lv_subject_t *subject)

Notify all Observers of Subject.

Parameters:: subject – pointer to Subject

lv_observer_t *lv_obj_bind_flag_if_eq(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_flag_if_not_eq(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is not equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_flag_if_gt(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is greater than a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_flag_if_ge(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is greater than or equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_flag_if_lt(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is less than a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_flag_if_le(lv_obj_t *obj, lv_subject_t *subject, lv_obj_flag_t flag, int32_t ref_value)

Set Widget's flag(s) if an integer Subject's value is less than or equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
flag – flag(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_eq(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set Widget's state(s) if an integer Subject's value is equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_not_eq(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set a Widget's state(s) if an integer Subject's value is not equal to a reference value, clear flag otherwise

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_gt(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set Widget's state(s) if an integer Subject's value is greater than a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_ge(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set Widget's state(s) if an integer Subject's value is greater than or equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_lt(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set Widget's state(s) if an integer Subject's value is less than a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_state_if_le(lv_obj_t *obj, lv_subject_t *subject, lv_state_t state, int32_t ref_value)

Set Widget's state(s) if an integer Subject's value is less than or equal to a reference value, clear flag otherwise.

Parameters:

obj – pointer to Widget
subject – pointer to Subject
state – state(s) (can be bit-wise OR-ed) to set or clear (e.g. LV_STATE_CHECKED)
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

lv_observer_t *lv_obj_bind_checked(lv_obj_t *obj, lv_subject_t *subject)

Set an integer Subject to 1 when a Widget is checked and set it 0 when unchecked, and clear Widget's checked state when Subject's value changes to 0 and set it when non-zero.

Note

Ensure Widget's LV_OBJ_FLAG_CHECKABLE flag is set.

Parameters:

obj – pointer to Widget
subject – pointer to a Subject

Returns:

pointer to newly-created Observer

lv_observer_t *lv_label_bind_text(lv_obj_t *obj, lv_subject_t *subject, const char *fmt)

Bind an integer, string, or pointer Subject to a Label.

Note

fmt == NULL can be used only with string and pointer Subjects.

Note

If Subject is a pointer and fmt == NULL, pointer must point to a \0 terminated string.

Parameters:

obj – pointer to Label
subject – pointer to Subject
fmt – optional printf-like format string with 1 format specifier (e.g. "%d °C") or NULL to bind to the value directly.

Returns:

pointer to newly-created Observer

lv_observer_t *lv_arc_bind_value(lv_obj_t *obj, lv_subject_t *subject)

Bind an integer subject to an Arc's value.

Parameters:

obj – pointer to Arc
subject – pointer to Subject

Returns:

pointer to newly-created Observer

lv_observer_t *lv_slider_bind_value(lv_obj_t *obj, lv_subject_t *subject)

Bind an integer Subject to a Slider's value.

Parameters:

obj – pointer to Slider
subject – pointer to Subject

Returns:

pointer to newly-created Observer

lv_observer_t *lv_roller_bind_value(lv_obj_t *obj, lv_subject_t *subject)

Bind an integer Subject to a Roller's value.

Parameters:

obj – pointer to Roller
subject – pointer to Subject

Returns:

pointer to newly-created Observer

lv_observer_t *lv_dropdown_bind_value(lv_obj_t *obj, lv_subject_t *subject)

Bind an integer Subject to a Dropdown's value.

Parameters:

obj – pointer to Dropdown
subject – pointer to Subject

Returns:

pointer to newly-created Observer

union lv_subject_value_t

#include <lv_observer.h>

A common type to handle all the various observable types in the same way

Public Members

int32_t num: Integer number (opacity, enums, booleans or "normal" numbers)

const void *pointer: Constant pointer (string buffer, format string, font, cone text, etc.)

lv_color_t color: Color

struct lv_subject_t

#include <lv_observer.h>

The Subject (an observable value)

Public Members

lv_ll_t subs_ll: Subscribers

lv_subject_value_t value: Current value

lv_subject_value_t prev_value: Previous value

void *user_data: Additional parameter, can be used freely by user

uint32_t type: One of the LV_SUBJECT_TYPE_... values

uint32_t size: String buffer size or group length

uint32_t notify_restart_query: If an Observer was deleted during notifcation, start notifying from the beginning.