* doc/skins/skins2-howto: document the SubBitmap tag

doc/skins/skins2-howto.xml

@@ -86,12 +86,14 @@ difficulty to understand how VLC skins work.</para>
 <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). Of course, the same bitmap file can be used for many controls, provided you want to display the same image!</para>
+<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>
@@ -164,24 +166,54 @@ difficulty to understand how VLC skins work.</para>
 
 <sect3 id="Bitmap">
   <title>Bitmap</title>
-  <para>Associates a bitmap file 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>
+  <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>
   <sect4 id="bitmapid">
     <title>id</title>
-      <para>This is the identifiant of the bitmap that will be used with controls. Two bitmaps cannot have the same id.</para>
+    <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>
   <sect4 id="bitmapfile">
     <title>file</title>
-      <para>This attribute is used to indicate 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>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>
   <sect4 id="alphacolor">
     <title>alphacolor</title>
-      <para>This is the 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>
+    <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>
-  </sect3>
+</sect3>
+
+<sect3 id="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 <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>
+  <sect4 id="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>
+  <sect4 id="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>
+  <sect4 id="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>
+  <sect4 id="subbitmapwidth">
+    <title>width</title>
+    <para>Width of the sub-bitmap, in pixels.</para>
+    <para><emphasis>Required.</emphasis></para>
+  </sect4>
+  <sect4 id="subbitmapheight">
+    <title>height</title>
+    <para>Height of the SubBitmap, in pixels.</para>
+    <para><emphasis>Required.</emphasis></para>
+  </sect4>
+</sect3>
 
 <sect3 id="Font">
   <title>Font</title>
@@ -201,7 +233,7 @@ difficulty to understand how VLC skins work.</para>
     <para>This is the size of the font, in points.</para>
     <para>Default value: 12</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="BitmapFont">
   <title>BitmapFont</title>
@@ -221,7 +253,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Type of font, one of "digits" or "text".</para>
     <para>Default value: digits</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Window">
   <title>Window</title>
@@ -256,7 +288,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Indicates whether a dropped file is played directly (true) or only enqueued (false). This attribute has no effect if <link linkend="dragdrop">dragdrop</link> is set to "false".</para>
     <para>Default value: true</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Layout">
   <title>Layout</title>
@@ -291,7 +323,7 @@ difficulty to understand how VLC skins work.</para>
     <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>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Group">
   <title>Group</title>
@@ -306,7 +338,7 @@ difficulty to understand how VLC skins work.</para>
     <para>What do you think?</para>
     <para>Default value: 0</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Anchor">
   <title>Anchor</title>
@@ -337,7 +369,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Range of action of the anchor, in pixels. Default is "10".</para>
     <para>Default value: 10</para>
   </sect4>
-  </sect3>
+</sect3>
 
 
 <sect3 id="commattr">
@@ -378,7 +410,7 @@ difficulty to understand how VLC skins work.</para>
     <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>
   </sect4>
- </sect3>
+</sect3>
 
 <sect3 id="Image">
   <title>Image</title>
@@ -399,7 +431,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Action triggered by a click on the control. Possible values are "move", to move the window, or "resizeSE" (SE as in South-East ; other directions will be added in the future) to resize the window in the corresponding direction.</para>
     <para>Default value: none</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Button">
   <title>Button</title>
@@ -425,7 +457,7 @@ difficulty to understand how VLC skins work.</para>
     <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>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Checkbox">
   <title>Checkbox</title>
@@ -486,7 +518,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Tooltip associated with the checkbox in state 2. See also <link linkend="textvars">Text variables</link>.</para>
     <para>Default value: </para>
   </sect4>
- </sect3>
+</sect3>
 
 <sect3 id="Text">
   <title>Text</title>
@@ -512,7 +544,7 @@ difficulty to understand how VLC skins work.</para>
     <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>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Slider">
   <title>Slider</title>
@@ -553,7 +585,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Tooltip associated with the slider. See also <link linkend="textvars">Text variables</link>.</para>
     <para>Default value: </para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="RadialSlider">
   <title>RadialSlider</title>
@@ -589,7 +621,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Tooltip associated with the slider. See also <link linkend="textvars">Text variables</link>.</para>
     <para>Default value: </para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Video">
   <title>Video</title>
@@ -605,7 +637,7 @@ difficulty to understand how VLC skins work.</para>
     <para>Initial height of the control, in pixels.<!--XXX: cannot be deduced?--></para>
     <para>Default value: 0</para>
   </sect4>
-  </sect3>
+</sect3>
 
 <sect3 id="Playlist">
   <title>Playlist</title>