<commit_before><?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">

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

<article id="skin-creation-howto">

<articleinfo>

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

<copyright>
<year>2004</year>
<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>Teulire</surname>
  </author>
</authorgroup>

<keywordset>
    <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 id="bezier">
<title>Bezier curves</title>

<para>One cool thing with VLC sliders is that they are not necessarily rectilinear, but they can follow any Bezier curve. So if you want to have a slider moving on a half-circle, or even doing a loop, you can!</para>

<para>This is not the place to explain how Bezier curves work (see <ulink url="http://astronomy.swin.edu.au/~pbourke/curves/bezier/">http://astronomy.swin.edu.au/~pbourke/curves/bezier/</ulink> for a nice introduction), the main thing to know is that a Bezier curve can be characterized by a set of points. Once you have them (thanks to the <link linkend="CurveMaker">CurveMaker</link> utility for example<!--XXX: deprecated-->), you just need to enter the list of points in the <link linkend="sliderpoints">points</link> attribute. Here is an example with 3 points: points="(2,50),(45,120),(88,50)".</para>

<para>Bezier curves can be used with the <link linkend="Slider">Slider</link> and <link linkend="Anchor">Anchor</link> tags:</para>

<itemizedlist>
  <listitem><para>For sliders, it defines the curve followed by the cursor of the slider. This curve is of course invisible, so if you want a visible background for your <link linkend="Slider">Slider</link> you need to provide it yourself using the <link linkend="Image">Image</link> tag.</para></listitem>
  <listitem><para>For anchors, the use of Bezier curves is more anecdotic. Its purpose is to have non-ponctual anchor, the whole curve becoming the anchor. In this case, a ponctual anchor (and only a ponctual one) can be attracted by any point of the curve, if it is in its range of action. In fact, you can consider the curve as an easy way to define at once many anchors that share the same properties (except their position, of course :)).</para></listitem>
</itemizedlist>

<note><para>The coordinates are relative to the upper-left corner of the control (i.e. to its <link linkend="x">x</link> and <link linkend="y">y</link> attributes).</para></note>

</sect1>

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

<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>

<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>

<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>

</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>

<para>The XML file used for the VLC skins follows a predefined DTD. You can find this DTD <link linkend="http://trac.videolan.org/vlc/file/trunk/share/skins2/skin.dtd">in VLC SVN</link>, 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>OK, let's go for an enumeration of the different tags and their attributes:</para>

<sect3 id="Theme">
  <title>Theme</title>
  <para>Main tag, for global attributes</para>
      <sect4 id="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>
    <sect4 id="themetooltipfont"><commit_msg> * doc/skins/skins2-howto.xml: Fixed a link<commit_after><?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">

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

<article id="skin-creation-howto">

<articleinfo>

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

<copyright>
<year>2004</year>
<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>Teulire</surname>
  </author>
</authorgroup>

<keywordset>
    <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 id="bezier">
<title>Bezier curves</title>

<para>One cool thing with VLC sliders is that they are not necessarily rectilinear, but they can follow any Bezier curve. So if you want to have a slider moving on a half-circle, or even doing a loop, you can!</para>

<para>This is not the place to explain how Bezier curves work (see <ulink url="http://astronomy.swin.edu.au/~pbourke/curves/bezier/">http://astronomy.swin.edu.au/~pbourke/curves/bezier/</ulink> for a nice introduction), the main thing to know is that a Bezier curve can be characterized by a set of points. Once you have them (thanks to the <link linkend="CurveMaker">CurveMaker</link> utility for example<!--XXX: deprecated-->), you just need to enter the list of points in the <link linkend="sliderpoints">points</link> attribute. Here is an example with 3 points: points="(2,50),(45,120),(88,50)".</para>

<para>Bezier curves can be used with the <link linkend="Slider">Slider</link> and <link linkend="Anchor">Anchor</link> tags:</para>

<itemizedlist>
  <listitem><para>For sliders, it defines the curve followed by the cursor of the slider. This curve is of course invisible, so if you want a visible background for your <link linkend="Slider">Slider</link> you need to provide it yourself using the <link linkend="Image">Image</link> tag.</para></listitem>
  <listitem><para>For anchors, the use of Bezier curves is more anecdotic. Its purpose is to have non-ponctual anchor, the whole curve becoming the anchor. In this case, a ponctual anchor (and only a ponctual one) can be attracted by any point of the curve, if it is in its range of action. In fact, you can consider the curve as an easy way to define at once many anchors that share the same properties (except their position, of course :)).</para></listitem>
</itemizedlist>

<note><para>The coordinates are relative to the upper-left corner of the control (i.e. to its <link linkend="x">x</link> and <link linkend="y">y</link> attributes).</para></note>

</sect1>

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

<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>

<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>

<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>

</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>

<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>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>

<sect3 id="Theme">
  <title>Theme</title>
  <para>Main tag, for global attributes</para>
      <sect4 id="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>
    <sect4 id="themetooltipfont">
{'fraction_non_alphanumeric': 0.11109429393067959, 'fraction_numerical': 0.007946117753897381, 'mean_word_length': 4.613848768054376, 'pattern_counts': {'":': 0, '<': 329, '<?xml version=': 2, '>': 329, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 5}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2102428', 'n_tokens_mistral': 3971, 'n_tokens_neox': 3817, 'n_words': 1733}