lv_observer.h

Typedefs

typedef struct _lv_observer_t lv_observer_t

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

Callback called when the observed value changes

Param observer:: pointer to the observer of the callback
Param subject:: pointer to the subject of the observer

Enums

enum lv_subject_type_t

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 the subject
value -- initial value

void lv_subject_set_int(lv_subject_t *subject, int32_t value)

Set the value of an integer subject. It will notify all the observers as well.

Parameters:

subject -- pointer to the subject
value -- the new value

int32_t lv_subject_get_int(lv_subject_t *subject)

Get the current value of an integer subject

Parameters:: subject -- pointer to the subject
Returns:: the current value

int32_t lv_subject_get_previous_int(lv_subject_t *subject)

Get the previous value of an integer subject

Parameters:: subject -- pointer to the subject
Returns:: the 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

the string subject stores the whole string, not only a pointer

Parameters:

subject -- pointer to the subject
buf -- pointer to a buffer to store the string
prev_buf -- pointer to a buffer to store the previous string, can be NULL if not used
size -- size of the buffer
value -- initial value as a string, e.g. "hello"

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

Copy a string to a subject. It will notify all the observers as well.

Parameters:

subject -- pointer to the subject
buf -- the new string

const char *lv_subject_get_string(lv_subject_t *subject)

Get the current value of an string subject

Parameters:: subject -- pointer to the subject
Returns:: pointer to the buffer containing the current value

const char *lv_subject_get_previous_string(lv_subject_t *subject)

Get the previous value of an string subject

Note

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

Parameters:: subject -- pointer to the subject
Returns:: pointer to the buffer containing the current value

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

Initialize an pointer type subject

Parameters:

subject -- pointer to the subject
value -- initial value

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

Set the value of a pointer subject. It will notify all the observers as well.

Parameters:

subject -- pointer to the subject
value -- the new value

const void *lv_subject_get_pointer(lv_subject_t *subject)

Get the current value of a pointer subject

Parameters:: subject -- pointer to the subject
Returns:: the current value

const void *lv_subject_get_previous_pointer(lv_subject_t *subject)

Get the previous value of a pointer subject

Parameters:: subject -- pointer to the subject
Returns:: the current value

void lv_subject_init_color(lv_subject_t *subject, lv_color_t color)

Initialize an color type subject

Parameters:

subject -- pointer to the subject
value -- initial value

void lv_subject_set_color(lv_subject_t *subject, lv_color_t color)

Set the value of a color subject. It will notify all the observers as well.

Parameters:

subject -- pointer to the subject
value -- the new value

lv_color_t lv_subject_get_color(lv_subject_t *subject)

Get the current value of a color subject

Parameters:: subject -- pointer to the subject
Returns:: the current value

lv_color_t lv_subject_get_previous_color(lv_subject_t *subject)

Get the previous value of a color subject

Parameters:: subject -- pointer to the subject
Returns:: the current value

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

Initialize a subject group

Parameters:

subject -- pointer to the subject
list -- list of other subject addresses, any of these changes subject will be notified
list_len -- number of elements in list

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

Get an element from the subject group's list

Parameters:

subject -- pointer to the subject
index -- index of the element to get

Returns:

pointer a subject from the list, or NULL if the 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 an observer to a subject. When the subject changes observer_cb will be called.

Parameters:

subject -- pointer to the subject
observer_cb -- the callback to call
user_data -- optional user data

Returns:

pointer to the 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 an observer to a subject for an object. When the object is deleted, it will be removed from the subject automatically.

Parameters:

subject -- pointer to the subject
observer_cb -- the callback to call
obj -- pointer to an object
user_data -- optional user data

Returns:

pointer to the created observer

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

Add an observer to a subject and also save a target.

Parameters:

subject -- pointer to the subject
observer_cb -- the callback to call
target -- pointer to any data
user_data -- optional user data

Returns:

pointer to the created observer

void lv_observer_remove(lv_observer_t *observer)

Remove an observer from its subject

Parameters:: observer -- pointer to an observer

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

Remove all observers from their subject related to an object

Parameters:

observer -- pointer to an observer
obj -- pointer to an object

void *lv_observer_get_target(lv_observer_t *observer)

Get the target of an observer

Parameters:: observer -- pointer to an observer
Returns:: pointer to the saved target

static inline lv_obj_t *lv_observer_get_target_obj(lv_observer_t *observer)

Get the target object of the observer. It's the same as lv_observer_get_target and added only for semantic reasons

Parameters:: observer -- pointer to an observer
Returns:: pointer to the saved object target

void lv_subject_notify(lv_subject_t *subject)

Notify all observers of subject

Parameters:: subject -- pointer to a 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 an object flag if an integer subject's value is equal to a reference value, clear the flag otherwise

Parameters:

obj -- pointer to an object
subject -- pointer to a subject
flag -- a flag to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value -- a reference value to compare the subject's value with

Returns:

pointer to the 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 an object flag if an integer subject's value is not equal to a reference value, clear the flag otherwise

Parameters:

obj -- pointer to an object
subject -- pointer to a subject
flag -- a flag to set or clear (e.g. LV_OBJ_FLAG_HIDDEN)
ref_value -- a reference value to compare the subject's value with

Returns:

pointer to the 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 an object state if an integer subject's value is equal to a reference value, clear the flag otherwise

Parameters:

obj -- pointer to an object
subject -- pointer to a subject
flag -- a state to set or clear (e.g. LV_STATE_CHECKED)
ref_value -- a reference value to compare the subject's value with

Returns:

pointer to the 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 an object state if an integer subject's value is not equal to a reference value, clear the flag otherwise

Parameters:

obj -- pointer to an object
subject -- pointer to a subject
flag -- a state to set or clear (e.g. LV_STATE_CHECKED)
ref_value -- a reference value to compare the subject's value with

Returns:

pointer to the created observer

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

Set an integer subject to 1 when a button is checked and set it 0 when unchecked.

Parameters:

obj -- pointer to a button
subject -- pointer to a subject

Returns:

pointer to the 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 the subject is a pointer must point to a \0 terminated string.

Parameters:

obj -- pointer to a label
subject -- pointer to a subject
fmt -- an optional format string with 1 format specifier (e.g. "%d °C") or NULL to bind the value directly.

Returns:

pointer to the 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 an arc
subject -- pointer to a subject

Returns:

pointer to the 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 a slider
subject -- pointer to a subject

Returns:

pointer to the 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 a roller
subject -- pointer to a subject

Returns:

pointer to the 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 a drop down
subject -- pointer to a subject

Returns:

pointer to the 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

uint32_t type

uint32_t size: Might be used to store a size related to type

lv_subject_value_t value: Actual value

lv_subject_value_t prev_value: Previous value

uint32_t notify_restart_query: If an observer deleted start notifying from the beginning.

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

struct _lv_observer_t

#include <lv_observer.h>

The observer object: a descriptor returned when subscribing LVGL widgets to subjects

Public Members

lv_subject_t *subject: The observed value

lv_observer_cb_t cb: Callback that should be called when the value changes

void *target: A target for the observer, e.g. a widget or style

void *user_data: Additional parameter supplied when subscribing

uint32_t auto_free_user_data: Automatically free user data when the observer is removed

uint32_t notified: Mark if this observer was already notified