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,  "{\"weight\":\"bold\",\"slant\":\"italic\"}" );
  58 label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
  59 ~~~
  60
  61 ~~~{.js}
  62 // JavaScript
  63
  64 label.fontFamily = "FreeSerif";
  65 label.fontStyle = "{\"weight\":\"bold\",\"slant\":\"italic\"}";
  66 label.pointSize = 12;
  67 ~~~
  68
  69 However the text control will fall-back to using the default font, if the requested font does not support the required scripts.
  70
  71 ### Font Styles
  72
  73 Setting a font size programmatically is not ideal for applications which support multiple
  74 screen resolutions and platforms which support multiple logical font sizes.  Also, any
  75 changes to the platform font settings will override any sizes that have been programmatically
  76 set.
  77
  78 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
  79
  80 ~~~{.cpp}
  81 // C++
  82 StyleManager styleManager = StyleManager::Get();
  83 styleManager.RequestThemeChange( "example-path/example.json" );
  84 ~~~
  85
  86 To change the font for standard text controls, this JSON syntax can be used:
  87
  88 ~~~{.json}
  89 {
  90   "styles":
  91   {
  92     "textlabel":
  93     {
  94       "fontFamily":"FreeSerif",
  95       "fontStyle":"{\"weight\":\"bold\",\"slant\":\"italic\"}",
  96       "pointSize":8
  97     }
  98   }
  99 }
 100 ~~~
 101
 102 However the same pointSize is unlikely to be suitable for all text controls in an application.
 103 To define custom styles for existing controls, simply set a style name for each case, and
 104 then provide a style override in JSON.
 105
 106 To provide flexibility for the end user, the platform offers a mechanism to alter the logical
 107 font size between 0 and 4 inclusive. This logical size is mapped to a physical size using the
 108 stylesheets, by appending FontSizeN to the style name. These sections ("textlabelFontSizeN")
 109 in the style sheet are applied after the base section ("textlabel"), so take precedence.
 110
 111 ~~~{.cpp}
 112   // C++
 113
 114   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
 115 ~~~
 116 ~~~{.js}
 117   // JavaScript
 118
 119   label.styleName = "customLabel"';
 120 ~~~
 121
 122 ~~~{.json}
 123 {
 124   "styles":
 125   {
 126     "textlabel":
 127     {
 128       "fontFamily":"FreeSerif",
 129       "fontStyle":"{\"weight\":\"bold\",\"slant\":\"italic\"}",
 130     },
 131
 132     "textlabelFontSize0":
 133     {
 134       "pointSize":8
 135     },
 136     "textlabelFontSize1":
 137     {
 138       "pointSize":10
 139     },
 140     "textlabelFontSize2":
 141     {
 142       "pointSize":15
 143     },
 144     "textlabelFontSize3":
 145     {
 146       "pointSize":19
 147     },
 148     "textlabelFontSize4":
 149     {
 150       "pointSize":25
 151     },
 152
 153     "customLabel":
 154     {
 155       "fontFamily":"TimesNewRoman",
 156       "fontStyle":"{\"weight\":\"regular\",\"slant\":\"regular\"}",
 157     },
 158     "customLabelFontSize0":
 159     {
 160       "pointSize":10
 161     },
 162     "customLabelFontSize1":
 163     {
 164       "pointSize":12
 165     },
 166     "customLabelFontSize2":
 167     {
 168       "pointSize":15
 169     },
 170     "customLabelFontSize3":
 171     {
 172       "pointSize":20
 173     },
 174     "customLabelFontSize4":
 175     {
 176       "pointSize":28
 177     }
 178   }
 179 }
 180 ~~~
 181
 182 In the example above, at platform logical text size 0, standard text labels will have pointSize 8, and custom labels will have pointSize 10.
 183
 184
 185 */