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

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
+Message boxes act as pop-ups. They are built from a content area
-container, a title, an optional close button, a text and optional
+with a helper to add text, an optional header (which can have
-buttons.
+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
+The text will be broken into multiple lines and the height
-will be set automatically to include the text and the buttons.
+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`
+- Content, header, and footer: :ref:`lv_obj`
-- Close button: :ref:`lv_button`
+- Buttons: :ref:`lv_button`
-- Title and text: :ref:`lv_label`
+- Title and content text: :ref:`lv_label`
-- Buttons: :ref:`lv_buttonmatrix`
 
 .. _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)`
+:cpp:expr:`lv_msgbox_create(parent)` creates a message box.
-creates a message box.
+If ``parent`` is ``NULL`` the message box will be modal.
-
-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.
 
 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_content(lv_obj_t * obj);
-   lv_obj_t * lv_msgbox_get_close_btn(lv_obj_t * mbox);
+   lv_obj_t * lv_msgbox_get_title(lv_obj_t * obj);
-   lv_obj_t * lv_msgbox_get_text(lv_obj_t * mbox);
+   lv_obj_t * lv_msgbox_get_header(lv_obj_t * obj);
-   lv_obj_t * lv_msgbox_get_btns(lv_obj_t * mbox);
+   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
+No special events are sent by this widget.
-   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.
 
 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
+No *Keys* are processed by the object type.
-manually to a group if required.
 
 Learn more about :ref:`indev_keys`.
 

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
+
 

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);