docs/content/shared-javascript-and-cpp-documentation/font-selection.md

   1 <!--
   2 /**-->
   3
   4 # Font Selection {#font-selection}
   5
   6 By default TextLabel or TextField will automatically select a suitable font from the platform.
   7 Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.
   8 Therefore you should expect the text control to select different fonts for each script.
   9
  10 Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
  11
  12 - FONT_FAMILY
  13   Is a string with the font's family name. i.e. *FreeSerif*
  14 - FONT_STYLE
  15   Is a json formatted string with the font's style. Possible *key, value* pairs are:
  16   + *width* Modifies the space between glyphs. Possible values are:
  17     - *ultraCondensed*
  18     - *extraCondensed*
  19     - *condensed*
  20     - *semiCondensed*
  21     - *normal*
  22     - *semiExpanded*
  23     - *expanded*
  24     - *extraExpanded*
  25     - *ultraExpanded*
  26   + *weight* Modifies the thickness or darkness of the glyphs. Possible values are:
  27     - *thin*
  28     - *ultraLight*
  29     - *extraLight*
  30     - *light*
  31     - *demiLight*
  32     - *semiLight*
  33     - *book*
  34     - *normal*
  35     - *regular*
  36     - *medium*
  37     - *demiBold*
  38     - *semiBold*
  39     - *bold*
  40     - *ultraBold*
  41     - *extraBold*
  42     - *black*
  43     - *heavy*
  44     - *extraBlack*
  45   + *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:
  46     - *normal*
  47     - *roman* Same as *normal*
  48     - *italic*
  49     - *oblique*
  50 - POINT_SIZE
  51   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.
  52
  53 ~~~{.cpp}
  54 // C++
  55
  56 label.SetProperty( TextLabel::Property::FONT_FAMILY, "FreeSerif" );
  57 label.SetProperty( TextLabel::Property::FONT_STYLE,
  58                    Property::Map().Add( "weight", "bold" )
  59                                   .Add( "slant", "italic" ) );
  60 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
  61 ~~~
  62
  63 ~~~{.js}
  64 // JavaScript
  65
  66 label.fontFamily = "FreeSerif";
  67 label.fontStyle = {
  68                     "weight" : "bold",
  69                     "slant"  : "italic"
  70                   };
  71 label.pointSize = 12;
  72 ~~~
  73
  74 However the text control will fall-back to using the default font, if the requested font does not support the required scripts.
  75
  76 ### Font Styles
  77
  78 Setting a font size programmatically is not ideal for applications which support multiple
  79 screen resolutions and platforms which support multiple logical font sizes.  Also, any
  80 changes to the platform font settings will override any sizes that have been programmatically
  81 set.
  82
  83 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
  84
  85 ~~~{.cpp}
  86 // C++
  87 StyleManager styleManager = StyleManager::Get();
  88 styleManager.RequestThemeChange( "example-path/example.json" );
  89 ~~~
  90
  91 To change the font for standard text controls, this JSON syntax can be used:
  92
  93 ~~~{.json}
  94 {
  95   "styles":
  96   {
  97     "textlabel":
  98     {
  99       "fontFamily":"FreeSerif",
 100       "fontStyle":
 101       {
 102         "weight":"bold",
 103         "slant":"italic"
 104       },
 105       "pointSize":8
 106     }
 107   }
 108 }
 109 ~~~
 110
 111 However the same pointSize is unlikely to be suitable for all text controls in an application.
 112 To define custom styles for existing controls, simply set a style name for each case, and
 113 then provide a style override in JSON.
 114
 115 To provide flexibility for the end user, the platform offers a mechanism to alter the logical
 116 font size between 0 and 4 inclusive. This logical size is mapped to a physical size using the
 117 stylesheets, by appending FontSizeN to the style name. These sections ("textlabelFontSizeN")
 118 in the style sheet are applied after the base section ("textlabel"), so take precedence.
 119
 120 ~~~{.cpp}
 121   // C++
 122
 123   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
 124 ~~~
 125 ~~~{.js}
 126   // JavaScript
 127
 128   label.styleName = "customLabel"';
 129 ~~~
 130
 131 ~~~{.json}
 132 {
 133   "styles":
 134   {
 135     "textlabel":
 136     {
 137       "fontFamily":"FreeSerif",
 138       "fontStyle":
 139       {
 140         "weight":"bold",
 141         "slant":"italic"
 142       },
 143     },
 144
 145     "textlabelFontSize0":
 146     {
 147       "pointSize":8
 148     },
 149     "textlabelFontSize1":
 150     {
 151       "pointSize":10
 152     },
 153     "textlabelFontSize2":
 154     {
 155       "pointSize":15
 156     },
 157     "textlabelFontSize3":
 158     {
 159       "pointSize":19
 160     },
 161     "textlabelFontSize4":
 162     {
 163       "pointSize":25
 164     },
 165
 166     "customLabel":
 167     {
 168       "fontFamily":"TimesNewRoman",
 169       "fontStyle":
 170       {
 171         "weight":"regular",
 172         "slant":"regular"
 173       },
 174     },
 175     "customLabelFontSize0":
 176     {
 177       "pointSize":10
 178     },
 179     "customLabelFontSize1":
 180     {
 181       "pointSize":12
 182     },
 183     "customLabelFontSize2":
 184     {
 185       "pointSize":15
 186     },
 187     "customLabelFontSize3":
 188     {
 189       "pointSize":20
 190     },
 191     "customLabelFontSize4":
 192     {
 193       "pointSize":28
 194     }
 195   }
 196 }
 197 ~~~
 198
 199 In the example above, at platform logical text size 0, standard text labels will have pointSize 8, and custom labels will have pointSize 10.
 200
 201
 202 */