.. _lv_msgbox:

=======================
Message box (lv_msgbox)
=======================

Overview
********

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 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.

.. _lv_msgbox_parts_and_styles:

Parts and Styles
****************

The message box is built from other widgets, so you can check these
widgets' documentation for details.

- Content, header, and footer: :ref:`lv_obj`
- Buttons: :ref:`lv_button`
- Title and content text: :ref:`lv_label`

.. _lv_msgbox_usage:

Usage
*****

Create a message box
--------------------

:cpp:expr:`lv_msgbox_create(parent)` creates a message box.
If ``parent`` is ``NULL`` the message box will be modal.

Get the parts
-------------

The building blocks of the message box can be obtained using the
following functions:

.. code:: c

   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
******

No special events are sent by this widget.

Learn more about :ref:`events`.

.. _lv_msgbox_keys:

Keys
****

No *Keys* are processed by the object type.

Learn more about :ref:`indev_keys`.

.. _lv_msgbox_example:

Example
*******

.. include:: ../examples/widgets/msgbox/index.rst

.. _lv_msgbox_api:

API
***