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 screen resolutions etc.
  74 A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
  75
  76 ~~~{.cpp}
  77 // C++
  78 StyleManager styleManager = StyleManager::Get();
  79 styleManager.RequestThemeChange( "example-path/example.json" );
  80 ~~~
  81
  82 To change the font for standard text controls, this JSON syntax can be used:
  83
  84 ~~~{.json}
  85 {
  86   "styles":
  87   {
  88     "textlabel":
  89     {
  90       "fontFamily":"FreeSerif",
  91       "fontStyle":"{\"weight\":\"bold\",\"slant\":\"italic\"}",
  92       "pointSize":8
  93     }
  94   }
  95 }
  96 ~~~
  97
  98 However the same pointSize is unlikely to be suitable for all text controls in an application.
  99 To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
 100
 101 ~~~{.cpp}
 102   // C++
 103
 104   label.SetProperty( Control::Property::STYLE_NAME, "custom" );
 105 ~~~
 106 ~~~{.js}
 107   // JavaScript
 108
 109   label.styleName = "custom"';
 110 ~~~
 111
 112 ~~~{.json}
 113 {
 114   "styles":
 115   {
 116     "textlabel":
 117     {
 118       "fontFamily":"FreeSerif",
 119       "fontStyle":"{\"weight\":\"bold\",\"slant\":\"italic\"}",
 120       "pointSize":8
 121     },
 122
 123     "custom":
 124     {
 125       "pointSize":10
 126     }
 127   }
 128 }
 129 ~~~
 130
 131 In the example above, standard text labels will have pointSize 8, and "custom" labels will have pointSize 10.
 132
 133 */