<!--
/**-->

# Font Selection {#font-selection}

By default TextLabel or TextField will automatically select a suitable font from the platform.
Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.
Therefore you should expect the text control to select different fonts for each script.

Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:

- FONT_FAMILY
  Is a string with the font's family name. i.e. *FreeSerif*
- FONT_STYLE
  Is a json formatted string with the font's style. Possible *key, value* pairs are:
  + *width* Modifies the space between glyphs. Possible values are:
    - *ultraCondensed*
    - *extraCondensed*
    - *condensed*
    - *semiCondensed*
    - *normal*
    - *semiExpanded*
    - *expanded*
    - *extraExpanded*
    - *ultraExpanded*
  + *weight* Modifies the thickness or darkness of the glyphs. Possible values are:
    - *thin*
    - *ultraLight*
    - *extraLight*
    - *light*
    - *demiLight*
    - *semiLight*
    - *book*
    - *normal*
    - *regular*
    - *medium*
    - *demiBold*
    - *semiBold*
    - *bold*
    - *ultraBold*
    - *extraBold*
    - *black*
    - *heavy*
    - *extraBlack*
  + *slant* Whether to use italics. Usually *italic* is a different font whilst the *oblique* has been generated by slanting the *normal* one. Possible values are:
    - *normal*
    - *roman* Same as *normal*
    - *italic*
    - *oblique*
- POINT_SIZE
  Is a float with the font's size in points. To get the point size from pixels, could use the formula: <em>point_size = 72 * pixels / vertical_dpi</em> where <em>vertical_dpi</em> is the device's vertical resolution in dots per inch.

~~~{.cpp}
// C++

label.SetProperty( TextLabel::Property::FONT_FAMILY, "FreeSerif" );
label.SetProperty( TextLabel::Property::FONT_STYLE,
                   Property::Map().Add( "weight", "bold" )
                                  .Add( "slant", "italic" ) );
label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
~~~

~~~{.js}
// JavaScript

label.fontFamily = "FreeSerif";
label.fontStyle = {
                    "weight" : "bold",
                    "slant"  : "italic"
                  };
label.pointSize = 12;
~~~

However the text control will fall-back to using the default font, if the requested font does not support the required scripts.

### Font Styles

Setting a font size programmatically is not ideal for applications which support multiple
screen resolutions and platforms which support multiple logical font sizes.  Also, any
changes to the platform font settings will override any sizes that have been programmatically
set.

A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:

~~~{.cpp}
// C++
StyleManager styleManager = StyleManager::Get();
styleManager.RequestThemeChange( "example-path/example.json" );
~~~

To change the font for standard text controls, this JSON syntax can be used:

~~~{.json}
{
  "styles":
  {
    "textlabel":
    {
      "fontFamily":"FreeSerif",
      "fontStyle":
      {
        "weight":"bold",
        "slant":"italic"
      },
      "pointSize":8
    }
  }
}
~~~

However the same pointSize is unlikely to be suitable for all text controls in an application.
To define custom styles for existing controls, simply set a style name for each case, and
then provide a style override in JSON.

To provide flexibility for the end user, the platform offers a mechanism to alter the logical
font size between 0 and 4 inclusive. This logical size is mapped to a physical size using the
stylesheets, by appending FontSizeN to the style name. These sections ("textlabelFontSizeN")
in the style sheet are applied after the base section ("textlabel"), so take precedence.

~~~{.cpp}
  // C++

  label.SetProperty( Control::Property::STYLE_NAME, "custom" );
~~~
~~~{.js}
  // JavaScript

  label.styleName = "customLabel"';
~~~

~~~{.json}
{
  "styles":
  {
    "textlabel":
    {
      "fontFamily":"FreeSerif",
      "fontStyle":
      {
        "weight":"bold",
        "slant":"italic"
      },
    },

    "textlabelFontSize0":
    {
      "pointSize":8
    },
    "textlabelFontSize1":
    {
      "pointSize":10
    },
    "textlabelFontSize2":
    {
      "pointSize":15
    },
    "textlabelFontSize3":
    {
      "pointSize":19
    },
    "textlabelFontSize4":
    {
      "pointSize":25
    },

    "customLabel":
    {
      "fontFamily":"TimesNewRoman",
      "fontStyle":
      {
        "weight":"regular",
        "slant":"regular"
      },
    },
    "customLabelFontSize0":
    {
      "pointSize":10
    },
    "customLabelFontSize1":
    {
      "pointSize":12
    },
    "customLabelFontSize2":
    {
      "pointSize":15
    },
    "customLabelFontSize3":
    {
      "pointSize":20
    },
    "customLabelFontSize4":
    {
      "pointSize":28
    }
  }
}
~~~

In the example above, at platform logical text size 0, standard text labels will have pointSize 8, and custom labels will have pointSize 10.


*/