skins2-howto.xml 73.1 KB
Newer Older
1 2 3
<?xml version="1.0" encoding="iso8859-1" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">

4 5
<!-- vim: set ts=2 sts=2 sw=2 et -->

6 7 8 9 10 11 12
<article id="skin-creation-howto">

<articleinfo>

<title>HowTo create your own skin</title>

<copyright>
13
<year>2004-2013</year>
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
<holder>
the VideoLAN project
</holder>
</copyright>

<abstract>
<para>
Skin creation HowTo
</para>
</abstract>

<legalnotice>
<para>
Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version. The text of the license
can be found on <ulink url="http://www.gnu.org/copyleft/gpl.html">the GNU
website</ulink>.
</para>
</legalnotice>

<authorgroup>
  <author>
  <firstname>Olivier</firstname>
  <surname>Teulière</surname>
  </author>
</authorgroup>

<keywordset>
44
    <keyword>VLC</keyword>
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
    <keyword>Skin</keyword>
    <keyword>XML</keyword>
    <keyword>Bezier</keyword>
</keywordset>

</articleinfo>

<toc></toc>

<sect1><title>Basic principles</title>

<para>A skin (or theme, the two words have almost the same meaning) for VLC is made of:</para>

<itemizedlist>
  <listitem><para>many PNG (Portable Network Graphics) files, for the images of the different states of the controls,</para></listitem>
  <listitem><para>font files in the TTF (TrueType Font) format,</para></listitem>
  <listitem><para>a XML file describing the logical structure of the skin (which bitmaps correspond to which controls, where to place buttons, sliders, and so on) and its behaviour (what happens when the user clicks on a button, etc.).</para></listitem>
</itemizedlist>

<para>Those of you who have already made skins for other software should have no
difficulty to understand how VLC skins work.</para>

</sect1>

<sect1>
<title>The bitmaps</title>

72
<para>Basically, you need one bitmap file (in PNG format) by state of control. For example, with a <link linkend="Image">Image</link> control you need 1 image, with a <link linkend="Button">Button</link> control you need 3 images (for the up, down and mouseover states). The same bitmap file can be used for many controls, using <link linkend="SubBitmap">sub-bitmaps</link>.</para>
73 74 75 76 77

<para>The PNG format allows setting a transparency mask, which will be used wherever the image needs to be displayed (only non-transparent parts will be drawn). In addition, you can also specify a transparency color in the XML file: the bitmap will be considered as transparent wherever this color appears in the bitmap file.</para>

<note><para>Both the transparency mask and the transparent color will be taken into acount, so if the transparency mask is correctly set in the bitmap file you need to choose a unused color for the transparency color.</para></note>

78 79
<note><para>Starting from VLC 0.8.5, it is not anymore necessary to use PNG format for the bitmap files: most common formats are supported. Using PNG format is still recommended, for compatibility with older VLC versions.</para></note>

80 81 82 83 84 85 86
</sect1>

<sect1>
<title>The XML file</title>

<para>XML is a markup language, like HTML. It won't be explained here any further, please use Google if you don't know what XML is. You'll see, it is rather easy to understand.</para>

Christophe Mutricy's avatar
Christophe Mutricy committed
87
<para>The XML file used for the VLC skins follows a predefined DTD. You can find this DTD <ulink url="http://git.videolan.org/gitweb.cgi?p=vlc.git;a=blob;f=share/skins2/skin.dtd;hb=HEAD">in VLC Git</ulink>, and its reading is strongly advised, since it contains the default values used for the parameters. A skin that does not follow the DTD with which VLC was compiled won't be loaded by VLC (and it might even crash it...).</para>
88 89 90 91 92

<para>For a better undestanding of what follows, you should have a look at the DTD <!--(the last version is available on <ulink url="FIXME">TODO</ulink>) -->and/or at an example of valid XML skin<!-- TODO: link to the current DTD -->.</para>

<para>OK, let's go for an enumeration of the different tags and their attributes:</para>

93
<sect2 id="Theme">
94 95
  <title>Theme</title>
  <para>Main tag, for global attributes</para>
96
      <sect3 id="themeversion">
97 98 99
      <title>version</title>
      <para>Version of the DTD used when making the skin, such as "2.0" (you can find the version in the <!--TODO: link-->DTD itself). This number might be used in the future to provide a better backward compatibility with older skins.</para>
      <para><emphasis>Required.</emphasis></para>
100 101
    </sect3>
    <sect3 id="themetooltipfont">
102 103 104
      <title>tooltipfont</title>
      <para>Identifiant of a <link linkend="Font">Font</link> or <link linkend="BitmapFont">BitmapFont</link>, used for the tooltips (beware that any character not present in a <link linkend="BitmapFont">BitmapFont</link> will be printed as a space, so will be invisible). The default value uses a font provided with VLC, so you don't need to provide it with your skin.</para>
      <para>Default value: defaultfont</para>
105 106
    </sect3>
    <sect3 id="thememagnet">
107 108 109
      <title>magnet</title>
      <para>Allows to select the range of action (in pixels) of magnetism with borders of the screen: when the distance between the border of the screen and an anchor of a window is less than this value, the window will stick to the border. 0 disables magnetism with the screen borders.</para>
      <para>Default value: 15</para>
110 111
    </sect3>
    <sect3 id="themealpha">
112 113 114 115
      <title>alpha</title>
      <para>Sets the alpha transparency of the windows. The value must be between 1 (nearly total transparency) and 255 (total opacity). Low values should be avoided.</para>
<note><para>This only works if transparency is not disabled in the preferences of the skins2 module.</para></note>
      <para>Default value: 255</para>
116 117
    </sect3>
    <sect3 id="thememovealpha">
118
      <title>movealpha</title>
119
      <para>Sets the alpha transparency of the windows when they are moving. Same range as <link linkend="themealpha">alpha</link>.</para>
120 121
      <note><para>This only works if transparency is not disabled in the preferences of the skins2 module.</para></note>
      <para>Default value: 255</para>
122 123
    </sect3>
  </sect2>
124

125
<sect2 id="ThemeInfo">
126 127
  <title>ThemeInfo</title>
  <para>You can enter here some information about you (but this information is currently unused by VLC...)</para>
128
      <sect3 id="themeinfoname">
129 130 131
      <title>name</title>
      <para>Skin name. Not supported yet.</para>
      <para><emphasis>Implied.</emphasis></para>
132 133
    </sect3>
    <sect3 id="themeinfoauthor">
134 135 136
      <title>author</title>
      <para>Author of the skin. Not supported yet.</para>
      <para><emphasis>Implied.</emphasis></para>
137 138
    </sect3>
    <sect3 id="themeinfoemail">
139 140 141
      <title>email</title>
      <para>Email of the author. Not supported yet.</para>
      <para><emphasis>Implied.</emphasis></para>
142 143
    </sect3>
    <sect3 id="themeinfowebpage">
