Label control: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Dankula
 
(36 intermediate revisions by 16 users not shown)
Line 1: Line 1:
<section begin="main content" />
The label control is used for displaying text in XBMC. You can choose the font, size, colour, location and contents of the text to be displayed.
The label control is used for displaying text in XBMC. You can choose the font, size, colour, location and contents of the text to be displayed.
===Example===
=== Example ===
<xml>
<syntaxhighlight lang="XML" enclose="div">
   <control>
   <control type="label" id="1">
         <description>My First label</description>
         <description>My First label</description>
         <type>label</type>
         <left>80</left>
        <id>1</id>
         <top>60</top>
        <posx>80</posx>
         <posy>60</posy>
         <width>250</width>
         <width>250</width>
         <visible>true</visible>
         <visible>true</visible>
         <align>center</align>
         <align>center</align>
        <aligny>center</aligny>
         <scroll>false</scroll>
         <scroll>false</scroll>
         <label>6</label>
         <label fallback="$LOCALIZE[123]">$INFO[MusicPlayer.Artist]</label>
         <number></number>
         <angle>30</angle>
        <info>MusicPlayer.Artist</info>
         <haspath>false</haspath>
         <haspath>false</haspath>
         <font>font14</font>
         <font>font14</font>
         <textcolor>FFB2D4F5</textcolor>
         <textcolor>FFB2D4F5</textcolor>
        <shadowcolor>ff000000</shadowcolor>
        <wrapmultiline>false</wrapmultiline>
        <scrollspeed>50</scrollspeed>
        <scrollsuffix> - </scrollsuffix>
   </control>
   </control>
</xml>
</syntaxhighlight>
===Multi-Line Labels===
 
=== Auto size labels ===
 
Wrapping your label in a grouplist with the auto width and appropriate minium and maximum values. Allows the labels width to dynamically change relevalant to how long the label text is. This allows a image or other control to be alligned to the right of the actual label text no matter how wide the label is.
 
<syntaxhighlight lang="XML" enclose="div">
  <width min="29" max="200">auto</width>
</syntaxhighlight>
 
As of XBMC Gotham, simply specifying <width>auto</width> is also supported.
 
=== Multi-line labels ===
If you want your label control to span multiple lines, you can insert a new line character in your label. For example:
If you want your label control to span multiple lines, you can insert a new line character in your label. For example:
<xml>
 
   <label>This will be on the first line&#10;And this will be on the second line</label>
<syntaxhighlight lang="XML" enclose="div">
</xml>
   <label>This will be on the first line[CR]And this will be on the second line</label>
</syntaxhighlight>
 
Also, if you want your label control to conform to the <width> parameter, but still want to be able to give it more content than will fit on one line, then setting:
Also, if you want your label control to conform to the <width> parameter, but still want to be able to give it more content than will fit on one line, then setting:
<xml>
 
<syntaxhighlight lang="XML" enclose="div">
   <wrapmultiline>true</wrapmultiline>
   <wrapmultiline>true</wrapmultiline>
</xml>
</syntaxhighlight>
will cause the text to be cut up (at the spaces in the text) onto multiple lines. Note that if a single word is larger than <width> then it will not be cut, and will still overflow.
will cause the text to be cut up (at the spaces in the text) onto multiple lines. Note that if a single word is larger than <width> then it will not be cut, and will still overflow.


===Tag Descriptions===
=== Available tags ===
Note that each tag is '''lower case''' only. This is important, as xml tags are case-sensitive.
In addition to the '''[[Default Control Tags]]''' the following tags are available. Note that each tag is '''lower case''' only. This is important, as xml tags are case'''-'''sensitive.


