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_FLOAT¶: a float, requires LV_USE_FLOAT 1

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_set_min_value_int(lv_subject_t *subject, int32_t min_value)¶

Set a minimum value for an integer subject

Parameters:

subject – pointer to Subject
min_value – the minimum value

void lv_subject_set_max_value_int(lv_subject_t *subject, int32_t max_value)¶

Set a maximum value for an integer subject

Parameters:

subject – pointer to Subject
max_value – the maximum value

void lv_subject_init_float(lv_subject_t *subject, float value)¶

Initialize an float-type Subject.

Parameters:

subject – pointer to Subject
value – initial value

void lv_subject_set_float(lv_subject_t *subject, float value)¶

Set value of an float Subject and notify Observers.

Parameters:

subject – pointer to Subject
value – new value

float lv_subject_get_float(lv_subject_t *subject)¶

Get current value of an float Subject.

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

float lv_subject_get_previous_float(lv_subject_t *subject)¶

Get previous value of an float Subject.

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

void lv_subject_set_min_value_float(lv_subject_t *subject, float min_value)¶

Set a minimum value for a float subject

Parameters:

subject – pointer to Subject
min_value – the minimum value

void lv_subject_set_max_value_float(lv_subject_t *subject, float max_value)¶

Set a maximum value for a float subject

Parameters:

subject – pointer to Subject
max_value – the maximum 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 – pointer 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_subject_increment_dsc_t *lv_obj_add_subject_increment_event(lv_obj_t *obj, lv_subject_t *subject, lv_event_code_t trigger, int32_t step)¶

Add an event handler to increment (or decrement) the value of a subject on a trigger.

Parameters:

obj – pointer to a widget
subject – pointer to a subject to change
trigger – the trigger on which the subject should be changed
step – value to add on trigger if the minimum value is reached, the maximum value will be set on rollover.

void lv_obj_set_subject_increment_event_min_value(lv_obj_t *obj, lv_subject_increment_dsc_t *dsc, int32_t min_value)¶

Set the minimum subject value to set by the event

Parameters:

obj – pointer to the Widget to which the event is attached
dsc – pointer to the descriptor returned by lv_obj_add_subject_increment_event()
min_value – the minimum value to set

void lv_obj_set_subject_increment_event_max_value(lv_obj_t *obj, lv_subject_increment_dsc_t *dsc, int32_t max_value)¶

Set the maximum subject value to set by the event

Parameters:

obj – pointer to the Widget to which the event is attached
dsc – pointer to the descriptor returned by lv_obj_add_subject_increment_event()
max_value – the maximum value to set

void lv_obj_set_subject_increment_event_rollover(lv_obj_t *obj, lv_subject_increment_dsc_t *dsc, bool rollover)¶

Set what to do when the min/max value is crossed.

Note

the subject also can have min/max values and always the smaller range will be considered

Parameters:

obj – pointer to the Widget to which the event is attached
dsc – pointer to the descriptor returned by lv_obj_add_subject_increment_event()
rollover – false: stop at the min/max value; true: jump to the other end

void lv_obj_add_subject_toggle_event(lv_obj_t *obj, lv_subject_t *subject, lv_event_code_t trigger)¶

Toggle the value of an integer subject on an event. If it was != 0 it will be 0. If it was 0, it will be 1.

Parameters:

obj – pointer to a widget
subject – pointer to a subject to toggle
trigger – the trigger on which the subject should be changed

void lv_obj_add_subject_set_int_event(lv_obj_t *obj, lv_subject_t *subject, lv_event_code_t trigger, int32_t value)¶

Set the value of an integer subject.

Parameters:

obj – pointer to a widget
subject – pointer to a subject to change
trigger – the trigger on which the subject should be changed
value – the value to set

void lv_obj_add_subject_set_float_event(lv_obj_t *obj, lv_subject_t *subject, lv_event_code_t trigger, float value)¶

Set the value of a float subject.

Parameters:

obj – pointer to a widget
subject – pointer to a subject to change
trigger – the trigger on which the subject should be changed
value – the value to set

void lv_obj_add_subject_set_string_event(lv_obj_t *obj, lv_subject_t *subject, lv_event_code_t trigger, const char *value)¶

Set the value of a string subject.

Parameters:

obj – pointer to a widget
subject – pointer to a subject to change
trigger – the trigger on which the subject should be changed
value – the value to set

lv_observer_t *lv_obj_bind_style(lv_obj_t *obj, const lv_style_t *style, lv_style_selector_t selector, lv_subject_t *subject, int32_t ref_value)¶

Disable a style if a subject's value is not equal to a reference value

Parameters:

obj – pointer to Widget
style – pointer to a style
selector – pointer to a selector
subject – pointer to Subject
ref_value – reference value to compare Subject's value with

Returns:

pointer to newly-created Observer

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

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

float float_v¶: Floating point value

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

lv_subject_value_t min_value¶: Minimum value for min. int or float

lv_subject_value_t max_value¶: Maximum value for max. int or float

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 notification, start notifying from the beginning.