144 145 146
      <title>webpage</title>
      <para>Web page in relation with the skin. Not supported yet.</para>
      <para>Default value: http://www.videolan.org/vlc/</para>
147 148
    </sect3>
</sect2>
149

150
<sect2 id="Bitmap">
151
  <title>Bitmap</title>
152
  <para>Associates a bitmap file (usually in PNG format) with an identifiant (=name) that will be used by the various controls. Obviously, you need one Bitmap tag for each bitmap file you have.</para>
153
  <sect3 id="bitmapid">
154 155 156
    <title>id</title>
    <para>Identifiant of the bitmap that will be used with controls. Two bitmaps cannot have the same id.</para>
    <para><emphasis>Required.</emphasis></para>
157 158
  </sect3>
  <sect3 id="bitmapfile">
159 160 161
    <title>file</title>
    <para>Indicates the path and name of the bitmap file used. This path can be absolute (but you should definitely avoid it), or relative to the path of the XML file.</para>
    <para><emphasis>Required.</emphasis></para>
162 163
  </sect3>
  <sect3 id="bitmapalphacolor">
164 165 166 167
    <title>alphacolor</title>
    <para>Transparency color of the bitmap. It must be indicated with the following format: "#RRGGBB", where RR stands for the hexadecimal value of the red component, GG for the green one, and BB for the blue one.</para>
    <note><para>If your PNG file specifies a transparency mask, it will be taken into account too.</para></note>
    <para>Default value: #000000</para><!--XXX: should we change it into a less often used color?-->
168 169
  </sect3>
  <sect3 id="bitmapnbframes">
170 171 172
    <title>nbframes</title>
    <para>This attribute is needed to define animated bitmaps; it is the number of frames (images) contained in your animation. All the different frames are just images laid vertically in the bitmap. Animated GIFs are not supported at the moment. (since VLC 0.8.5)</para>
    <para>Default value: 1</para>
173 174
  </sect3>
  <sect3 id="bitmapfps">
175 176 177
    <title>fps</title>
    <para>Only used in animated bitmaps; it is the number of frames (images) per seconds of the animation. (since VLC 0.8.5)</para>
    <para>Default value: 0</para>
178
  </sect3>
179 180 181 182 183
  <sect3 id="bitmaploop">
    <title>loop</title>
    <para>Only used in animated bitmaps; it is the number of loops before animation stops. Default value 0 means animation doesn't stop. Otherwise, animation stops on the last frame after the number of loops has been reached (since VLC 1.1)</para>
    <para>Default value: 0</para>
  </sect3>
184

185
</sect2>
186

187
<sect2 id="SubBitmap">
188 189
  <title>SubBitmap</title>
  <para>Declares a portion of bitmap, that will be used with controls in the same way as a regular Bitmap. A SubBitmap tag can only be placed inside a <link linkend="Bitmap">Bitmap</link> tag, and references implicitly the same file. SubBitmaps are very convenient when a file contains images for several controls. (This tag was not available before VLC 0.8.5).</para>
190
  <sect3 id="subbitmapid">
191 192 193
    <title>id</title>
    <para>Identifiant of the portion of bitmap that will be used with controls. It must be unique in the whole skin.</para>
    <para><emphasis>Required.</emphasis></para>
194 195
  </sect3>
  <sect3 id="subbitmapx">
196 197 198
    <title>x</title>
    <para>Horizontal offset of the sub-bitmap (in pixels), relative to the "parent" bitmap.</para>
    <para><emphasis>Required.</emphasis></para>
199 200
  </sect3>
  <sect3 id="subbitmapy">
201 202 203
    <title>y</title>
    <para>Vertical offset of the sub-bitmap (in pixels), relative to the "parent" bitmap.</para>
    <para><emphasis>Required.</emphasis></para>
204 205
  </sect3>
  <sect3 id="subbitmapwidth">
206 207 208
    <title>width</title>
    <para>Width of the sub-bitmap, in pixels.</para>
    <para><emphasis>Required.</emphasis></para>
209 210
  </sect3>
  <sect3 id="subbitmapheight">
211 212 213
    <title>height</title>
    <para>Height of the SubBitmap, in pixels.</para>
    <para><emphasis>Required.</emphasis></para>
214 215
  </sect3>
  <sect3 id="subbitmapnbframes">
216
    <title>nbframes</title>
217
    <para>Same as in <link linkend="bitmapnbframes">Bitmap</link> tag.</para>
218
    <para>Default value: 1</para>
219 220
  </sect3>
  <sect3 id="subbitmapfps">
221
    <title>fps</title>
222
    <para>Same as in <link linkend="bitmapfps">Bitmap</link> tag.</para>
223
  </sect3>
224 225 226 227
  <sect3 id="subbitmaploop">
    <title>loop</title>
    <para>Same as in <link linkend="bitmaploop">Bitmap</link> tag.</para>
  </sect3>
228

229
</sect2>
230

231
<sect2 id="Font">
232
  <title>Font</title>
233
  <para>Declares a font to be used in a <link linkend="Text">Text</link> or <link linkend="Playtree">Playtree</link>.</para>
234
  <sect3 id="fontid">
235 236 237
    <title>id</title>
    <para>Identifiant of the font that will be used with controls.</para>
    <para><emphasis>Required.</emphasis></para>
238 239
  </sect3>
  <sect3 id="fontfile">
240 241 242
    <title>file</title>
    <para>This is the file containing a TrueType font.</para>
    <para><emphasis>Required.</emphasis></para>
243 244
  </sect3>
  <sect3 id="fontsize">
245 246 247
    <title>size</title>
    <para>This is the size of the font, in points.</para>
    <para>Default value: 12</para>
248 249
  </sect3>
</sect2>
250

251
<sect2 id="BitmapFont">
252 253
  <title>BitmapFont</title>
  <para><!--TODO--></para>
254
  <sect3 id="bitmapfontid">
255 256 257
    <title>id</title>
    <para>Identifiant of the font that will be used with controls.</para>
    <para><emphasis>Required.</emphasis></para>
258 259
  </sect3>
  <sect3 id="bitmapfontfile">
260 261 262
    <title>file</title>
    <para>This is the file containing a bitmap font, à la Winamp.</para>
    <para><emphasis>Required.</emphasis></para>
263 264
  </sect3>
  <sect3 id="bitmapfonttype">
265 266 267
    <title>type</title>
    <para>Type of font, one of "digits" or "text".</para>
    <para>Default value: digits</para>
268 269
  </sect3>
</sect2>
270

271
<sect2 id="Window">
272 273
  <title>Window</title>
  <para>A window that will appear on screen.</para>
274
  <sect3 id="windowid">
275 276 277
    <title>id</title>
    <para>Name of the window (it may be used for actions). Two windows cannot have the same id.</para>
    <para>Default value: none</para>
278
    <para>As of vlc1.1, a special id has been added to provide a skinnable fullscreen controller. This value id="fullscreenController" allows the window to be displayed only in fullscreen mode. Display is toggled by pressing the 'i' hotkey or clicking the mouse middle button</para>
