.. index:: label


*****
Label
*****

Label element
=============

A *label* element represents a label on the UI, it can be the child element of a *page*, a *fragment* or a *container* element.

Syntax of the *label* element
-----------------------------
..
  
  label <label-id> {<label-descriptor>}
  

where:

- The <label-id> is the name of the label.
- The <label-descriptor> defines the look of the *label* element.


.. index:: label refresh event

Events of the *label*
---------------------
The label is not an active UI element, but it supports following events:

- **valueChange**: using this event, the label value can be changed.

.. code-block:: scolvoscript
  :caption: Example event call to change the value of the label DescriptionLabel on page ExamplePage
  :linenos:

  
  function changeTheValueOfTheLabelDescription(labelValue) {
    fireEvent(createTargetEvent("DescriptionLabel", "onRefresh", labelValue), "ExamplePage");
  }
  
..

.. index:: label dictionary keys

Dictionary keys of the *label*
------------------------------
The UI values of the *label* element are in the dictionary. The corresponding key has the form of 'page_<page-name>[_<fragments-and-container-structure-to-label>]_<label-id>_defaultText'.

.. code-block:: properties
  :caption: Dictionary key definition for label example in the mobile_dictionary_en.properties file
  :linenos:

  
  page_ExamplePage_DescriptionLabel_defaultText=This is the UI value of the label with name DescriptionLabel
  
..

Syntax of the *label* descriptor
--------------------------------
The label descriptor can contain one or more attribute descriptors.

..
  
  (<attribute-descriptor>[,|;])+
  
..

where:

- Multiple <attirbute-descriptor> can be defined, the definitions are optionally separated by ',' or ';'.


Syntax of the label's attribute descriptor
-------------------------------------------

..
  
  <attirubte-name>: <attribute-value>

..

where:

- List of valid attribute names and values are defined by client device types below.

.. index:: label attributes

Valid *label* attribute names and values
----------------------------------------
The following table describes the valid attributes and its values for different client device types.

.. list-table:: Valid values
    :widths: 10 5 10 50
    :header-rows: 1

    * - Name
      - Description
      - Valid values
      - Example

    * - template
      - Defines the template to be used
      - display templates in 5 sizes ( N = 1..5): display<N>Primary, display<N>Secondary, display<N>Tertiary, display<N>Disabled;
        heading templates in 5 sizes ( N = 1..7): heading<N>Primary, heading<N>Secondary, heading<N>Tertiary, heading<N>Disabled;
        body-copy templates in 3 sizes ( N = 1..3): bodyCopy<N>Primary, bodyCopy<N>Secondary, bodyCopy<N>Tertiary, bodyCopy<N>Disabled;
        body-copy-condensed templates in 3 sizes ( N = 1..3): bodyCopy<N>CondensedPrimary, bodyCopy<N>CondensedSecondary, bodyCopy<N>CondensedTertiary, bodyCopy<N>CondensedDisabled
      - template: display1Primary,

    * - span
      - Defines the spacing of the element, if missing, then auto sizing is set
      - Numbers, e.g.: 0
      - span: 0;

    * - bold / isBoold
      - Defines if the font is bold or not
      - Boolean values: *true* or *false*
      - isBold: true;

    * - fontSize
      - Not supported anymore
      - 
      - 

    * - alignment
      - Defines the alignment of the label
      - Valid values are 'left', 'right' and 'center'
      - alignment: center;

Example *label* definition
--------------------------
The following code examples are defining a label and its value:

.. code-block:: scolvoscript
  :caption: Example label definition on a page
  :linenos:

  page ExamplePage {
    layout: vertical;
    template: fullscreen;

    label DescriptionLabel {
      template: display1Primary;
    }
  }
..

.. code-block:: properties
  :caption: Dictionary key definition for the example label
  :linenos:

  
  page_ExamplePage_DescriptionLabel_defaultText=Here and now!
  
..