<title>HowTo create your own skin</title>
<copyright>
-<year>2004-2006</year>
+<year>2004-2012</year>
<holder>
the VideoLAN project
</holder>
</authorgroup>
<keywordset>
+ <keyword>VLC</keyword>
<keyword>Skin</keyword>
<keyword>XML</keyword>
<keyword>Bezier</keyword>
<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>
-<para>The XML file used for the VLC skins follows a predefined DTD. You can find this DTD <ulink url="http://trac.videolan.org/vlc/file/trunk/share/skins2/skin.dtd">in VLC SVN</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>
+<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>
<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>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>
</sect3>
+ <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>
</sect2>
<title>fps</title>
<para>Same as in <link linkend="bitmapfps">Bitmap</link> tag.</para>
</sect3>
+ <sect3 id="subbitmaploop">
+ <title>loop</title>
+ <para>Same as in <link linkend="bitmaploop">Bitmap</link> tag.</para>
+ </sect3>
</sect2>
<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>
+ <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>
</sect3>
<sect3 id="windowvisible">
<title>visible</title>
<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>
+ <para><emphasis>Required.</emphasis></para>
</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>
+ <para><emphasis>Required.</emphasis></para>
</sect3>
<sect3 id="panellefttop">
<title>lefttop</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>
</sect3>
+ <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>
+ <sect3 id="x-margin">
+ <title>x-margin</title>
+ <para>Coupled with position, x-margin 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>
+ <para>Default value: 0</para>
+ </sect3>
+ <sect3 id="y-margin">
+ <title>y-margin</title>
+ <para>Coupled with position, y-margin 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>
+ <para>Default value: 0</para>
+ </sect3>
+ <sect3 id="x-offset">
+ <title>x-offset</title>
+ <para>Coupled with position and x-margin, this parameter moves the widget horizontally by this offset from the position computed above.</para>
+ <para>Default value: 0</para>
+ </sect3>
+ <sect3 id="y-offset">
+ <title>y-offset</title>
+ <para>Coupled with position and y-margin, this parameter moves the widget vertically by this offset from the position computed above.</para>
+ <para>Default value: 0</para>
+ </sect3>
</sect2>
<sect2 id="Image">
<sect3 id="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>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>
<para>Default value: mosaic.</para>
</sect3>
<sect3 id="imageaction">
<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>
</sect3>
+ <sect3 id="imageart">
+ <title>art</title>
+ <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>
+ <para>Default value: false</para>
+ </sect3>
</sect2>
<sect2 id="Button">
<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>
</sect3>
+ <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>
</sect2>
<sect2 id="Checkbox">
<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>
</sect3>
+ <sect3 id="focus">
+ <title>focus</title>
+ <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>
+ <para>Default value: true</para>
+ </sect3>
<sect3 id="textscrolling">
<title>scrolling</title>
<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>
<listitem><para>
<emphasis>vlc.snapshot()</emphasis>: Take a snapshot (since VLC 0.8.5).
</para></listitem>
+ <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>
<listitem><para>
<emphasis>vlc.onTop()</emphasis>: Toggle the "Always on top" status (since VLC 0.8.0).
</para></listitem>
<listitem><para>
<emphasis>$V</emphasis>: Value of the volume (from 0 to 100 --> useful for a percentage).
</para></listitem>
+ <listitem><para>
+ <emphasis>$R</emphasis>: Value of the playback speed rate. Available from VLC 2.0
+ </para></listitem>
<listitem><para>
<emphasis>$T</emphasis>: Current time (the output format is H:MM:SS).
</para></listitem>
<listitem><para>
<emphasis>vlc.isSeekable</emphasis>: True when the stream is seekable, false otherwise. This one can be used if you want to display a slider only when seeking is allowed.
</para></listitem>
+ <listitem><para>
+ <emphasis>vlc.canRecord</emphasis>: True if the stream can be recorded, false otherwise. (since vlc1.1)
+ </para></listitem>
+ <listitem><para>
+ <emphasis>vlc.isRecording</emphasis>: True if the stream is being recorded, false otherwise. (since vlc1.1)
+ </para></listitem>
<listitem><para>
<emphasis>vlc.isMute</emphasis>: True when the sound is mute (in VLC, not on your OS), false otherwise.
</para></listitem>
<emphasis>dvd.isActive</emphasis>: True when a DVD is currently playing. This variable can be used to display buttons associated to the <link linkend="dvdactions">dvd.* actions</link> only when needed (since VLC 0.8.5).
</para></listitem>
<listitem><para>
- <emphasis>WindowID.isMaximized</emphasis>: True when the window whose <link linkend="windowid">id</link> is "WindowID" is maximized, false otherwise.
+ <emphasis>WindowID.isMaximized</emphasis>: True when the window whose <link linkend="windowid">id</link> is "WindowID" is maximized, false otherwise (since VLC 0.9.0).
</para></listitem>
<listitem><para>
<emphasis>WindowID.isVisible</emphasis>: True when the window whose <link linkend="windowid">id</link> is "WindowID" is visible, false otherwise.
<para>A box inside a container box always defines how it should react when its container box is resized. Two different mechanisms are provided: corners anchoring (useful when resizing of the inner box is wanted, for example) and constant ratio (mainly useful to keep the inner box centered inside its parent):</para>
<itemizedlist>
<listitem><para>
- <emphasis>corners anchoring</emphasis>: The top-left-hand corner (TL) and the bottom-right-hand corner (BR) of the inner box are "tied" to corners of the container box (TL, TR, BL or BR). When any resizing occurs, tied corners move together, which can move or resize the inner box. For example, if the TL corner of the inner box is tied to the TL corner of the container (let's write it TL/TL), and if the BR corner of the inner box is also tied to the TL corner of the container box (BR/TL), the inner box will not be resized, and will always stay at the same place (this is the default behaviour). If we have TL/TL and TL/BL, the inner box is resized vertically its container is resized. If we have TL/TR and BR/TR, the inner box moves with the TR corner of its container. We could even define TL/BR and BR/TL, in which case increasing the size of the container box would shrink the size of the inner box... until it disappears completely!
+ <emphasis>corners anchoring</emphasis>: The top-left-hand corner (TL) and the bottom-right-hand corner (BR) of the inner box are "tied" to corners of the container box (TL, TR, BL or BR). When any resizing occurs, tied corners move together, which can move or resize the inner box. For example, if the TL corner of the inner box is tied to the TL corner of the container (let's write it TL/TL), and if the BR corner of the inner box is also tied to the TL corner of the container box (BR/TL), the inner box will not be resized, and will always stay at the same place (this is the default behaviour). If we have TL/TL and BR/BL, the inner box is resized vertically when its container is resized. If we have TL/TR and BR/TR, the inner box moves with the TR corner of its container. We could even define TL/BR and BR/TL, in which case increasing the size of the container box would shrink the size of the inner box... until it disappears completely!
</para>
<para>This mechanism is controlled by the <link linkend="lefttop">lefttop</link> and <link linkend="rightbottom">rightbottom</link> attributes of the controls.
</para></listitem>
<sect2>
<title>Relative paths</title>
-
- <para>
-For the Bitmap tags, do not use absolute paths but relative paths (they are relative to the XML file directory), so that your skin can be reused by anybody without a particular file structure.
- </para>
+ <para>For the Bitmap tags, do not use absolute paths but relative paths (they are relative to the XML file directory), so that your skin can be reused by anybody without a particular file structure.</para>
</sect2>
<sect2>
<title>Get inspiration</title>
-
- <para>
-In order to use plainly the possibilities given, you should look at how existing skins are made, it may give you ideas for your own skins...
- </para>
+ <para>In order to use plainly the possibilities given, you should look at how existing skins are made, it may give you ideas for your own skins... You can also consult <ulink url="http://wiki.videolan.org/DefaultSkinRequirements">on the wiki</ulink> a list of features usually expected from a skin. </para>
</sect2>
<sect2>
<title>Submit your skin!</title>
-
- <para>
-Once your skin is finished, you can share it with other people. The easiest way is probably to send it by email to vlc -at- videolan -dot- org, so that we can put it on the website with the other ones.
- </para>
+ <para>Once your skin is finished, you can share it with other people. The easiest way is probably to send it by email to vlc -at- videolan -dot- org, so that we can put it on the website with the other ones. You can also post it in the <ulink url="http://forum.videolan.org/viewforum.php?f=15">skins forum</ulink>. Feel free to ask for support there if you have any problems...</para>
</sect2>
</sect1>
projects / vlc / blobdiff