Empty State
===========

+----------+---------------------------------+
| Author   | Nekhelesh Ramananthan           |
+----------+-------------+-------------------+
| License  | BSD License                     |
+----------+---------------------------------+
| Contact  | nik90@ubuntu.com                |
+----------+---------------------------------+
| Framework| ubuntu-sdk-14.10                |
+----------+---------------------------------+

This widget provides a standardized way to show an empty state (approved by Canonical designers) 
to improve the user experience and avoid showing a blank page. This way the user is not left starring 
a blank page but instead is shown the empty state which informs the user of situation along with some
recommendations.

For instance, in the clock app if the user has no alarms saved, then an empty state is shown and encourages
the user to create a new alarm.
  
Example:

.. code-block:: qml

    EmptyState {
        iconName: "alarm-clock"
        title: i18n.tr("No saved alarms")
        subTitle: i18n.tr("Tap the + icon to add an alarm")
        anchors.centerIn: parent
    }

.. image:: ../_images/emptystate.png
   :align: center

Properties
----------

- :ref:`iconName`: string
- :ref:`iconSource`: url
- :ref:`iconColor`: color
- :ref:`title`: string
- :ref:`subTitle`: string

Property Documentation
----------------------

.. _iconName:

iconName
^^^^^^^^

The name of the icon to display. Valid icon names can be found in the suru-icon-theme.

.. note:: If both :ref:`iconName` and :ref:`iconSource` are specified, then :ref:`iconName` will be ignored. 

.. _iconSource:

iconSource
^^^^^^^^^^

The source url of the icon to display. It has precedence over :ref:`iconName`. 

.. _iconColor:

iconColor
^^^^^^^^^

The color of the icon.

.. note:: This property only works if iconName is used.

.. _title:

title
^^^^^

The main message of the empty state. Try to keep this short and precise.

.. _subTitle:

subTitle
^^^^^^^^

A more descriptive message of the empty state. Usually the subtitle provides tips or instructions to perform an action to avoid the empty state.