diff --git a/docs/src/details/auxiliary-modules/xml/events.rst b/docs/src/details/auxiliary-modules/xml/events.rst index d8e7d94935..41567def51 100644 --- a/docs/src/details/auxiliary-modules/xml/events.rst +++ b/docs/src/details/auxiliary-modules/xml/events.rst @@ -4,4 +4,48 @@ Events ====== -TODO +Overview +******** + +```` tags can be added as a child of any widget to react to user inputs or other value changes. + +Right now, only a single event type is supported to call user-defined callbacks. + +Usage +***** + +Call function +------------- + +User-defined functions can be called like this: + +.. code-block:: xml + + + + + + + +When the XML is loaded at runtime, the callback name needs to be mapped to a function by using: +``lv_xml_register_event_cb("my_callback_1", an_event_handler)`` + +The callback should have the standard LVGL event callback signature: +``void an_event_handler(lv_event_t * e);`` + +In the exported C code, it is assumed that there is a function with the exact name specified as the callback name. +For example, ``callback="my_callback_1"`` will be exported as: + +.. code-block:: c + void my_callback_1(lv_event_t * e); /* At the beginning of the exported file */ + + lv_obj_add_event_cb(obj, my_callback_1, LV_EVENT_CLICKED, "some_text"); + +For triggers, all LVGL event types are supported with straightforward mapping: + +- :cpp:expr:`LV_EVENT_ALL`: ``"all"`` +- :cpp:expr:`LV_EVENT_CLICKED`: ``"clicked"`` +- :cpp:expr:`LV_EVENT_PRESSED`: ``"pressed"`` +- etc. + +The ``user_data`` is optional. If omitted, ``NULL`` will be passed.