github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(msgbox): update to reflect latest (#6603)

Browse Source
This commit is contained in:
Liam
2024-08-02 00:21:26 -04:00
committed by GitHub
parent 89f2ff6701
commit a246b47e5a
3 changed files with 45 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/widgets/msgbox.rst
View File

@@ -7,12 +7,14 @@ Message box (lv_msgbox)
Overview
********
The Message boxes act as pop-ups. They are built from a background
container, a title, an optional close button, a text and optional
buttons.
Message boxes act as pop-ups. They are built from a content area
with a helper to add text, an optional header (which can have
a title, a close button, and other buttons), and an optional footer
with buttons.
The text will be broken into multiple lines automatically and the height
will be set automatically to include the text and the buttons.
The text will be broken into multiple lines and the height
will be set automatically. If the height
is set manually, the content will become scrollable.
The message box can be modal (blocking clicks on the rest of the screen)
or not modal.
@@ -25,10 +27,9 @@ Parts and Styles
The message box is built from other widgets, so you can check these
widgets' documentation for details.
- Background: :ref:`lv_obj`
- Close button: :ref:`lv_button`
- Title and text: :ref:`lv_label`
- Buttons: :ref:`lv_buttonmatrix`
- Content, header, and footer: :ref:`lv_obj`
- Buttons: :ref:`lv_button`
- Title and content text: :ref:`lv_label`
.. _lv_msgbox_usage:
@@ -38,15 +39,8 @@ Usage
Create a message box
--------------------
:cpp:expr:`lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn)`
creates a message box.
If ``parent`` is ``NULL`` the message box will be modal. ``title`` and
``txt`` are strings for the title and the text. ``btn_txts[]`` is an
array with the buttons' text.
E.g. :cpp:expr:`const char * btn_txts[] = {"Ok", "Cancel", NULL}`.
``add_close_btn`` can be ``true`` or ``false`` to add/don't add a close button.
:cpp:expr:`lv_msgbox_create(parent)` creates a message box.
If ``parent`` is ``NULL`` the message box will be modal.
Get the parts
-------------
@@ -56,29 +50,37 @@ following functions:
.. code:: c
lv_obj_t * lv_msgbox_get_title(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_close_btn(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_text(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_btns(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_content(lv_obj_t * obj);
lv_obj_t * lv_msgbox_get_title(lv_obj_t * obj);
lv_obj_t * lv_msgbox_get_header(lv_obj_t * obj);
lv_obj_t * lv_msgbox_get_footer(lv_obj_t * obj);
Functions that add something to the message box return the newly added object:
.. code:: c
lv_obj_t * lv_msgbox_add_text(lv_obj_t * obj, const char * text);
lv_obj_t * lv_msgbox_add_title(lv_obj_t * obj, const char * title);
lv_obj_t * lv_msgbox_add_close_button(lv_obj_t * obj);
lv_obj_t * lv_msgbox_add_header_button(lv_obj_t * obj, const void * icon);
lv_obj_t * lv_msgbox_add_footer_button(lv_obj_t * obj, const char * text);
Close the message box
---------------------
:cpp:expr:`lv_msgbox_close(msgbox)` closes (deletes) the message box.
:cpp:expr:`lv_msgbox_close_async(msgbox)` closes (deletes) the message box
asynchronously. This is useful if you want the message box to close the on
the next call to ``lv_timer_handler`` instead of immediately.
.. _lv_msgbox_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` is sent by the buttons if one of them is
clicked. :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` is enabled on the buttons so
you can add events to the message box itself. In the event handler,
:cpp:expr:`lv_event_get_target(e)` will return the button matrix and
:cpp:expr:`lv_event_get_current_target(e)` will return the message box.
:cpp:expr:`lv_msgbox_get_active_button(msgbox)` and
:cpp:expr:`lv_msgbox_get_active_button_text(msgbox)` can be used to get the
index and text of the clicked button.
No special events are sent by this widget.
Learn more about :ref:`events`.
@@ -87,8 +89,7 @@ Learn more about :ref:`events`.
Keys
****
Keys have effect on the close button and button matrix. You can add them
manually to a group if required.
No *Keys* are processed by the object type.
Learn more about :ref:`indev_keys`.

6
examples/widgets/msgbox/index.rst
View File

@@ -5,4 +5,10 @@ Simple Message box
.. lv_example:: widgets/msgbox/lv_example_msgbox_1
:language: c
Scrolling and styled Message box
--------------------------------
.. lv_example:: widgets/msgbox/lv_example_msgbox_2
:language: c

12
src/widgets/msgbox/lv_msgbox.h
View File

@@ -19,7 +19,7 @@ extern "C" {
/*Testing of dependencies*/
#if LV_USE_BUTTONMATRIX == 0
#error "lv_mbox: lv_btnm is required. Enable it in lv_conf.h (LV_USE_BUTTONMATRIX 1) "
#error "lv_mbox: lv_buttonmatrix is required. Enable it in lv_conf.h (LV_USE_BUTTONMATRIX 1) "
#endif
#if LV_USE_LABEL == 0
@@ -56,7 +56,7 @@ LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_msgbox_backdrop_class;
/**
* Create an empty message box
* @param parent the parent of the message box
* @param parent the parent or NULL to create a modal msgbox
* @return the created message box
*/
lv_obj_t * lv_msgbox_create(lv_obj_t * parent);
@@ -78,7 +78,7 @@ lv_obj_t * lv_msgbox_add_title(lv_obj_t * obj, const char * title);
lv_obj_t * lv_msgbox_add_header_button(lv_obj_t * obj, const void * icon);
/**
* Add a text to the content area of message box. Multiply texts will be created below each other.
* Add a text to the content area of message box. Multiple texts will be created below each other.
* @param obj pointer to a message box
* @param text text to add
* @return the created button
@@ -94,7 +94,7 @@ lv_obj_t * lv_msgbox_add_text(lv_obj_t * obj, const char * text);
lv_obj_t * lv_msgbox_add_footer_button(lv_obj_t * obj, const char * text);
/**
* Add a close button to the message box. It also create a header.
* Add a close button to the message box. It also creates a header.
* @param obj pointer to a message box
* @return the created close button
*/
@@ -117,14 +117,14 @@ lv_obj_t * lv_msgbox_get_footer(lv_obj_t * obj);
/**
* Get the content widget
* @param obj pointer to a message box
* @return the content, or NULL if not exists
* @return the content
*/
lv_obj_t * lv_msgbox_get_content(lv_obj_t * obj);
/**
* Get the title label
* @param obj pointer to a message box
* @return the title, or NULL if not exists
* @return the title, or NULL if it does not exist
*/
lv_obj_t * lv_msgbox_get_title(lv_obj_t * obj);