From a246b47e5ae738b12c6bf12eaa6f86d550380167 Mon Sep 17 00:00:00 2001 From: Liam <30486941+liamHowatt@users.noreply.github.com> Date: Fri, 2 Aug 2024 00:21:26 -0400 Subject: [PATCH] docs(msgbox): update to reflect latest (#6603) --- docs/widgets/msgbox.rst | 65 ++++++++++++++++--------------- examples/widgets/msgbox/index.rst | 6 +++ src/widgets/msgbox/lv_msgbox.h | 12 +++--- 3 files changed, 45 insertions(+), 38 deletions(-) diff --git a/docs/widgets/msgbox.rst b/docs/widgets/msgbox.rst index 6310ad4a3..2821d8f44 100644 --- a/docs/widgets/msgbox.rst +++ b/docs/widgets/msgbox.rst @@ -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`. diff --git a/examples/widgets/msgbox/index.rst b/examples/widgets/msgbox/index.rst index 8056e5dc6..ece638269 100644 --- a/examples/widgets/msgbox/index.rst +++ b/examples/widgets/msgbox/index.rst @@ -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 + diff --git a/src/widgets/msgbox/lv_msgbox.h b/src/widgets/msgbox/lv_msgbox.h index 10040f0ff..e2f863ae9 100644 --- a/src/widgets/msgbox/lv_msgbox.h +++ b/src/widgets/msgbox/lv_msgbox.h @@ -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);