.. _timer: ================ Timer (lv_timer) ================ LVGL has a built-in Timer system. You can register a function to have it be called periodically. The Timers are handled and called in :cpp:func:`lv_timer_handler`, which needs to be called every few milliseconds. See :ref:`timer_handler` for more information. By default, LVGL itself uses Timers to: - refresh each display --- during the creation of each :ref:`Display`, a Timer is created for that Display. That Timer refreshes the display based on the configured value of :c:macro:`LV_DEF_REFR_PERIOD`, and also sends all display-related events, like :cpp:enumerator:`LV_EVENT_REFR_START`, :cpp:enumerator:`LV_EVENT_REFR_READY`, etc. - read input devices --- during the creation of each :ref:`indev`, a Timer is created for that Input Device based on the configured value of :c:macro:`LV_DEF_REFR_PERIOD`. That Timer causes that input device to be read and also sends all input-device-related events, like :cpp:enumerator:`LV_EVENT_CLICKED`, :cpp:enumerator:`LV_EVENT_PRESSED`, etc. - update system-monitor values --- if :c:macro:`LV_USE_SYSMON` is set to ``1`` in ``lv_conf.h``, one or more timers are created to periodically compute and monitor system performance statistics and LVGL's memory usage. Timers are non-preemptive, which means a Timer cannot interrupt another Timer. Therefore, you can call any LVGL related function in a Timer. Creating a Timer **************** To create a new Timer, use :cpp:expr:`lv_timer_create(timer_cb, period_ms, user_data)`. It returns an :cpp:type:`lv_timer_t` ``*`` which can be used later to modify the parameters of the Timer, pause it, or delete it when it is no longer needed. :cpp:func:`lv_timer_create_basic` can also be used to create a new Timer without specifying any parameters. A Timer callback should have this prototype: ``void (*lv_timer_cb_t)(lv_timer_t *)``. For example: .. code-block:: c void my_timer(lv_timer_t * timer) { /* Use the user_data */ uint32_t * user_data = lv_timer_get_user_data(timer); printf("my_timer called with user data: %d\n", *user_data); /* Do something with LVGL */ if(something_happened) { something_happened = false; lv_button_create(lv_screen_active()); } } ... static uint32_t user_data = 10; lv_timer_t * timer = lv_timer_create(my_timer, 500, &user_data); Ready and Reset *************** :cpp:expr:`lv_timer_ready(timer)` makes a Timer run on the next call of :cpp:func:`lv_timer_handler`. :cpp:expr:`lv_timer_reset(timer)` resets the period of a Timer. It will be called again after its currently-set period (in milliseconds) has elapsed. Setting Parameters ****************** You can modify these Timer parameters at any time during its life: - :cpp:expr:`lv_timer_set_cb(timer, new_cb)` - :cpp:expr:`lv_timer_set_period(timer, new_period_ms)` - :cpp:expr:`lv_timer_set_user_data(timer, user_data)` Repeat Count ************ When a Timer is created, its repeat-count is set to ``-1`` to cause it to repeat indefinitely. You can make a Timer repeat only a given number of times with :cpp:expr:`lv_timer_set_repeat_count(timer, count)`. By default, once the Timer has run ``count`` times, it will be automatically deleted. You can use :cpp:expr:`lv_timer_set_auto_delete(timer, false)` if you want the timer to instead be paused after it has run ``count`` times. This can be handy if you reuse that timer repeatedly and want to avoid the CPU and :cpp:func:`lv_malloc` overhead of repeatedly creating and deleting a timer. If you use this option, you will need to set its repeat count (to either ``-1`` or a positive repeat count, since it will have decremented to ``0``) and :ref:`resume ` it to make it active again. .. _timer_pause_and_resume: Pause and Resume **************** :cpp:expr:`lv_timer_pause(timer)` pauses the specified Timer. :cpp:expr:`lv_timer_resume(timer)` resumes the specified Timer. Measuring Idle Time ******************* You can get the idle percentage time of :cpp:func:`lv_timer_handler` with :cpp:func:`lv_timer_get_idle`. Note that it does not measure the idle time of the overall system, only of :cpp:func:`lv_timer_handler`. This can be misleading if you are using an operating system and DMA and/or GPU are used during rendering, as it does not actually measure the time the OS spends in an idle thread. If you are using an OS and wish to get the time the CPU is spending in an idle thread, one way of doing so is configuring :c:macro:`LV_USE_SYSMON` and :c:macro:`LV_USE_PERF_MONITOR` to ``1`` in ``lv_conf.h`` (if they are not already), and setting the macro :c:macro:`LV_SYSMON_GET_IDLE` to the name of a function that fetches the percent of CPU time spent in the OS's idle thread. An example of such a function is :cpp:func:`lv_os_get_idle_percent` in ``lv_freertos.c``. While the configuration is set this way, some system performance statistics (including CPU load) will appear on the display in a partially-transparent label whose location is set by the :c:macro:`LV_USE_PERF_MONITOR_POS` macro. Enable and Disable ****************** You can temporarily disable Timer handling with :cpp:expr:`lv_timer_enable(false)`. Be advised: this also pauses handling of Timers that refresh Display(s) and read from input devices, so don't forget to re-enable it with :cpp:expr:`lv_timer_enable(true)` as soon as the need for the pause is over. Timer Handler Resume Callback ***************************** When the Timer system has been disabled (causing :cpp:func:`lv_timer_handler` to return early before it has processed any timers), if you want to take some action when the Timer system is re-enabled again, set a resume callback using :cpp:expr:`lv_timer_handler_set_resume_cb(cb, user_data)`. The callback should have this prototype: ``void (*lv_timer_handler_resume_cb_t)(void*)``. Asynchronous calls ****************** There are several cases in which you may not want to perform an action immediately. Some examples are: - you cannot delete a Widget because something else is still using it, - you don't want to block execution now, or - you detect the need to delete a Widget in a thread other than the thread making LVGL calls (e.g. in a case where you are using a :ref:`Gateway Thread ` to make all LVGL calls in a multi-threaded environment). For these cases, :cpp:expr:`lv_async_call(my_function, data_p)` can be used to call ``my_function`` on the next invocation of :cpp:func:`lv_timer_handler`. As a side effect, this also ensures it is called in a thread in which it is safe to make LVGL calls. ``data_p`` will be passed to the function when it's called. Note that only the data's pointer is saved, so whatever it is pointing to needs to remain valid until the function is called, so it can point to ``static``, global or dynamically allocated data. If you want to cancel an asynchronous call, call :cpp:expr:`lv_async_call_cancel(my_function, data_p)`, which will remove all asynchronous calls matching ``my_function`` and ``data_p``. Note that if :cpp:expr:`lv_async_call(my_function, data_p)` is called from a thread other than the one that normally makes LVGL calls, you are still obligated to protect the LVGL data structure using a MUTEX. For example: .. code-block:: c void my_screen_clean_up(void * scr) { /* Free some resources related to `scr`*/ /* Finally delete the screen */ lv_obj_delete(scr); } ... /* Do something with the Widget on the current screen */ /* Delete screen on next call of `lv_timer_handler`, not right now. */ lv_lock(); lv_async_call(my_screen_clean_up, lv_screen_active()); lv_unlock(); /* The screen is still valid so you can do other things with it */ If you just want to delete a Widget and don't need to clean anything up in ``my_screen_cleanup`` you could just use :cpp:expr:`lv_obj_delete_async(widget)` which will delete the Widget on the next call to :cpp:func:`lv_timer_handler`. .. _timer_api: API ***