279 280
  </sect3>
  <sect3 id="windowvisible">
281 282 283
    <title>visible</title>
    <para>Indicates whether the window should appear when VLC is started. Since VLC remembers the skin windows position and visibility, this attribute will only be used the first time the skin is started.</para>
    <para>Default value: true</para>
284 285
  </sect3>
  <sect3 id="windowx">
286 287 288
    <title>x</title>
    <para>Initial left position of the window.</para>
    <para>Default value: 0</para>
289 290
  </sect3>
  <sect3 id="windowy">
291 292 293
    <title>y</title>
    <para>Initial top position of the window.</para>
    <para>Default value: 0</para>
294 295
  </sect3>
  <sect3 id="windowdragdrop">
296 297 298
    <title>dragdrop</title>
    <para>Indicates whether drag and drop of media files is allowed on this window.</para>
    <para>Default value: true</para>
299 300
  </sect3>
  <sect3 id="windowplayondrop">
301
    <title>playondrop</title>
302
    <para>Indicates whether a dropped file is played directly (true) or only enqueued (false). This attribute has no effect if <link linkend="windowdragdrop">dragdrop</link> is set to "false".</para>
303
    <para>Default value: true</para>
304 305
  </sect3>
</sect2>
306

307
<sect2 id="Layout">
308 309
  <title>Layout</title>
  <para>A layout is one aspect of a window, i.e. a set of controls and anchors. A window can have many layouts, but only one will be visible at any time.</para>
310
  <sect3 id="layoutid">
311 312 313
    <title>id</title>
    <para>Name of the layout (it may be used for actions). Two layouts cannot have the same id.</para>
    <para>Default value: none</para>
314 315
  </sect3>
  <sect3 id="layoutwidth">
316
    <title>width</title>
Olivier Teulière's avatar
Olivier Teulière committed
317
    <para><!--TODO: calculate it in VLC :)-->Initial width of the layout. This value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls.</para>
318
    <para><emphasis>Required.</emphasis></para>
319 320
  </sect3>
  <sect3 id="layoutheight">
321
    <title>height</title>
Olivier Teulière's avatar
Olivier Teulière committed
322
    <para><!--TODO: calculate it in VLC :)-->Initial height of the layout. This value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls.</para>
323
    <para><emphasis>Required.</emphasis></para>
324 325
  </sect3>
  <sect3 id="minwidth">
326 327 328
    <title>minwidth</title>
    <para>Minimum width of the layout. This value is only used when resizing the layout. If this value is set to "-1", the initial width (as specified by the <link linkend="layoutwidth">width</link> attribute) will be used as minimum width.</para>
    <para>Default value: -1</para>
329 330
  </sect3>
  <sect3 id="maxwidth">
331 332 333
    <title>maxwidth</title>
    <para>Maximum width of the layout. This value is only used when resizing the layout. If this value is set to "-1", the initial width (as specified by the <link linkend="layoutwidth">width</link> attribute) will be used as maximum width.</para>
    <para>Default value: -1</para>
334 335
  </sect3>
  <sect3 id="minheight">
336 337 338
    <title>minheight</title>
    <para>Minimum height of the layout. This value is only used when resizing the layout. If this value is set to "-1", the initial height (as specified by the <link linkend="layoutheight">height</link> attribute) will be used as minimum height.</para>
    <para>Default value: -1</para>
339 340
  </sect3>
  <sect3 id="maxheight">
341 342 343
    <title>maxheight</title>
    <para>Maximum height of the layout. This value is only used when resizing the layout. If this value is set to "-1", the initial height (as specified by the <link linkend="layoutheight">height</link> attribute) will be used as maximum height.</para>
    <para>Default value: -1</para>
344 345
  </sect3>
</sect2>
346

347
<sect2 id="Group">
348
  <title>Group</title>
Olivier Teulière's avatar
Olivier Teulière committed
349
  <para>Add an offset to the elements it contains. A Group is only supposed to ease the job of the skin designer, who can adjust the position of a group of controls without modifying all the coordinates, but you can ignore it if you want (only one Group is necessary, inside the <link linkend="Layout">Layout</link> tag). Group tags can be nested. Note that Group elements are deprecated, since <link linkend="Panel">Panel</link> elements are more powerful.</para>
350
  <sect3 id="groupx">
351
    <title>x</title>
Olivier Teulière's avatar
Olivier Teulière committed
352
    <para>Horizontal offset, relative to the container box (see the <link linkend="layoutmodel">Layout model</link> for more details).</para>
353
    <para>Default value: 0</para>
354 355
  </sect3>
  <sect3 id="groupy">
356
    <title>y</title>
Olivier Teulière's avatar
Olivier Teulière committed
357
    <para>Vertical offset, relative to the container box (see the <link linkend="layoutmodel">Layout model</link> for more details).</para>
358
    <para>Default value: 0</para>
359 360
  </sect3>
</sect2>
361

Olivier Teulière's avatar
Olivier Teulière committed
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
<sect2 id="Panel">
  <title>Panel</title>
  <para>A Panel can be seen as an enhanced <link linkend="Layout">Group</link>. It also adds an offset to the elements it contains, but in addition it becomes their reference for the lefttop, rightbottom, xkeepratio and ykeepratio attributes. Panel tags can be nested. Since VLC 0.9.0.</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
  <sect3 id="panelx">
    <title>x</title>
    <para>Same as the <link linkend="x">x</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
  <sect3 id="panely">
    <title>y</title>
    <para>Same as the <link linkend="y">y</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
  <sect3 id="panelwidth">
    <title>width</title>
    <para>Initial width of this container box (see the <link linkend="layoutmodel">Layout model</link> for more details).</para>
377
    <para><emphasis>Required.</emphasis></para>
Olivier Teulière's avatar
Olivier Teulière committed
378 379 380 381
  </sect3>
  <sect3 id="panelheight">
    <title>height</title>
    <para>Initial height of this container box (see the <link linkend="layoutmodel">Layout model</link> for more details).</para>
382
    <para><emphasis>Required.</emphasis></para>
Olivier Teulière's avatar
Olivier Teulière committed
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401
  </sect3>
  <sect3 id="panellefttop">
    <title>lefttop</title>
    <para>Same as the <link linkend="lefttop">lefttop</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
  <sect3 id="panelrightbottom">
    <title>rightbottom</title>
    <para>Same as the <link linkend="rightbottom">rightbottom</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
  <sect3 id="panelxkeepratio">
    <title>xkeepratio</title>
    <para>Same as the <link linkend="xkeepratio">xkeepratio</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
  <sect3 id="panelykeepratio">
    <title>ykeepratio</title>
    <para>Same as the <link linkend="ykeepratio">ykeepratio</link> attribute of the <link linkend="commattr">common attributes</link>.</para>
  </sect3>
</sect2>

402
<sect2 id="Anchor">
403
  <title>Anchor</title>
404
  <para>Create a "magnetic point" (or curve) in the current window. If an anchor of another window enters in the range of action of this anchor, the 2 anchors will automatically be on the same place, and the windows are "sticked". Each anchor has a priority (<link linkend="anchorpriority">priority</link> attribute), and the anchor with the highest priority is the winner, which means that when moving its window all the other anchored windows will move too. To break the effect of 2 anchored windows, you need to move the window whose anchor has the lower priority.</para>
405
  <sect3 id="anchorx">
406
    <title>x</title>
Olivier Teulière's avatar
Olivier Teulière committed
407
    <para>Is it really necessary to explain?</para>
408
    <para>Default value: 0</para>
409 410
  </sect3>
  <sect3 id="anchory">
411 412 413
    <title>y</title>
    <para>...</para>
    <para>Default value: 0</para>
414 415
  </sect3>
  <sect3 id="anchorlefttop">
416
    <title>lefttop</title>
417
    <para>Indicate to which corner of the Layout the top-left-hand corner of this anchor is attached, in case of resizing. Possible values are 'lefttop', 'leftbottom', 'righttop' and 'rightbottom'. Available since VLC 0.8.6.</para>
418 419
    <para>Note that there is no "rightbottom" attribute for the anchors (contrarily to normal controls), because an anchor is not resizable (even when the anchor is not ponctual and follows a Bezier curve).</para>
    <para>Default value: lefttop</para>
420 421
  </sect3>
  <sect3 id="anchorpriority">
422 423 424
    <title>priority</title>
    <para>Priority of anchor (see the previous description).</para>
    <para><emphasis>Required.</emphasis></para>
425 426
  </sect3>
  <sect3 id="anchorpoints">
427 428 429 430
    <title>points</title>
    <para>Points defining the <link linkend="bezier">Bezier curve</link> followed by the anchor.</para>
    <note><para>You don't need to change this parameter if all you want is a ponctual anchor.</para></note>
    <para>Default value: (0,0)</para>
431 432
  </sect3>
  <sect3 id="anchorrange">
433
    <title>range</title>
434
    <para>Range of action of the anchor, in pixels.</para>
435
    <para>Default value: 10</para>
436 437
  </sect3>
</sect2>
438 439


440 441
<sect2 id="commattr">
  <title>Common attributes</title>
442
  <para>The following attributes are common to all the controls (Image, Button, Checkbox, Text, Slider, RadialSlider, Playlist, Playtree, Video)</para>
443
  <sect3 id="attrid">
444 445 446
    <title>id</title>
    <para>Identifiant of the control. Currently unused.</para>
    <para>Default value: none</para>
447 448
  </sect3>
  <sect3 id="visible">
449 450 451
    <title>visible</title>
    <para>See <link linkend="boolexpr">Boolean expressions</link>.</para>
    <para>Default value: true</para>
452 453
  </sect3>
  <sect3 id="x">
454
    <title>x</title>
Olivier Teulière's avatar
Olivier Teulière committed
455
    <para>Horizontal offset of the control, relative to the container box (see the <link linkend="layoutmodel">Layout model</link>) or to the parent <link linkend="Group">Group</link>.</para>
456
    <para>Default value: 0</para>
457 458
  </sect3>
  <sect3 id="y">
459
    <title>y</title>
Olivier Teulière's avatar
Olivier Teulière committed
460
    <para>Vertical offset of the control, relative to the container box (see the <link linkend="layoutmodel">Layout model</link>) or to the parent <link linkend="Group">Group</link>.</para>
461
    <para>Default value: 0</para>
462 463
  </sect3>
  <sect3 id="lefttop">
464
    <title>lefttop</title>
Olivier Teulière's avatar
Olivier Teulière committed
465
    <para>Indicate to which corner of the container box the top-left-hand corner of this control is attached, in case of resizing. Possible values are 'lefttop', 'leftbottom', 'righttop' and 'rightbottom'. See the <link linkend="layoutmodel">Layout model</link> for more details.</para>
466
    <para>Default value: lefttop</para>
467 468
  </sect3>
  <sect3 id="rightbottom">
469
    <title>rightbottom</title>
Olivier Teulière's avatar
Olivier Teulière committed
470
    <para>Indicate to which corner of the container box the bottom-right-hand corner of this control is attached, in case of resizing. See the <link linkend="layoutmodel">Layout model</link> for more details.</para>
471
    <para>Default value: lefttop</para>
472 473
  </sect3>
  <sect3 id="xkeepratio">
474
    <title>xkeepratio</title>
Olivier Teulière's avatar
Olivier Teulière committed
475 476
    <para>When set to true, the behaviour of the horizontal resizing is changed. Instead of taking into account the <link linkend="lefttop">lefttop</link> and <link linkend="rightbottom">rightbottom</link> attributes to determine how the control will be moved/resized, only its initial position inside the container box matters. For example, if initially the space to the left of the control is twice as big as the one to its right, this will stay the same during any horizontal resizing. The width of the control stays constant.</para>
    <para>This attribute can be particularly useful to keep a control centered in the container box, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). See the <link linkend="layoutmodel">Layout model</link> for more details. Available since VLC 0.8.6.</para>
477
    <para>Default value: false</para>
478 479
  </sect3>
  <sect3 id="ykeepratio">
480 481
    <title>ykeepratio</title>
    <para>When set to true, the behaviour of the vertical resizing is changed. Instead of taking into account the <link linkend="lefttop">lefttop</link> and <link linkend="rightbottom">rightbottom</link> attributes to determine how the control will be moved/resized, only its initial position inside the <link linkend="Layout">Layout</link> matters. For example, if initially the space to the top of the control is twice as big as the one to its bottom, this will stay the same during any vertical resizing. The height of the control stays constant.</para>
Olivier Teulière's avatar
Olivier Teulière committed
482
    <para>This attribute can be particularly useful to keep a control centered in the container box, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). See the <link linkend="layoutmodel">Layout model</link> for more details. Available since VLC 0.8.6.</para>
483
    <para>Default value: false</para>
484 485
  </sect3>
  <sect3 id="help">
486 487 488
    <title>help</title>
    <para>Help text for the current control. The variable '$H' will be expanded to this value when the mouse hovers the current control (see <link linkend="textvars">Text variables</link>).</para>
    <para>Default value: </para>
489
  </sect3>
490 491 492 493 494 495
    <para>The vlc2.0 extends some of these parameters and adds five more parameters to ease up positioning windows within a given screen and widgets within their own containers (layout, panel, ...). As extension, the x, y, width and height can now be given in pixels (default) or in percentage of their container. For instance, x="10" or x="10px" is construed as 10 pixels, and x="10%" is construed as 10% of the width of the screen for windows or their container for widgets.</para>
  <sect3 id="position">
    <title>position</title>
    <para>Relative placement of windows or widget within their respective container(screen for windows, layout or panel for widgets). This placement is given with a geographical qualifier. Possible values are "Center", "North", "NorthWest", ....The skin engine computes the size of the element (from the width and height parameters) then places it at the center or sticks it to a given border depending on the geographical qualifer.</para>
    <para>Default value: -1(N/A)</para>
  </sect3>
496 497 498
  <sect3 id="xmargin">
    <title>xmargin</title>
    <para>Coupled with position, xmargin allows for a horizontal margin instead of just sticking to the border. It can be given in pixels or in percentage of the width of the container.</para>
499 500
    <para>Default value: 0</para>
  </sect3>
501 502 503
  <sect3 id="ymargin">
    <title>ymargin</title>
    <para>Coupled with position, ymargin allows for a vertical margin instead of just sticking to the border. It can be given in pixels or in percentage of the height of the container.</para>
504 505
    <para>Default value: 0</para>
  </sect3>
506 507
  <sect3 id="xoffset">
    <title>xoffset</title>
508
    <para>Coupled with position and xmargin, this parameter moves the widget horizontally by this offset from the position computed above. From VLC2.1.0 on, xoffset can directly be used without position, in which case percentage is computed against the current object instead of the upper container</para>
509 510
    <para>Default value: 0</para>
  </sect3>
511 512
  <sect3 id="yoffset">
    <title>yoffset</title>
513
    <para>Coupled with position and ymargin, this parameter moves the widget vertically by this offset from the position computed above. From VLC2.1.0 on, yoffset can directly be used without position, in which case percentage is computed against the current object instead of the upper container</para>
514 515
    <para>Default value: 0</para>
  </sect3>
516
</sect2>
517

518
<sect2 id="Image">
519 520 521
  <title>Image</title>
  <para>Create a simple image. Particularly useful for backgrounds.</para>
  <para>See the <link linkend="commattr">Common attributes</link>.</para>
522
  <sect3 id="image">
523 524 525
    <title>image</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>.</para>
    <para><emphasis>Required.</emphasis></para>
526
  </sect3>
527 528 529 530 531 532 533 534 535 536
  <sect3 id="imagewidth">
    <title>width</title>
    <para>Width of the image. If set, this width supersedes the actual width of the image. The initial resizing takes the resize policy into account</para>
    <para>Default value: -1</para>
  </sect3>
  <sect3 id="imageheight">
    <title>height</title>
    <para>Height of the image. If set, this height supersedes the actual height of the image. The initial resizing takes the resize policy into account</para>
    <para>Default value: -1</para>
  </sect3>
537
  <sect3 id="imageresize">
538 539
    <title>resize</title>
    <para>Since VLC 0.8.2. Specify the behaviour of the image when it is resized. Possible values are 'mosaic' (the image is repeated as many times as necessary to reach the wanted dimensions) and 'scale' (the image is actually rescaled). Beware that the 'scale' behaviour is much slower than the 'mosaic' one, so make sure to use it only when it's really needed.</para>
540
    <para>In VLC 2.0, a third value 'scale2' is available to scale an image, yet preserving its aspect ratio. The image is centered and scaled either heightwise or widthwise to fill up as much area as possible. Extra borders are made transparent.</para>
541
    <para>Default value: mosaic.</para>
542 543
  </sect3>
  <sect3 id="imageaction">
544
    <title>action</title>
545
    <para>Action triggered by a click on the control. Possible values are 'move', to move the window, 'resizeE', to resize horizontally, 'resizeS' to resize vertically, and 'resizeSE' to resize both horizontally and vertically. Mnemonics: S, E and SE stand for South, East, and South-East. The 'resizeS' and 'resizeE' actions are available since VLC 0.8.5 only.</para>
546
    <para>Default value: none</para>
547 548
  </sect3>
  <sect3 id="imageaction2">
549 550 551
    <title>action2</title>
    <para>Action triggered by a double-click on the control. See <link linkend="actions">Actions</link> for a list of possible actions. (Since VLC 0.8.5).</para>
    <para>Default value: none</para>
552
  </sect3>
553 554
  <sect3 id="imageart">
    <title>art</title>
555
    <para>if set to true, the skin engine reuses the control to display the art file of the resource currently being played back. Usually, resize="scale2" is desirable, for art to be rendered in the best possible way. (from VLC 2.0 on).</para>
556 557
    <para>Default value: false</para>
  </sect3>
558
</sect2>
559

560
<sect2 id="Button">
561 562 563
  <title>Button</title>
  <para>Create a button.</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
564
  <sect3 id="buttonup">
565 566 567
    <title>up</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the button is up.</para>
    <para><emphasis>Required.</emphasis></para>
568 569
  </sect3>
  <sect3 id="buttondown">
570 571 572
    <title>down</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the button is down.</para>
    <para>Default value: none</para>
573 574
  </sect3>
  <sect3 id="buttonover">
575 576 577
    <title>over</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the mouse is over the button.</para>
    <para>Default value: none</para>
578 579
  </sect3>
  <sect3 id="buttonaction">
580 581 582
    <title>action</title>
    <para>Action executed when the button is clicked. See <link linkend="actions">Actions</link> for a list of possible actions.</para>
    <para>Default value: none</para>
583
  </sect3>
584 585 586 587 588
  <sect3 id="buttontooltiptext">
    <title>tooltiptext</title>
    <para>Tooltip associated with the button. See also <link linkend="textvars">Text variables</link>.</para>
    <para>Default value: </para>
  </sect3>
589
</sect2>
590

591
<sect2 id="Checkbox">
592 593 594
  <title>Checkbox</title>
  <para>Create a checkbox, i.e. a button with 2 states (checked/unchecked). So you need 6 images for a full-featured checkbox: each state has a basic image ('up' state), an image for the control being hovered by the mouse ('over' state) and an image corresponding to a click not yet released ('down' state). If you supply only the basic images, the other ones will be identical.</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
595
  <sect3 id="up1">
596 597 598
    <title>up1</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the checkbox is up in the first state.</para>
    <para><emphasis>Required.</emphasis></para>
599 600
  </sect3>
  <sect3 id="down1">
601 602 603
    <title>down1</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the checkbox is down in the first state.</para>
    <para>Default value: none</para>
604 605
  </sect3>
  <sect3 id="over1">
606 607 608
    <title>over1</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the mouse is over the checkbox in the first state.</para>
    <para>Default value: none</para>
609 610
  </sect3>
  <sect3 id="up2">
611 612 613
    <title>up2</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the checkbox is up in the second state.</para>
    <para><emphasis>Required.</emphasis></para>
614 615
  </sect3>
  <sect3 id="down2">
616 617 618
    <title>down2</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the checkbox is down in the second state.</para>
    <para>Default value: none</para>
619 620
  </sect3>
  <sect3 id="over2">
621 622 623
    <title>over2</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the mouse is over the checkbox in the second state.</para>
    <para>Default value: none</para>
624 625
  </sect3>
  <sect3 id="state">
626 627 628
    <title>state</title>
    <para><link linkend="boolexpr">Boolean expression</link> specifying the state of the checkbox: if the expression resolves to 'false', the first state will be used, and if it resolves to 'true' the second state will be used. Example for a checkbox showing/hiding a window whose <link linkend="windowid">id</link> is "playlist_window": state="playlist_window.isVisible" (or state="not playlist_window.isVisible", depending on the states you chose).</para>
    <para><emphasis>Required.</emphasis></para>
629 630
  </sect3>
  <sect3 id="action1">
631 632 633
    <title>action1</title>
    <para>Action executed when the checkbox is clicked (state 1 to state 2). See <link linkend="actions">Actions</link> for a list of possible actions.</para>
    <para>Default value: none</para>
634 635
  </sect3>
  <sect3 id="action2">
636 637 638
    <title>action2</title>
    <para>Action executed when the checkbox is clicked (state 2 to state 1). See <link linkend="actions">Actions</link> for a list of possible actions.</para>
    <para>Default value: none</para>
639 640
  </sect3>
  <sect3 id="tooltiptext1">
641 642 643
    <title>tooltiptext1</title>
    <para>Tooltip associated with the checkbox in state 1. See also <link linkend="textvars">Text variables</link>.</para>
    <para>Default value: </para>
644 645
  </sect3>
  <sect3 id="tooltiptext2">
646 647 648
    <title>tooltiptext2</title>
    <para>Tooltip associated with the checkbox in state 2. See also <link linkend="textvars">Text variables</link>.</para>
    <para>Default value: </para>
649 650
  </sect3>
</sect2>
651

652
<sect2 id="Text">
653 654 655
  <title>Text</title>
  <para>Control to display some text.</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
656
  <sect3 id="textfont">
657 658 659
    <title>font</title>
    <para>Identifiant of a <link linkend="Font">Font</link> or <link linkend="BitmapFont">BitmapFont</link> (beware that any character not present in the <link linkend="BitmapFont">BitmapFont</link> will be printed as a space, so will be invisible).</para>
    <para><emphasis>Required.</emphasis></para>
660 661
  </sect3>
  <sect3 id="texttext">
662
    <title>text</title>
663
    <para>Text to display. See also <link linkend="textvars">Text variables</link>.</para>
664
    <para>Default value: </para>
665 666
  </sect3>
  <sect3 id="textcolor">
667 668 669
    <title>color</title>
    <para>Color of the text, using the #RRGGBB format.</para>
    <para>Default value: #000000</para>
670 671
  </sect3>
  <sect3 id="textwidth">
672 673 674
    <title>width</title>
    <para>Width of the text in pixels. If set to "0", the width is automatically calculated to fit with the current text.<!--XXX: Probably false...--></para>
    <para>Default value: 0</para>
675 676
  </sect3>
  <sect3 id="textalignment">
677 678 679
    <title>alignment</title>
    <para>Alignment of the text inside the control. Possible values are 'left', 'center' and 'right'. The 'width' and 'center' alignments are computed using the width of the control (as given by the <link linkend="textwidth">width</link> attribute). Available since VLC 0.8.5.</para>
    <para>Default value: left</para>
680
  </sect3>
681 682
  <sect3 id="focus">
    <title>focus</title>
683
    <para>indicates if the control is eligible for mouse focus or not. If focus is set to false, it is as though the control did not exist when it comes to mouse focus. This allows for instance displaying a dynamic text in the title bar, yet opting for being able to move the window rather than manage scrolling of lengthy text. Available in VLC 2.0</para>
684 685
    <para>Default value: true</para>
  </sect3>
686
  <sect3 id="textscrolling">
687
    <title>scrolling</title>
688
    <para>Scrolling behaviour of the text (only when it doesn't fit in the <link linkend="textwidth">width</link> of the control). Possible values are 'auto', 'manual' and 'none'. If this attribute is set to 'auto', the text automatically starts scrolling. The user can drag the text, and click on it to start/stop the scrolling. If this attribute is set to 'manual', the text only scrolls when dragged by the user. If this attribute is set to 'none', no scrolling is possible at all. Available since VLC 0.8.5.</para>
689
    <para>Default value: auto</para>
690 691
  </sect3>
</sect2>
692

693
<sect2 id="Slider">
694
  <title>Slider</title>
695
  <para>Create a slider. This element can be used alone, or can contain a <link linkend="SliderBackground">SliderBackground</link> element.</para>
696
  <para>See the <link linkend="commattr">common attributes</link>.</para>
697
  <sect3 id="sliderup">
698 699 700
    <title>up</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the slider cursor is up.</para>
    <para><emphasis>Required.</emphasis></para>
701 702
  </sect3>
  <sect3 id="sliderdown">
703 704 705
    <title>down</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the slider cursor is down.</para>
    <para>Default value: none</para>
706 707
  </sect3>
  <sect3 id="sliderover">
708 709 710
    <title>over</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used when the mouse is over the slider cursor.</para>
    <para>Default value: none</para>
711 712
  </sect3>
  <sect3 id="sliderpoints">
713 714 715
    <title>points</title>
    <para>Points defining the <link linkend="bezier">Bezier curve</link> followed by the slider cursor.</para>
    <para>Default value: none</para>
716 717
  </sect3>
  <sect3 id="sliderthickness">
718 719 720
    <title>thickness</title>
    <para>Thickness of the slider curve. This attribute is used to determine whether the mouse is over the slider (hence whether a mouse click will have an effect on the cursor position).</para>
    <para>Default value: 10</para>
721 722
  </sect3>
  <sect3 id="slidervalue">
723
    <title>value</title>
724
    <para>Variable controlled by the slider. This must be a <link linkend="percent">percentage variable</link>, e.g "volume" or "time" (only exception: the <link linkend="Slider">Slider</link> defined inside the <link linkend="Playtree">Playtree</link> tag does not need to set this attribute).</para>
725
    <para>Default value: none</para>
726
  </sect3>
727 728 729 730 731 732 733 734 735 736
  <sect3 id="sliderwidth">
    <title>width</title>
    <para>Width of the slider. If set, this width supersedes the actual width of the slider computed from the curve width. (new after VLC 2.1.0)</para>
    <para>Default value: -1</para>
  </sect3>
  <sect3 id="sliderheight">
    <title>height</title>
    <para>Height of the slider. If set, this height supersedes the actual height of the slider computed from the curve height. (new after VLC 2.1.0)</para>
    <para>Default value: -1</para>
  </sect3>
737
  <sect3 id="slidertooltiptext">
738 739 740
    <title>tooltiptext</title>
    <para>Tooltip associated with the slider. See also <link linkend="textvars">Text variables</link>.</para>
    <para>Default value: </para>
741 742
  </sect3>
</sect2>
743

744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775

<sect2 id="SliderBackground">
  <title>SliderBackground</title>
  <para>Set of background images associated to a slider (it must be a sub-element of a <link linkend="Slider">Slider</link>). The displayed image depends on the value of the corresponding slider; if the SliderBackground contains n images, the image #m will be displayed, where m = n * (slider value). A SliderBackground actually contains a single image, which is divided into a grid to build all the sub-images. All the sub-images of the grid have the same size, and can be separated by unused pixel lines or rows if needed (this is called "padding").</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
  <sect3 id="sbg_image">
    <title>image</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>; image containing the sub-images used to draw the background of the slider.</para>
    <para><emphasis>Required.</emphasis></para>
  </sect3>
  <sect3 id="nbhoriz">
    <title>nbhoriz</title>
    <para>Number of sub-images in the horizontal direction.</para>
    <para>Default value: 1</para>
  </sect3>
  <sect3 id="nbvert">
    <title>nbvert</title>
    <para>Number of sub-images in the vertical direction.</para>
    <para>Default value: 1</para>
  </sect3>
  <sect3 id="padhoriz">
    <title>padhoriz</title>
    <para>Horizontal padding: number of unused pixel rows between two sub-images.</para>
    <para>Default value: 0</para>
  </sect3>
  <sect3 id="padvert">
    <title>padvert</title>
    <para>Vertical padding: number of unused pixel lines between two sub-images.</para>
    <para>Default value: 0</para>
  </sect3>
</sect2>

776
<sect2 id="RadialSlider">
777 778 779
  <title>RadialSlider</title>
  <para>Create a circular slider from a list of images with the different possible positions.</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
780
  <sect3 id="sequence">
781 782 783
    <title>sequence</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link> containing the list of images of the different positions of the slider, concatenated vertically.</para>
    <para><emphasis>Required.</emphasis></para>
784 785
  </sect3>
  <sect3 id="nbimages">
786 787 788
    <title>nbimages</title>
    <para>Number of elementary images contained in the sequence.</para>
    <para><emphasis>Required.</emphasis></para>
789 790
  </sect3>
  <sect3 id="minangle">
791
    <title>minangle</title>
792
    <para>Minimum angle of the rotation, corresponding to 0%.</para>
793
    <para>Default value: 0</para>
794 795
  </sect3>
  <sect3 id="maxangle">
796
    <title>maxangle</title>
797
    <para>Maximum angle of the rotation, corresponding to 100%.</para>
798
    <para>Default value: 360</para>
799 800
  </sect3>
  <sect3 id="radialslidervalue">
801
    <title>value</title>
802
    <para>Variable controlled by the slider. This must be a <link linkend="percent">percentage variable</link>, e.g "volume" or "time".</para>
803
    <para>Default value: none</para>
804 805
  </sect3>
  <sect3 id="radialslidertooltiptext">
806 807 808
    <title>tooltiptext</title>
    <para>Tooltip associated with the slider. See also <link linkend="textvars">Text variables</link>.</para>
    <para>Default value: </para>
809 810
  </sect3>
</sect2>
811

812
<sect2 id="Video">
813 814
  <title>Video</title>
  <para>Control containing a video. This allows skinable video outputs!</para>
815 816
  <note><para>This control is still under development and its behaviour may change a lot in the future.</para></note>
  <sect3 id="videowidth">
817 818 819
    <title>width</title>
    <para>Initial width of the control, in pixels.<!--XXX: cannot be deduced?--></para>
    <para>Default value: 0</para>
820 821
  </sect3>
  <sect3 id="videoheight">
822 823 824
    <title>height</title>
    <para>Initial height of the control, in pixels.<!--XXX: cannot be deduced?--></para>
    <para>Default value: 0</para>
825 826
  </sect3>
  <sect3 id="videoautoresize">
827 828 829
    <title>autoresize</title>
    <para>Indicate whether the layout should be automatically resized to fit the dimensions of the played video.</para>
    <para>Default value: true</para>
830 831
  </sect3>
</sect2>
832

833
<sect2 id="Playlist">
834 835
 <title>Playlist</title>
 <para>This tag used to create a playlist. This tag is deprecated, you should now use <link linkend="Playtree">Playtree</link></para>
836
</sect2>
837

838
<sect2 id="Playtree">
839
  <title>Playtree</title>
840 841
  <para>Create a playlist. This tag must contain a <link linkend="Slider">Slider</link> tag (to allow scrolling in the playlist).</para>
  <para>See the <link linkend="commattr">common attributes</link>.</para>
842
  <sect3 id="playlistwidth">
843 844 845
    <title>width</title>
    <para>Width of the playlist, in pixels. If playlist items are wider, the end of the name will be replaced with '...'.</para>
    <para>Default value: 0</para>
846 847
  </sect3>
  <sect3 id="playlistheight">
848 849 850
    <title>height</title>
    <para>Height of the playlist, in pixels.</para>
    <para>Default value: 0</para>
851 852
  </sect3>
  <sect3 id="playlistfont">
853 854 855
    <title>font</title>
    <para>Identifiant of a <link linkend="Font">Font</link> tag.</para>
    <para><emphasis>Required.</emphasis></para>
856 857
  </sect3>
  <sect3 id="var">
858 859 860
    <title>var</title>
    <para>Type of playlist. Currently, only "playlist" is recognized, so don't bother with this attribute :)</para>
    <para>Default value: playlist</para>
861 862
  </sect3>
  <sect3 id="bgimage">
863 864 865
    <title>bgimage</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link>, used as the background image. When no bitmap is specified, the background will be filled using the <link linkend="bgcolor1">bgcolor1</link> and <link linkend="bgcolor2">bgcolor2</link> attributes.</para>
    <para>Default value: none</para>
866 867
  </sect3>
  <sect3 id="fgcolor">
868 869 870
    <title>fgcolor</title>
    <para>Foreground color of the playlist items.</para>
    <para>Default value: #000000</para>
871 872
  </sect3>
  <sect3 id="playcolor">
873 874 875
    <title>playcolor</title>
    <para>Foreground color of the item currently played.</para>
    <para>Default value: #FF0000</para>
876 877
  </sect3>
  <sect3 id="selcolor">
878 879 880
    <title>selcolor</title>
    <para>Background color of selected items.</para>
    <para>Default value: #0000FF</para>
881 882
  </sect3>
  <sect3 id="bgcolor1">
883 884 885
    <title>bgcolor1</title>
    <para>Background color for odd playlist items. This attribute is ignored if the <link linkend="bgimage">bgimage</link> one is used.</para>
    <para>Default value: #FFFFFF</para>
886 887
  </sect3>
  <sect3 id="bgcolor2">
888 889 890
    <title>bgcolor2</title>
    <para>Background color for even playlist items. This attribute is ignored if the <link linkend="bgimage">bgimage</link> one is used.</para>
    <para>Default value: #FFFFFF</para>
891 892
  </sect3>
  <sect3 id="flat">
893 894 895 896
    <title>flat</title>
    <para>Boolean to indicate whether the playlist should use the tree structure or be completely "flat" (only show the leafs of the tree).</para>
    <para>A flat playtree will work like old-style playlists.</para>
    <para>Default value: false</para>
897 898
  </sect3>
  <sect3 id="itemimage">
899 900
    <title>itemimage</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link> shown to the left of a leaf (playlist item).</para>
901 902
 </sect3>
  <sect3 id="openimage">
903 904
    <title>openimage</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link> shown to the left of a node, when it is expanded.</para>
905 906
 </sect3>
 <sect3 id="closedimage">
907 908
    <title>closedimage</title>
    <para>Identifiant of a <link linkend="Bitmap">Bitmap</link> shown to the left of a node, when it is retracted.</para>
909 910
 </sect3>
</sect2>
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929

</sect1>

<sect1 id="actions">
<title>Actions</title>

<para>There is a predefined list of actions:</para>

<itemizedlist>
  <listitem><para>
    <emphasis>none</emphasis>: Do nothing
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.changeSkin()</emphasis>: Show a dialog box to load a new skin. This does the same as the predefined hotkey Ctrl+S.
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.fileSimple()</emphasis>: Show the simple "Open File" dialog box.
  </para></listitem>
  <listitem><para>
930
    <emphasis>dialogs.file()</emphasis>: Show the "Open File" dialog box, with many options (stream output, subtitles, etc...).
931
  </para></listitem>
932
  <listitem><para>
933
    <emphasis>dialogs.directory()</emphasis>: Show the "Open Directory" dialog box (new after VLC 0.8.2).
934
  </para></listitem>
935
  <listitem><para>
936
    <emphasis>dialogs.disc()</emphasis>: Show the "Open Disc" dialog box.
937 938 939 940 941 942 943 944 945 946 947 948 949
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.net()</emphasis>: Show the "Open Network Stream" dialog box.
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.messages()</emphasis>: Show the "Meessage" dialog box (which gives error/warning/debug messages).
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.prefs()</emphasis>: Show the "Preferences" dialog box.
  </para></listitem>
  <listitem><para>
    <emphasis>dialogs.fileInfo()</emphasis>: Show the "File Info" dialog box.
  </para></listitem>
Clément Stenac's avatar
Clément Stenac committed
950
  <listitem><para>
951
    <emphasis>dialogs.playlist()</emphasis>: Show the "standard" (not skinned) playlist dialog (since VLC 0.8.6).
Clément Stenac's avatar
Clément Stenac committed
952
  </para></listitem>
953 954 955
  <listitem><para>
    <emphasis>dialogs.streamingWizard()</emphasis>: Show the "Streaming Wizard" dialog box (new after VLC 0.8.2).
  </para></listitem>
956
  <listitem><para>
Clément Stenac's avatar
Clément Stenac committed
957 958 959
    <emphasis>dialogs.popup()</emphasis>: Show the full popup menu, (already available with a right-click on a <link linkend="Image">Image</link> control).
  </para></listitem>
  <listitem><para>
Clément Stenac's avatar
Clément Stenac committed
960
    <emphasis>dialogs.audioPopup()</emphasis>: Show the audio settings popup menu (since VLC 0.8.6).
Clément Stenac's avatar
Clément Stenac committed
961 962
  </para></listitem>
   <listitem><para>
Clément Stenac's avatar
Clément Stenac committed
963
    <emphasis>dialogs.videoPopup()</emphasis>: Show the video settings popup menu (since VLC 0.8.6).
Clément Stenac's avatar
Clément Stenac committed
964 965
  </para></listitem>
  <listitem><para>
Clément Stenac's avatar
Clément Stenac committed
966
    <emphasis>dialogs.miscPopup()</emphasis>: Show a popup menu containing playback control and general options (since VLC 0.8.6).
967
  </para></listitem>
968 969 970 971 972 973
  <listitem><para>
    <emphasis>equalizer.enable()</emphasis>: Enable the equalizer audio filter (since VLC 0.8.5).
  </para></listitem>
  <listitem><para>
    <emphasis>equalizer.disable()</emphasis>: Disable the equalizer audio filter (since VLC 0.8.5).
  </para></listitem>
974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991
  <listitem><para>
    <emphasis>vlc.play()</emphasis>: Play the current playlist item.
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.pause()</emphasis>: Pause the current playlist item.
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.stop()</emphasis>: Stop the current playlist item.
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.faster()</emphasis>: Play the current playlist item faster.
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.slower()</emphasis>: Play the current playlist item slower.
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.mute()</emphasis>: Toggle mute/un-mute.
  </para></listitem>
992 993 994 995 996 997
  <listitem><para>
    <emphasis>vlc.volumeUp()</emphasis>: Increase the volume (since VLC 0.8.2).
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.volumeDown()</emphasis>: Reduce the volume (since VLC 0.8.2).
  </para></listitem>
998 999 1000
  <listitem><para>
    <emphasis>vlc.fullscreen()</emphasis>: Toggle the fullscreen mode.
  </para></listitem>
1001 1002 1003
  <listitem><para>
    <emphasis>vlc.snapshot()</emphasis>: Take a snapshot (since VLC 0.8.5).
  </para></listitem>
1004 1005 1006 1007 1008 1009
  <listitem><para>
    <emphasis>vlc.toggleRecord()</emphasis>: Start/Stop recording (since VLC 1.1).
  </para></listitem>
  <listitem><para>
    <emphasis>vlc.nextFrame()</emphasis>: Advance one frame at a time (since VLC 1.1).
  </para></listitem>
1010
  <listitem><para>
1011
    <emphasis>vlc.onTop()</emphasis>: Toggle the "Always on top" status (since VLC 0.8.0).
1012 1013
  </para></listitem>
  <listitem><para>
1014
    <emphasis>vlc.minimize()</emphasis>: Minimize VLC (since VLC 0.8.0)
1015
  </para></listitem>
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030
  <listitem><para>
    <emphasis>vlc.quit()</emphasis>: Quit VLC.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.add()</emphasis>: Add a new item to the playlist.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.del()</emphasis>: Remove the selected items from the playlist.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.next()</emphasis>: Go to the next playlist item.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.previous()</emphasis>: Go to the previous playlist item.
  </para></listitem>
1031 1032 1033
  <listitem><para>
    <emphasis>playlist.sort()</emphasis>: Sort the playlist alphabetically.
  </para></listitem>
1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045
  <listitem><para>
    <emphasis>playlist.setRandom(true)</emphasis>: Play the playlist items in random order.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.setRandom(false)</emphasis>: Play the playlist items in the playlist order.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.setLoop(true)</emphasis>: Loop at playlist end.
  </para></listitem>
  <listitem><para>
    <emphasis>playlist.setLoop(false)</emphasis>: Do not loop at playlist end.
  </para></listitem>
1046
  <listitem><para>
1047
    <emphasis>playlist.setRepeat(true)</emphasis>: Repeat the current playlist item (since VLC 0.8.0).
1048 1049
  </para></listitem>
  <listitem><para>
1050
    <emphasis>playlist.setRepeat(false)</emphasis>: Stop repeating the current playlist item (since VLC 0.8.0).
1051
  </para></listitem>
Olivier Teulière's avatar
Olivier Teulière committed