@@ -107,680 +107,680 @@ difficulty to understand how VLC skins work.</para>
<para>OK, let's go for an enumeration of the different tags and their attributes:</para>
<sect3id="Theme">
<sect2id="Theme">
<title>Theme</title>
<para>Main tag, for global attributes</para>
<sect4id="themeversion">
<sect3id="themeversion">
<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>
</sect4>
<sect4id="themetooltipfont">
</sect3>
<sect3id="themetooltipfont">
<title>tooltipfont</title>
<para>Identifiant of a <linklinkend="Font">Font</link> or <linklinkend="BitmapFont">BitmapFont</link>, used for the tooltips (beware that any character not present in a <linklinkend="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>
</sect4>
<sect4id="thememagnet">
</sect3>
<sect3id="thememagnet">
<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>
</sect4>
<sect4id="themealpha">
</sect3>
<sect3id="themealpha">
<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>
</sect4>
<sect4id="thememovealpha">
</sect3>
<sect3id="thememovealpha">
<title>movealpha</title>
<para>Sets the alpha transparency of the windows when they are moving. Same range as <linklinkend="themealpha">alpha</link>.</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>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="ThemeInfo">
<sect2id="ThemeInfo">
<title>ThemeInfo</title>
<para>You can enter here some information about you (but this information is currently unused by VLC...)</para>
<sect4id="themeinfoname">
<sect3id="themeinfoname">
<title>name</title>
<para>Skin name. Not supported yet.</para>
<para><emphasis>Implied.</emphasis></para>
</sect4>
<sect4id="themeinfoauthor">
</sect3>
<sect3id="themeinfoauthor">
<title>author</title>
<para>Author of the skin. Not supported yet.</para>
<para><emphasis>Implied.</emphasis></para>
</sect4>
<sect4id="themeinfoemail">
</sect3>
<sect3id="themeinfoemail">
<title>email</title>
<para>Email of the author. Not supported yet.</para>
<para><emphasis>Implied.</emphasis></para>
</sect4>
<sect4id="themeinfowebpage">
</sect3>
<sect3id="themeinfowebpage">
<title>webpage</title>
<para>Web page in relation with the skin. Not supported yet.</para>
<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>
<sect4id="bitmapid">
<sect3id="bitmapid">
<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>
</sect4>
<sect4id="bitmapfile">
</sect3>
<sect3id="bitmapfile">
<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>
</sect4>
<sect4id="bitmapalphacolor">
</sect3>
<sect3id="bitmapalphacolor">
<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?-->
</sect4>
<sect4id="bitmapnbframes">
</sect3>
<sect3id="bitmapnbframes">
<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>
</sect4>
<sect4id="bitmapfps">
</sect3>
<sect3id="bitmapfps">
<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>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="SubBitmap">
<sect2id="SubBitmap">
<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 <linklinkend="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>
<sect4id="subbitmapid">
<sect3id="subbitmapid">
<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>
</sect4>
<sect4id="subbitmapx">
</sect3>
<sect3id="subbitmapx">
<title>x</title>
<para>Horizontal offset of the sub-bitmap (in pixels), relative to the "parent" bitmap.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="subbitmapy">
</sect3>
<sect3id="subbitmapy">
<title>y</title>
<para>Vertical offset of the sub-bitmap (in pixels), relative to the "parent" bitmap.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="subbitmapwidth">
</sect3>
<sect3id="subbitmapwidth">
<title>width</title>
<para>Width of the sub-bitmap, in pixels.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="subbitmapheight">
</sect3>
<sect3id="subbitmapheight">
<title>height</title>
<para>Height of the SubBitmap, in pixels.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="subbitmapnbframes">
</sect3>
<sect3id="subbitmapnbframes">
<title>nbframes</title>
<para>Same as in <linklinkend="bitmapnbframes">Bitmap</link> tag.</para>
<para>Default value: 1</para>
</sect4>
<sect4id="subbitmapfps">
</sect3>
<sect3id="subbitmapfps">
<title>fps</title>
<para>Same as in <linklinkend="bitmapfps">Bitmap</link> tag.</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Font">
<sect2id="Font">
<title>Font</title>
<para>Declares a font to be used in a <linklinkend="Text">Text</link> or <linklinkend="Playtree">Playtree</link>.</para>
<sect4id="fontid">
<sect3id="fontid">
<title>id</title>
<para>Identifiant of the font that will be used with controls.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="fontfile">
</sect3>
<sect3id="fontfile">
<title>file</title>
<para>This is the file containing a TrueType font.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="fontsize">
</sect3>
<sect3id="fontsize">
<title>size</title>
<para>This is the size of the font, in points.</para>
<para>Default value: 12</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="BitmapFont">
<sect2id="BitmapFont">
<title>BitmapFont</title>
<para><!--TODO--></para>
<sect4id="bitmapfontid">
<sect3id="bitmapfontid">
<title>id</title>
<para>Identifiant of the font that will be used with controls.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="bitmapfontfile">
</sect3>
<sect3id="bitmapfontfile">
<title>file</title>
<para>This is the file containing a bitmap font, à la Winamp.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="bitmapfonttype">
</sect3>
<sect3id="bitmapfonttype">
<title>type</title>
<para>Type of font, one of "digits" or "text".</para>
<para>Default value: digits</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Window">
<sect2id="Window">
<title>Window</title>
<para>A window that will appear on screen.</para>
<sect4id="windowid">
<sect3id="windowid">
<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>
</sect4>
<sect4id="windowvisible">
</sect3>
<sect3id="windowvisible">
<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>
</sect4>
<sect4id="windowx">
</sect3>
<sect3id="windowx">
<title>x</title>
<para>Initial left position of the window.</para>
<para>Default value: 0</para>
</sect4>
<sect4id="windowy">
</sect3>
<sect3id="windowy">
<title>y</title>
<para>Initial top position of the window.</para>
<para>Default value: 0</para>
</sect4>
<sect4id="windowdragdrop">
</sect3>
<sect3id="windowdragdrop">
<title>dragdrop</title>
<para>Indicates whether drag and drop of media files is allowed on this window.</para>
<para>Default value: true</para>
</sect4>
<sect4id="windowplayondrop">
</sect3>
<sect3id="windowplayondrop">
<title>playondrop</title>
<para>Indicates whether a dropped file is played directly (true) or only enqueued (false). This attribute has no effect if <linklinkend="windowdragdrop">dragdrop</link> is set to "false".</para>
<para>Default value: true</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Layout">
<sect2id="Layout">
<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>
<sect4id="layoutid">
<sect3id="layoutid">
<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>
</sect4>
<sect4id="layoutwidth">
</sect3>
<sect3id="layoutwidth">
<title>width</title>
<para><!--TODO: calculate it in VLC :)-->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>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="layoutheight">
</sect3>
<sect3id="layoutheight">
<title>height</title>
<para><!--TODO: calculate it in VLC :)-->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>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="minwidth">
</sect3>
<sect3id="minwidth">
<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 <linklinkend="layoutwidth">width</link> attribute) will be used as minimum width.</para>
<para>Default value: -1</para>
</sect4>
<sect4id="maxwidth">
</sect3>
<sect3id="maxwidth">
<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 <linklinkend="layoutwidth">width</link> attribute) will be used as maximum width.</para>
<para>Default value: -1</para>
</sect4>
<sect4id="minheight">
</sect3>
<sect3id="minheight">
<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 <linklinkend="layoutheight">height</link> attribute) will be used as minimum height.</para>
<para>Default value: -1</para>
</sect4>
<sect4id="maxheight">
</sect3>
<sect3id="maxheight">
<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 <linklinkend="layoutheight">height</link> attribute) will be used as maximum height.</para>
<para>Default value: -1</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Group">
<sect2id="Group">
<title>Group</title>
<para>Adds 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 Window tag). Group tags can be nested.</para>
<sect4id="groupx">
<sect3id="groupx">
<title>x</title>
<para>Try and guess.</para>
<para>Default value: 0</para>
</sect4>
<sect4id="groupy">
</sect3>
<sect3id="groupy">
<title>y</title>
<para>What do you think?</para>
<para>Default value: 0</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Anchor">
<sect2id="Anchor">
<title>Anchor</title>
<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 (<linklinkend="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>
<sect4id="anchorx">
<sect3id="anchorx">
<title>x</title>
<para>Is it really necessary to explain ?</para>
<para>Default value: 0</para>
</sect4>
<sect4id="anchory">
</sect3>
<sect3id="anchory">
<title>y</title>
<para>...</para>
<para>Default value: 0</para>
</sect4>
<sect4id="anchorlefttop">
</sect3>
<sect3id="anchorlefttop">
<title>lefttop</title>
<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>
<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>
</sect4>
<sect4id="anchorpriority">
</sect3>
<sect3id="anchorpriority">
<title>priority</title>
<para>Priority of anchor (see the previous description).</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="anchorpoints">
</sect3>
<sect3id="anchorpoints">
<title>points</title>
<para>Points defining the <linklinkend="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>
</sect4>
<sect4id="anchorrange">
</sect3>
<sect3id="anchorrange">
<title>range</title>
<para>Range of action of the anchor, in pixels.</para>
<para>Default value: 10</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="commattr">
<title>Attributes common to all the controls</title>
<sect2id="commattr">
<title>Common attributes</title>
<para>The following attributes are common to all the controls (Image, Button, Checkbox, Text, Slider, RadialSlider, Playlist, Playtree, Video)</para>
<sect4id="attrid">
<sect3id="attrid">
<title>id</title>
<para>Identifiant of the control. Currently unused.</para>
<para>Horizontal offset of the control, relative to the parent tag (usually <linklinkend="Group">Group</link> or <linklinkend="Layout">Layout</link>).</para>
<para>Default value: 0</para>
</sect4>
<sect4id="y">
</sect3>
<sect3id="y">
<title>y</title>
<para>Vertical offset of the control, relative to the parent tag (usually <linklinkend="Group">Group</link> or <linklinkend="Layout">Layout</link>).</para>
<para>Default value: 0</para>
</sect4>
<sect4id="lefttop">
</sect3>
<sect3id="lefttop">
<title>lefttop</title>
<para>Indicate to which corner of the Layout the top-left-hand corner of this control is attached, in case of resizing. Possible values are 'lefttop', 'leftbottom', 'righttop' and 'rightbottom'.</para>
<para>Default value: lefttop</para>
</sect4>
<sect4id="rightbottom">
</sect3>
<sect3id="rightbottom">
<title>rightbottom</title>
<para>Indicate to which corner of the Layout the bottom-right-hand corner of this control is attached, in case of resizing.</para>
<para>Default value: lefttop</para>
</sect4>
<sect4id="xkeepratio">
</sect3>
<sect3id="xkeepratio">
<title>xkeepratio</title>
<para>When set to true, the behaviour of the horizontal resizing is changed. Instead of taking into account the <linklinkend="lefttop">lefttop</link> and <linklinkend="rightbottom">rightbottom</link> attributes to determine how the control will be moved/resized, only its initial position inside the <linklinkend="Layout">Layout</link> 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 layout, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes).</para>
<para>Default value: false</para>
</sect4>
<sect4id="ykeepratio">
</sect3>
<sect3id="ykeepratio">
<title>ykeepratio</title>
<para>When set to true, the behaviour of the vertical resizing is changed. Instead of taking into account the <linklinkend="lefttop">lefttop</link> and <linklinkend="rightbottom">rightbottom</link> attributes to determine how the control will be moved/resized, only its initial position inside the <linklinkend="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>
<para>This attribute can be particularly useful to keep a control centered in the layout, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes).</para>
<para>Default value: false</para>
</sect4>
<sect4id="help">
</sect3>
<sect3id="help">
<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 <linklinkend="textvars">Text variables</link>).</para>
<para>Default value: </para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Image">
<sect2id="Image">
<title>Image</title>
<para>Create a simple image. Particularly useful for backgrounds.</para>
<para>See the <linklinkend="commattr">Common attributes</link>.</para>
<sect4id="image">
<sect3id="image">
<title>image</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="imageresize">
</sect3>
<sect3id="imageresize">
<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>
<para>Default value: mosaic.</para>
</sect4>
<sect4id="imageaction">
</sect3>
<sect3id="imageaction">
<title>action</title>
<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>
<para>Default value: none</para>
</sect4>
<sect4id="imageaction2">
</sect3>
<sect3id="imageaction2">
<title>action2</title>
<para>Action triggered by a double-click on the control. See <linklinkend="actions">Actions</link> for a list of possible actions. (Since VLC 0.8.5).</para>
<para>Default value: none</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Button">
<sect2id="Button">
<title>Button</title>
<para>Create a button.</para>
<para>See the <linklinkend="commattr">common attributes</link>.</para>
<sect4id="buttonup">
<sect3id="buttonup">
<title>up</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the button is up.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="buttondown">
</sect3>
<sect3id="buttondown">
<title>down</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the button is down.</para>
<para>Default value: none</para>
</sect4>
<sect4id="buttonover">
</sect3>
<sect3id="buttonover">
<title>over</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the mouse is over the button.</para>
<para>Default value: none</para>
</sect4>
<sect4id="buttonaction">
</sect3>
<sect3id="buttonaction">
<title>action</title>
<para>Action executed when the button is clicked. See <linklinkend="actions">Actions</link> for a list of possible actions.</para>
<para>Default value: none</para>
</sect4>
</sect3>
</sect3>
</sect2>
<sect3id="Checkbox">
<sect2id="Checkbox">
<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 <linklinkend="commattr">common attributes</link>.</para>
<sect4id="up1">
<sect3id="up1">
<title>up1</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the checkbox is up in the first state.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="down1">
</sect3>
<sect3id="down1">
<title>down1</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the checkbox is down in the first state.</para>
<para>Default value: none</para>
</sect4>
<sect4id="over1">
</sect3>
<sect3id="over1">
<title>over1</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the mouse is over the checkbox in the first state.</para>
<para>Default value: none</para>
</sect4>
<sect4id="up2">
</sect3>
<sect3id="up2">
<title>up2</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the checkbox is up in the second state.</para>
<para><emphasis>Required.</emphasis></para>
</sect4>
<sect4id="down2">
</sect3>
<sect3id="down2">
<title>down2</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the checkbox is down in the second state.</para>
<para>Default value: none</para>
</sect4>
<sect4id="over2">
</sect3>
<sect3id="over2">
<title>over2</title>
<para>Identifiant of a <linklinkend="Bitmap">Bitmap</link>, used when the mouse is over the checkbox in the second state.</para>
<para>Default value: none</para>
</sect4>
<sect4id="state">
</sect3>
<sect3id="state">
<title>state</title>
<para><linklinkend="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 <linklinkend="windowid">id</link> is "playlist_window": state="playlist_window.isVisible" (or state="not playlist_window.isVisible", depending on the states you chose).</para>