# lv_timer.h (/api/public/core/lv_timer_h)



<RelatedHeaders name="lv_timer_private.h" isPrivate="false" />

<ApiSummary functions="24" typedefs="2" macros="1" />

Functions [#functions]

<ApiTabs items="[&#x22;Setters (7)&#x22;,&#x22;Getters (6)&#x22;,&#x22;Other (11)&#x22;]">
  <ApiTab value="Setters (7)">
    <ApiMember kind="function" name="lv_timer_handler_set_resume_cb" file="public/core/lv_timer.h" line="79" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L79">
      lv_timer_handler_set_resume_cb [#lv_timer_handler_set_resume_cb]

      Set the resume callback to the timer handler

      ```c title=" " lineNumbers=1
      void lv_timer_handler_set_resume_cb(lv_timer_handler_resume_cb_t cb, void *data)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name   | Type                                            | Description                                        |
      | ------ | ----------------------------------------------- | -------------------------------------------------- |
      | `cb`   | <ApiLink name="lv_timer_handler_resume_cb_t" /> | the function to call when timer handler is resumed |
      | `data` | `void *`                                        | pointer to a resume data **May** be `NULL`.        |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_cb" file="public/core/lv_timer.h" line="123" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L123">
      lv_timer_set_cb [#lv_timer_set_cb]

      Set the callback to the timer (the function to call periodically)

      ```c title=" " lineNumbers=1
      void lv_timer_set_cb(lv_timer_t *timer, lv_timer_cb_t timer_cb)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name       | Type                                                 | Description                       |
      | ---------- | ---------------------------------------------------- | --------------------------------- |
      | `timer`    | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a timer                |
      | `timer_cb` | <ApiLink name="lv_timer_cb_t" />                     | the function to call periodically |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_period" file="public/core/lv_timer.h" line="130" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L130">
      lv_timer_set_period [#lv_timer_set_period]

      Set new period for a lv\_timer

      ```c title=" " lineNumbers=1
      void lv_timer_set_period(lv_timer_t *timer, uint32_t period)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name     | Type                                                 | Description            |
      | -------- | ---------------------------------------------------- | ---------------------- |
      | `timer`  | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer |
      | `period` | `uint32_t`                                           | the new period         |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_repeat_count" file="public/core/lv_timer.h" line="143" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L143">
      lv_timer_set_repeat_count [#lv_timer_set_repeat_count]

      Set the number of times a timer will repeat.

      ```c title=" " lineNumbers=1
      void lv_timer_set_repeat_count(lv_timer_t *timer, int32_t repeat_count)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name           | Type                                                 | Description                                   |
      | -------------- | ---------------------------------------------------- | --------------------------------------------- |
      | `timer`        | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer.                       |
      | `repeat_count` | `int32_t`                                            | -1 : infinity; 0 : stop ; n>0: residual times |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_auto_delete" file="public/core/lv_timer.h" line="150" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L150">
      lv_timer_set_auto_delete [#lv_timer_set_auto_delete]

      Set whether a lv\_timer will be deleted automatically when it is called `repeat_count` times.

      ```c title=" " lineNumbers=1
      void lv_timer_set_auto_delete(lv_timer_t *timer, bool auto_delete)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name          | Type                                                 | Description                                                                            |
      | ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- |
      | `timer`       | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer.                                                                |
      | `auto_delete` | `bool`                                               | true: auto delete; false: timer will be paused when it is called `repeat_count` times. |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_user_data" file="public/core/lv_timer.h" line="157" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L157">
      lv_timer_set_user_data [#lv_timer_set_user_data]

      Set custom parameter to the lv\_timer.

      ```c title=" " lineNumbers=1
      void lv_timer_set_user_data(lv_timer_t *timer, void *user_data)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name        | Type                                                 | Description                         |
      | ----------- | ---------------------------------------------------- | ----------------------------------- |
      | `timer`     | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer.             |
      | `user_data` | `void *`                                             | custom parameter **May** be `NULL`. |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_set_external_data" file="public/core/lv_timer.h" line="220" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L220">
      lv_timer_set_external_data [#lv_timer_set_external_data]

      Attaches external user data and destructor callback to a timer object.

      Associates custom user data with an LVGL timer and specifies a destructor function that will be automatically invoked when the timer is deleted to properly clean up the associated resources.

      ```c title=" " lineNumbers=1
      void lv_timer_set_external_data(lv_timer_t *timer, void *data, void(*free_cb)(void *data))
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name      | Type                                                 | Description                                                                                                                                               |
      | --------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | `timer`   | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | Pointer to the timer object                                                                                                                               |
      | `data`    | `void *`                                             | User-defined data pointer to associate with the timer **May** be `NULL`.                                                                                  |
      | `free_cb` | `void(*)(void *data)`                                | Callback function for cleaning up ext\_data when timer is deleted. Receives ext\_data as parameter. **May** be `NULL`. When NULL no cleanup is performed. |
    </ApiMember>
  </ApiTab>

  <ApiTab value="Getters (6)">
    <ApiMember kind="function" name="lv_timer_get_time_to_next" file="public/core/lv_timer.h" line="65" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L65">
      lv_timer_get_time_to_next [#lv_timer_get_time_to_next]

      Calculate the time to the soonest LVGL timer.

      ```c title=" " lineNumbers=1
      uint32_t lv_timer_get_time_to_next(void)
      ```

      **Returns:** `uint32_t` — time till it needs to be run next timer (in ms)
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_get_idle" file="public/core/lv_timer.h" line="176" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L176">
      lv_timer_get_idle [#lv_timer_get_idle]

      Get idle percentage

      ```c title=" " lineNumbers=1
      uint32_t lv_timer_get_idle(void)
      ```

      **Returns:** `uint32_t` — the lv\_timer idle in percentage
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_get_time_until_next" file="public/core/lv_timer.h" line="182" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L182">
      lv_timer_get_time_until_next [#lv_timer_get_time_until_next]

      Get the time remaining until the next timer will run

      ```c title=" " lineNumbers=1
      uint32_t lv_timer_get_time_until_next(void)
      ```

      **Returns:** `uint32_t` — the time remaining in ms
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_get_next" file="public/core/lv_timer.h" line="190" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L190">
      lv_timer_get_next [#lv_timer_get_next]

      Iterate through the timers

      ```c title=" " lineNumbers=1
      lv_timer_t * lv_timer_get_next(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description                                                                                        |
      | ------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | the previous return value. **May** be `NULL`. When NULL the iteration starts from the first timer. |

      **Returns:** <ApiLink name="lv_timer_t" display="lv_timer_t *" /> — the next timer or NULL if there is no more timer
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_get_user_data" file="public/core/lv_timer.h" line="197" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L197">
      lv_timer_get_user_data [#lv_timer_get_user_data]

      Get the user\_data passed when the timer was created

      ```c title=" " lineNumbers=1
      void * lv_timer_get_user_data(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description              |
      | ------- | ---------------------------------------------------- | ------------------------ |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to the lv\_timer |

      **Returns:** `void *` — pointer to the user\_data
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_get_paused" file="public/core/lv_timer.h" line="204" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L204">
      lv_timer_get_paused [#lv_timer_get_paused]

      Get the pause state of a timer

      ```c title=" " lineNumbers=1
      bool lv_timer_get_paused(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description            |
      | ------- | ---------------------------------------------------- | ---------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer |

      **Returns:** `bool` — true: timer is paused; false: timer is running
    </ApiMember>
  </ApiTab>

  <ApiTab value="Other (11)">
    <ApiMember kind="function" name="lv_timer_handler" file="public/core/lv_timer.h" line="49" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L49">
      lv_timer_handler [#lv_timer_handler]

      Call it periodically to handle lv\_timers.

      ```c title=" " lineNumbers=1
      uint32_t lv_timer_handler(void)
      ```

      **Returns:** `uint32_t` — time till it needs to be run next (in ms)
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_handler_run_in_period" file="public/core/lv_timer.h" line="58" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L58">
      lv_timer_handler_run_in_period [#lv_timer_handler_run_in_period]

      Call it in the super-loop of main() or threads. It will run <ApiLink name="lv_timer_handler" display="lv_timer_handler()" /> with a given period in ms. You can use it with sleep or delay in OS environment. This function is used to simplify the porting.

      ```c title=" " lineNumbers=1
      uint32_t lv_timer_handler_run_in_period(uint32_t period)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name     | Type       | Description                                                                             |
      | -------- | ---------- | --------------------------------------------------------------------------------------- |
      | `period` | `uint32_t` | the period for running <ApiLink name="lv_timer_handler" display="lv_timer_handler()" /> |

      **Returns:** `uint32_t` — the time after which it must be called again
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_periodic_handler" file="public/core/lv_timer.h" line="72" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L72">
      lv_timer_periodic_handler [#lv_timer_periodic_handler]

      Call it in the super-loop of main() or threads. It will automatically call <ApiLink name="lv_timer_handler" display="lv_timer_handler()" /> at the right time. This function is used to simplify the porting.

      ```c title=" " lineNumbers=1
      void lv_timer_periodic_handler(void)
      ```
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_create_basic" file="public/core/lv_timer.h" line="86" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L86">
      lv_timer_create_basic [#lv_timer_create_basic]

      Create an "empty" timer. It needs to be initialized with at least `lv_timer_set_cb` and `lv_timer_set_period`

      ```c title=" " lineNumbers=1
      lv_timer_t * lv_timer_create_basic(void)
      ```

      **Returns:** <ApiLink name="lv_timer_t" display="lv_timer_t *" /> — pointer to the created timer
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_create" file="public/core/lv_timer.h" line="97" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L97">
      lv_timer_create [#lv_timer_create]

      Create a new lv\_timer

      ```c title=" " lineNumbers=1
      lv_timer_t * lv_timer_create(lv_timer_cb_t timer_xcb, uint32_t period, void *user_data)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name        | Type                             | Description                                                                                                                                                                               |
      | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | `timer_xcb` | <ApiLink name="lv_timer_cb_t" /> | a callback to call periodically. (the 'x' in the argument name indicates that it's not a fully generic function because it not follows the `func_name(object, callback, ...)` convention) |
      | `period`    | `uint32_t`                       | call period in ms unit                                                                                                                                                                    |
      | `user_data` | `void *`                         | custom parameter **May** be `NULL`.                                                                                                                                                       |

      **Returns:** <ApiLink name="lv_timer_t" display="lv_timer_t *" /> — pointer to the new timer
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_delete" file="public/core/lv_timer.h" line="103" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L103">
      lv_timer_delete [#lv_timer_delete]

      Delete a lv\_timer

      ```c title=" " lineNumbers=1
      void lv_timer_delete(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description                                |
      | ------- | ---------------------------------------------------- | ------------------------------------------ |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to an lv\_timer **May** be `NULL`. |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_pause" file="public/core/lv_timer.h" line="110" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L110">
      lv_timer_pause [#lv_timer_pause]

      Pause a timer. It is typically safe to call from an interrupt handler or a different thread.

      ```c title=" " lineNumbers=1
      void lv_timer_pause(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description             |
      | ------- | ---------------------------------------------------- | ----------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to an lv\_timer |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_resume" file="public/core/lv_timer.h" line="116" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L116">
      lv_timer_resume [#lv_timer_resume]

      Resume a timer.

      ```c title=" " lineNumbers=1
      void lv_timer_resume(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description             |
      | ------- | ---------------------------------------------------- | ----------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to an lv\_timer |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_ready" file="public/core/lv_timer.h" line="136" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L136">
      lv_timer_ready [#lv_timer_ready]

      Make a lv\_timer ready. It will not wait its period.

      ```c title=" " lineNumbers=1
      void lv_timer_ready(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description             |
      | ------- | ---------------------------------------------------- | ----------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer. |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_reset" file="public/core/lv_timer.h" line="164" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L164">
      lv_timer_reset [#lv_timer_reset]

      Reset a lv\_timer. It will be called the previously set period milliseconds later.

      ```c title=" " lineNumbers=1
      void lv_timer_reset(lv_timer_t *timer)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name    | Type                                                 | Description             |
      | ------- | ---------------------------------------------------- | ----------------------- |
      | `timer` | <ApiLink name="lv_timer_t" display="lv_timer_t *" /> | pointer to a lv\_timer. |
    </ApiMember>

    <ApiMember kind="function" name="lv_timer_enable" file="public/core/lv_timer.h" line="170" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L170">
      lv_timer_enable [#lv_timer_enable]

      Enable or disable the whole lv\_timer handling

      ```c title=" " lineNumbers=1
      void lv_timer_enable(bool en)
      ```

      <span className="sr-only">
        Parameters
      </span>

      | Name | Type   | Description                                                                 |
      | ---- | ------ | --------------------------------------------------------------------------- |
      | `en` | `bool` | true: lv\_timer handling is running, false: lv\_timer handling is suspended |
    </ApiMember>
  </ApiTab>
</ApiTabs>

Typedefs [#typedefs]

<ApiMember kind="typedef" name="lv_timer_cb_t" file="public/core/lv_timer.h" line="34" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L34">
  lv_timer_cb_t [#lv_timer_cb_t]

  ```c title=" " lineNumbers=1
  typedef void(* lv_timer_cb_t) (lv_timer_t *)
  ```

  Timers execute this type of functions.
</ApiMember>

<TypeUsedBy name="lv_timer_cb_t" count="2">
  * `lv_timer_create` — param `timer_xcb`
  * `lv_timer_set_cb` — param `timer_cb`
</TypeUsedBy>

<ApiMember kind="typedef" name="lv_timer_handler_resume_cb_t" file="public/core/lv_timer.h" line="39" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L39">
  lv_timer_handler_resume_cb_t [#lv_timer_handler_resume_cb_t]

  ```c title=" " lineNumbers=1
  typedef void(* lv_timer_handler_resume_cb_t) (void *data)
  ```

  Timer handler resume this type of function.
</ApiMember>

<TypeUsedBy name="lv_timer_handler_resume_cb_t" count="1">
  * `lv_timer_handler_set_resume_cb` — param `cb`
</TypeUsedBy>

Macros [#macros]

<ApiMember kind="macro" name="LV_NO_TIMER_READY" file="public/core/lv_timer.h" line="25" url="https://github.com/lvgl/lvgl/tree/e1a0ad863f29742359bc680d6a7d973448ec2285/include/lvgl/core/lv_timer.h#L25">
  LV_NO_TIMER_READY [#lv_no_timer_ready]

  ```c title=" " lineNumbers=1
  #define LV_NO_TIMER_READY 0xFFFFFFFF
  ```
</ApiMember>

Dependencies [#dependencies]

<FileIncludes includes="[&#x22;lv_conf_internal.h&#x22;, &#x22;lv_types.h&#x22;]" includedBy="[&#x22;lv_sysmon.h&#x22;, &#x22;lv_display.h&#x22;, &#x22;lv_indev.h&#x22;, &#x22;lvgl.h&#x22;]" />