{| class="dtable"
{| class="prettytable"
|- class="userrow"
! Tag
| class="usercell" | '''description'''
! Description
| class="usercell" | Only used to make things clear for the skinner. Not read by XBMC at all.
|-
|- class="userrow"
! align
| class="usercell" | '''type'''
| Can be left, right, or center. Aligns the text within the given label <code><width></code>. Defaults to left
| class="usercell" | Specifies the control type
|-
|- class="userrow"
! aligny
| class="usercell" | '''id'''
| Can be top or center. Aligns the text within its given label <code><height></code>. Defaults to top
| class="usercell" | Specifies the control's id. The value this takes depends on the control type, and the window that you are using the control on. There are special control id's that must be present in each window. Any other controls that the skinner adds can be any id they like.
|-
|- class="userrow"
! scroll
| class="usercell" | '''posx'''
| When true, the text will scroll if longer than the label's <code><width></code>. If false, the text will be truncated. Defaults to false.
| class="usercell" | Specifies where the left of the label should be drawn. This is offset from the window's coordinates (normally the left edge of the screen, or 0). In the case of <align>right</align> however, this specifies the '''right''' of the label.
|-
|- class="userrow"
! label
| class="usercell" | '''posy'''
| Specifies the text which should be drawn. You should specify an entry from the strings.xml here (either the Kodi strings.xml or your skin's strings.xml file). The fallback attribute will be used when the infolabel returns empty. You can use the full [[Label Formatting|label formatting syntax]] and [[Label Parsing|you may also specify more than one piece of information here by using the $INFO and $LOCALIZE formats.]]
| class="usercell" | Specifies where the top edge of the label should be drawn. This is offset from the window's coordinates (normally the top edge of the screen, or 0).
|-
|- class="userrow"
! info
| class="usercell" | '''width'''
| Specifies the information that should be presented. Kodi will <span class="nobr">auto-fill</span> in this info in place of the <code><label></code>. [[InfoLabels|See here for more information.]]
| class="usercell" | Specifies the width that should be used to draw the label. If the text is longer than the label, then it will either be truncated (ending in ...) or will scroll, depending on the <scroll> tag setting.
|-
|- class="userrow"
! number
| class="usercell" | '''visible'''
| 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 <code><label></code> will be used to lookup in strings.xml)
| class="usercell" |
|-
Specifies a condition as to when this control will be visible. Can be true, false, or a condition. [[Conditional Visibility|See here for more information.]] Defaults to true.
! angle
|- class="userrow"
| The angle the text should be rendered at, in degrees. A value of 0 is horizontal.
| class="usercell" | '''animation'''
|-
| class="usercell" |
! haspath
Specifies the animation to be run when the control enters a particular state. [[Animating Your Skin|See here for more information.]]
| 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.
|- class="userrow"
|-
| class="usercell" | '''align'''
! font
| class="usercell" | Can be left, right, or center. Aligns the text within the given label <width>. Defaults to left
| Specifies the font to use from the font.xml file.
|- class="userrow"
|-
| class="usercell" | '''scroll'''
! textcolor
| class="usercell" | When true, the text will scroll if longer than the label's <width>. If false, the text will be truncated. Defaults to false.
| Specifies the color the text should be, in hex AARRGGBB format, or a name from the [[Colour Themes|colour theme.]]
|- class="userrow"
|-
| class="usercell" | '''label'''
! shadowcolor
| class="usercell" |
| Specifies the color of the drop shadow on the text, in AARRGGBB format, or a name from the [[Colour Themes|colour theme.]]
Specifies the text which should be drawn. You should specify an entry from the strings.xml here, however you may also specify a piece of text yourself if you wish, though ofcourse it will not be localisable. [[Label Parsing|You may also specify more than one piece of information here by using the $INFO and $LOCALIZE formats.]]
|-
|- class="userrow"
! wrapmultiline
| class="usercell" | '''info'''
| If true, any text that doesn't fit on one line will be wrapped onto multiple lines.
| class="usercell" |
|-
Specifies the information that should be presented. XBMC will <span class="nobr">auto-fill</span> in this info in place of the <label>. [[InfoLabels|See here for more information.]]
! scrollspeed
|- class="userrow"
| Scroll speed of text in pixels per second. Defaults to 60.
| class="usercell" | '''number'''
|-
| class="usercell" | 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 <label> will be used to lookup in strings.xml)
! scrollsuffix
|- class="userrow"
| Specifies the suffix used in scrolling labels. Defaults to " <nowiki>|</nowiki> ".
| class="usercell" | '''haspath'''
| class="usercell" | 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.
|- class="userrow"
| class="usercell" | '''font'''
| class="usercell" | Specifies the font to use from the font.xml file.
|- class="userrow"
| class="usercell" | '''textcolor'''
| class="usercell" | Specifies the color the text should be, in hex AARRGGBB format.
|- class="userrow"
| class="usercell" | '''shadowcolor'''
| class="usercell" | Specifies the color of the drop shadow on the text, in AARRGGBB format.
|- class="userrow"
| class="usercell" | '''angle'''
| class="usercell" | The angle the text should be rendered at, in degrees. A value of 0 is horizontal.
|- class="userrow"
| class="usercell" | '''wrapmultiline'''
| class="usercell" | If true, any text that doesn't fit on one line will be wrapped onto multiple lines.
|}
|}
<section end="main content" />
== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]
[[Category:Skin development]]

Revision as of 22:30, 18 April 2020

The label control is used for displaying text in XBMC. You can choose the font, size, colour, location and contents of the text to be displayed.

Example

  <control type="label" id="1">
        <description>My First label</description>
        <left>80</left>
        <top>60</top>
        <width>250</width>
        <visible>true</visible>
        <align>center</align>
        <aligny>center</aligny>
        <scroll>false</scroll>
        <label fallback="$LOCALIZE[123]">$INFO[MusicPlayer.Artist]</label>
        <angle>30</angle>
        <haspath>false</haspath>
        <font>font14</font>
        <textcolor>FFB2D4F5</textcolor>
        <shadowcolor>ff000000</shadowcolor>
        <wrapmultiline>false</wrapmultiline>
        <scrollspeed>50</scrollspeed>
        <scrollsuffix> - </scrollsuffix>
  </control>

Auto size labels

Wrapping your label in a grouplist with the auto width and appropriate minium and maximum values. Allows the labels width to dynamically change relevalant to how long the label text is. This allows a image or other control to be alligned to the right of the actual label text no matter how wide the label is.

   <width min="29" max="200">auto</width>

As of XBMC Gotham, simply specifying <width>auto</width> is also supported.

Multi-line labels

If you want your label control to span multiple lines, you can insert a new line character in your label. For example:

   <label>This will be on the first line[CR]And this will be on the second line</label>

Also, if you want your label control to conform to the <width> parameter, but still want to be able to give it more content than will fit on one line, then setting:

   <wrapmultiline>true</wrapmultiline>

will cause the text to be cut up (at the spaces in the text) onto multiple lines. Note that if a single word is larger than <width> then it will not be cut, and will still overflow.

Available tags

In addition to the Default Control Tags the following tags are available. Note that each tag is lower case only. This is important, as xml tags are case-sensitive.

Tag Description
align Can be left, right, or center. Aligns the text within the given label <width>. Defaults to left
aligny Can be top or center. Aligns the text within its given label <height>. Defaults to top
scroll When true, the text will scroll if longer than the label's <width>. If false, the text will be truncated. Defaults to false.
label Specifies the text which should be drawn. You should specify an entry from the strings.xml here (either the Kodi strings.xml or your skin's strings.xml file). The fallback attribute will be used when the infolabel returns empty. You can use the full label formatting syntax and you may also specify more than one piece of information here by using the $INFO and $LOCALIZE formats.
info Specifies the information that should be presented. Kodi will auto-fill in this info in place of the <label>. See here for more information.
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 <label> will be used to lookup in strings.xml)
angle The angle the text should be rendered at, in degrees. A value of 0 is horizontal.
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.
font Specifies the font to use from the font.xml file.
textcolor Specifies the color the text should be, in hex AARRGGBB format, or a name from the colour theme.
shadowcolor Specifies the color of the drop shadow on the text, in AARRGGBB format, or a name from the colour theme.
wrapmultiline If true, any text that doesn't fit on one line will be wrapped onto multiple lines.
scrollspeed Scroll speed of text in pixels per second. Defaults to 60.
scrollsuffix Specifies the suffix used in scrolling labels. Defaults to " | ".


See also

Development: