xbmc/guilib/GUILabelControl.dox

   1 /*!
   2
   3 \page Label_Control Label Control
   4 \brief **Used to show some lines of text.**
   5
   6 \tableofcontents
   7
   8 The label control is used for displaying text in Kodi. You can choose the font,
   9 size, colour, location and contents of the text to be displayed.
  10
  11
  12 --------------------------------------------------------------------------------
  13 \section Label_Control_sect1 Example
  14
  15 ~~~~~~~~~~~~~
  16   <control type="label" id="1">
  17         <description>My First label</description>
  18         <posx>80</posx>
  19         <posy>60</posy>
  20         <width>250</width>
  21         <visible>true</visible>
  22         <align>center</align>
  23         <aligny>center</aligny>
  24         <scroll>false</scroll>
  25         <label>6</label>
  26         <info>MusicPlayer.Artist</info>
  27         <number></number>
  28         <angle>30</angle>
  29         <haspath>false</haspath>
  30         <font>font14</font>
  31         <textcolor>FFB2D4F5</textcolor>
  32         <shadowcolor>ff000000</shadowcolor>
  33         <wrapmultiline>false</wrapmultiline>
  34         <scrollspeed>50</scrollspeed>
  35         <scrollsuffix> - </scrollsuffix>
  36   </control>
  37 ~~~~~~~~~~~~~
  38
  39
  40 --------------------------------------------------------------------------------
  41 \section Label_Control_sect2 Auto size labels
  42 Wrapping your label in a grouplist with the auto width and appropriate minimum
  43 and maximum values. Allows the labels width to dynamically change relative to
  44 how long the label text is. This allows a image or other control to be aligned
  45 to the right of the actual label text no matter how wide the label is.
  46
  47 ~~~~~~~~~~~~~
  48    <width min="29" max="200">auto</width>
  49 ~~~~~~~~~~~~~
  50
  51 As of XBMC Gotham, simply specifying <b>`<width>auto</width>`</b> is also supported.
  52
  53
  54 --------------------------------------------------------------------------------
  55 \section Label_Control_sect3 Multi-line labels
  56
  57 If you want your label control to span multiple lines, you can insert a new line
  58 character in your label. For example:
  59
  60 ~~~~~~~~~~~~~
  61    <label>This will be on the first line[CR]And this will be on the second line</label>
  62 ~~~~~~~~~~~~~
  63
  64 Also, if you want your label control to conform to the <b>`<width>`</b> parameter, but still
  65 want to be able to give it more content than will fit on one line, then setting:
  66
  67 ~~~~~~~~~~~~~
  68    <wrapmultiline>true</wrapmultiline>
  69 ~~~~~~~~~~~~~
  70
  71 will cause the text to be cut up (at the spaces in the text) onto multiple lines.
  72 Note that if a single word is larger than <b>`<width>`</b> then it will not be cut, and
  73 will still overflow.
  74
  75
  76 --------------------------------------------------------------------------------
  77 \section Label_Control_sect4 Available tags
  78
  79 In addition to the [Default Control Tags](http://kodi.wiki/view/Default_Control_Tags)
  80 the following tags are available. Note that each tag is **lower case** only. This is
  81 important, as `xml` tags are case-sensitive.
  82
  83 | Tag           | Description                                                   |
  84 |--------------:|:--------------------------------------------------------------|
  85 | align         | Can be left, right, or center. Aligns the text within the given label <b>`<width>`</b>. Defaults to left
  86 | aligny        | Can be top or center. Aligns the text within its given label <b>`<height>`</b>. Defaults to top
  87 | scroll        | When true, the text will scroll if longer than the label's <b>`<width>`</b>. If false, the text will be truncated. Defaults to false.
  88 | label         | Specifies the text which should be drawn. You should specify an entry from the strings.po here (either the Kodi strings.po or your skin's strings.po file), however you may also hardcode a piece of text also if you wish, though of course it will not be localisable. You can use the full [label formatting syntax](http://kodi.wiki/view/Label_Formatting) and [you may also specify more than one piece of information here by using the $INFO and $LOCALIZE formats](http://kodi.wiki/view/Label_Parsing).
  89 | info          | Specifies the information that should be presented. Kodi will auto-fill in this info in place of the <b>`<label>`</b>. [See here for more information](http://kodi.wiki/view/InfoLabels).
  90 | number        | Specifies a number that should be presented. This is just here to allow a skinner to use a number rather than a text label (as any number given to <b>`<label>`</b> will be used to lookup in strings.po)
  91 | angle         | The angle the text should be rendered at, in degrees. A value of 0 is horizontal.
  92 | haspath       | Specifies whether or not this label is filled with a path. Long paths are shortened by compressing the file path while keeping the actual filename full length.
  93 | font          | Specifies the font to use from the font.xml file.
  94 | textcolor     | Specifies the color the text should be, in hex **AARRGGBB** format, or a name from the [colour theme](http://kodi.wiki/view/Colour_Themes).
  95 | shadowcolor   | Specifies the color of the drop shadow on the text, in **AARRGGBB** format, or a name from the [colour theme](http://kodi.wiki/view/Colour_Themes).
  96 | wrapmultiline | If true, any text that doesn't fit on one line will be wrapped onto multiple lines.
  97 | scrollspeed   | Scroll speed of text in pixels per second. Defaults to 60.
  98 | scrollsuffix  | Specifies the suffix used in scrolling labels. Defaults to <b>`"¦"`</b>.
  99
 100
 101
 102 --------------------------------------------------------------------------------
 103 \section Label_Control_sect5 See also
 104
 105
 106 #### Development:
 107
 108 - [Add-on development](http://kodi.wiki/view/Add-on_development)
 109 - [Skinning](http://kodi.wiki/view/Skinning)
 110
 111
 112 */