Update to MPlayer SVN rev 34578.
[vaapi:mplayer.git] / DOCS / xml / en / skin.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!-- $Revision: 34546 $ -->
3 <appendix id="skin">
4 <title><application>MPlayer</application> skin format</title>
5
6 <sect1 id="skin-overview">
7 <title>Overview</title>
8
9 <!-- ********** -->
10
11 <sect2 id="skin-overview-components">
12 <title>Skin components</title>
13
14 <para>
15 Skins are quite free-format (unlike the fixed-format skins of
16 <application>Winamp</application>/<application>XMMS</application>,
17 for example), so it is up to you to create something great.
18 </para>
19
20 <para>
21 Currently there are four windows to be decorated: the
22 <link linkend="skin-file-main">main window</link>, the
23 <link linkend="skin-file-subwindow">subwindow</link>, the
24 <link linkend="skin-file-main">playbar</link>, and the
25 <link linkend="skin-file-menu">skin menu</link>.
26
27 <itemizedlist>
28 <listitem>
29   <para>
30   The <emphasis role="bold">main window</emphasis> is where you can control
31   <application>MPlayer</application>. The <emphasis role="bold">playbar</emphasis>
32   shows up in fullscreen mode when moving the mouse to the bottom of
33   the screen. The background of the windows is an image.
34   Various items can (and must) be placed in the window:
35   <emphasis>buttons</emphasis>, <emphasis>potmeters</emphasis> (sliders) and
36   <emphasis>labels</emphasis>.
37   For every item, you must specify its position and size.
38   </para>
39
40   <para>
41   A <emphasis role="bold">button</emphasis> has three states (pressed, released,
42   disabled), thus its image must be divided into three parts vertically. See the
43   <link linkend="skin-button">button</link> item for details.
44   </para>
45
46   <para>
47   A <emphasis role="bold">potmeter</emphasis> (mainly used for the seek bar and
48   volume/balance control) can have any number of phases by dividing its image
49   into different parts below each other. See
50   <link linkend="skin-hpotmeter">hpotmeter</link> and
51   <link linkend="skin-potmeter">potmeter</link> for details.
52   </para>
53
54   <para>
55   <emphasis role="bold">Labels</emphasis> are a bit special: The characters
56   needed to draw them are taken from an image file, and the characters in the
57   image are described by a
58   <link linkend="skin-fonts">font description file</link>.
59   The latter is a plain text file which specifies the x,y position and size of
60   each character in the image (the image file and its font description file
61   form a font <emphasis>together</emphasis>).
62   See <link linkend="skin-dlabel">dlabel</link>
63   and <link linkend="skin-slabel">slabel</link> for details.
64   </para>
65
66   <note><para>
67   All images can have full transparency as described in the section about
68   <link linkend="skin-overview-formats">image formats</link>. If the X server
69   doesn't support the XShape extension, the parts marked transparent will be
70   black. If you'd like to use this feature, the width of the main window's
71   background image must be dividable by 8.
72   </para></note>
73 </listitem>
74
75 <listitem><para>
76   The <emphasis role="bold">subwindow</emphasis> is where the video appears. It
77   can display a specified image if there is no movie loaded (it is quite boring
78   to have an empty window :-)) <emphasis role="bold">Note:</emphasis>
79   transparency is <emphasis role="bold">not allowed</emphasis> here.
80 </para></listitem>
81
82 <listitem>
83   <para>
84   The <emphasis role="bold">skin menu</emphasis> is just a way to control
85   <application>MPlayer</application> by means of menu entries (which can be
86   activated by a middle mouse button click). Two images
87   are required for the menu: one of them is the base image that shows the
88   menu in its normal state, the other one is used to display the selected
89   entries. When you pop up the menu, the first image is shown. If you move
90   the mouse over the menu entries, the currently selected entry is copied
91   from the second image over the menu entry below the mouse pointer
92   (the second image is never shown as a whole).
93   </para>
94   <para>
95   A menu entry is defined by its position and size in the image (see the
96   section about the <link linkend="skin-file-menu">skin menu</link> for
97   details).
98   </para>
99 </listitem>
100 </itemizedlist>
101 </para>
102
103 <para>
104 There is an important thing not mentioned yet: For buttons, potmeters and
105 menu entries to work, <application>MPlayer</application> must know what to
106 do if they are clicked. This is done by <link linkend="skin-gui">messages</link>
107 (events). For these items you must define the messages to be generated when
108 they are clicked.
109 </para>
110 </sect2>
111
112 <sect2 id="skin-overview-formats">
113 <title>Image formats</title>
114
115 <para>Images must be truecolor (24 or 32 bpp) PNGs.</para>
116 <para>
117 In the main window and in the playbar (see below) you can use images with
118 `transparency': Regions filled with the color #FF00FF (magenta) are fully
119 transparent when viewed by <application>MPlayer</application>. This means
120 that you can even have shaped windows if your X server has the XShape extension.
121 </para>
122 </sect2>
123
124 <!-- ********** -->
125
126 <sect2 id="skin-files">
127 <title>Files</title>
128
129 <para>
130 You need the following files to build a skin:
131 <itemizedlist>
132 <listitem><para>
133   The configuration file named <link linkend="skin-file">skin</link> tells
134   <application>MPlayer</application> how to put different parts of the skin
135   together and what to do if you click somewhere in the window.
136 </para></listitem>
137 <listitem><para>
138   The background image for the main window.
139 </para></listitem>
140 <listitem><para>
141   Images for the items in the main window (including one or more font
142   description files needed to draw labels).
143 </para></listitem>
144 <listitem><para>
145   The image to be displayed in the subwindow (optional).
146 </para></listitem>
147 <listitem><para>
148   Two images for the skin menu (they are needed only if you want to create
149   a menu).
150 </para></listitem>
151 </itemizedlist>
152   With the exception of the skin configuration file, you can name the other
153   files whatever you want (but note that font description files must have
154   a <filename>.fnt</filename> extension).
155 </para>
156 </sect2>
157 </sect1>
158
159
160 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
161
162
163 <sect1 id="skin-file">
164 <title>The skin file</title>
165
166 <para>
167 As mentioned above, this is the skin configuration file. It is line oriented;
168 comments start with a '<literal>;</literal>' character and continue until
169 the end of the line, or start with a '<literal>#</literal>' character at the
170 beginning of the line (in that case only spaces and tabs are allowed before the
171 '<literal>#</literal>').
172 </para>
173
174 <para>
175 The file is made up of sections. Each section describes the skin for an
176 application and has the following form:
177 <programlisting>
178 section = <replaceable>section name</replaceable>
179 .
180 .
181 .
182 end
183 </programlisting>
184 </para>
185
186 <para>
187 Currently there is only one application, so you need only one section: its name
188 is <emphasis role="bold">movieplayer</emphasis>.
189 </para>
190
191 <para>
192 Within this section each window is described by a block of the following form:
193 <programlisting>
194 window = <replaceable>window name</replaceable>
195 .
196 .
197 .
198 end
199 </programlisting>
200 </para>
201
202 <para>
203 where <replaceable>window name</replaceable> can be one of these strings:
204 <itemizedlist>
205 <listitem><para>
206   <emphasis role="bold">main</emphasis> - for the main window
207 </para></listitem>
208 <listitem><para>
209   <emphasis role="bold">sub</emphasis> - for the subwindow
210 </para></listitem>
211 <listitem><para>
212   <emphasis role="bold">playbar</emphasis> - for the playbar
213 </para></listitem>
214 <listitem><para>
215   <emphasis role="bold">menu</emphasis> - for the skin menu
216 </para></listitem>
217 </itemizedlist>
218 </para>
219
220 <para>
221 (The sub, playbar and menu blocks are optional - you do not need to decorate
222 the subwindow, have a playbar or create a menu. A default menu is always
223 available by a right mouse button click.)
224 </para>
225
226 <para>
227 Within a window block, you can define each item for the window by a line in
228 this form:
229 <programlisting>item = parameter</programlisting>
230 Where <literal>item</literal> is a string that identifies the type of the GUI
231 item, <literal>parameter</literal> is a numeric or textual value (or a list of
232 values separated by commas).
233 </para>
234
235 <para>
236 Putting the above together, the whole file looks something like this:
237 <programlisting>
238 section = movieplayer
239   window = main
240   ; ... items for main window ...
241   end
242
243   window = sub
244   ; ... items for subwindow ...
245   end
246
247   window = menu
248   ; ... items for menu ...
249   end
250
251   window = playbar
252   ; ... items for playbar ...
253   end
254 end
255 </programlisting>
256 </para>
257
258 <para>
259 The name of an image file must be given without leading directories - images
260 are searched for in the <filename class="directory">skins</filename> directory.
261 You may (but you need not) specify the extension of the file. If the file does
262 not exist, <application>MPlayer</application> tries to load the file
263 <filename>&lt;filename&gt;.&lt;ext&gt;</filename>, where <literal>png</literal>
264 and <literal>PNG</literal> are tried for <filename>&lt;ext&gt;</filename>
265 (in this order). The first matching file will be used.
266 </para>
267
268 <para>
269 Finally some words about positioning. The main window and the subwindow can be
270 placed in the different corners of the screen by giving <literal>X</literal>
271 and <literal>Y</literal> coordinates. <literal>0</literal> is top or left,
272 <literal>-1</literal> is center and <literal>-2</literal> is right or bottom, as
273 shown in this illustration:
274 <informalfigure>
275 <screen>
276 (0, 0)----(-1, 0)----(-2, 0)
277   |          |          |
278   |          |          |
279 (0,-1)----(-1,-1)----(-2,-1)
280   |          |          |
281   |          |          |
282 (0,-2)----(-1,-2)----(-2,-2)
283 </screen>
284 </informalfigure>
285 </para>
286
287 <para>
288 Here is an example to make this clear. Suppose that you have an image called
289 <filename>main.png</filename> that you use for the main window:
290 <programlisting>base = main, -1, -1</programlisting>
291 <application>MPlayer</application> tries to load <filename>main</filename>,
292 <filename>main.png</filename>, <filename>main.PNG</filename> files and centers it.
293 </para>
294
295 <!-- ********** -->
296
297 <sect2 id="skin-file-main">
298 <title>Main window and playbar</title>
299
300 <para>
301 Below is the list of entries that can be used in the
302 '<literal>window = main</literal>' ... '<literal>end</literal>',
303 and the '<literal>window = playbar</literal>' ... '<literal>end</literal>'
304 blocks.
305 </para>
306
307 <variablelist>
308 <varlistentry>
309   <term><literal>
310   <anchor id="skin-main-base"/>base = image, X, Y
311   </literal></term>
312   <listitem>
313   <para>
314   Lets you specify the background image to be used for the main window.
315   The window will appear at the given <literal>X,Y</literal> position on
316   the screen. It will have the size of the image.
317   </para>
318   <warning><para>Transparent regions in the image (colored #FF00FF) appear black
319   on X servers without the XShape extension. The image's width must be dividable
320   by 8.</para></warning>
321   </listitem>
322 </varlistentry>
323
324 <varlistentry>
325   <term><literal>
326   <anchor id="skin-button"/>button = image, X, Y, width, height, message
327   </literal></term>
328   <listitem>
329   <para>
330   Place a button of <literal>width</literal> * <literal>height</literal> size at
331   position <literal>X,Y</literal>. The specified <literal>message</literal> is
332   generated when the button is clicked. The image given by
333   <literal>image</literal> must have three parts below each other (according to
334   the possible states of the button), like this:
335   </para>
336   <informalfigure>
337   <screen>
338 +------------+
339 |  pressed   |
340 +------------+
341 |  released  |
342 +------------+
343 |  disabled  |
344 +------------+<!--
345   --></screen>
346   </informalfigure>
347   </listitem>
348 </varlistentry>
349
350 <varlistentry>
351   <term><literal>
352   <anchor id="skin-decoration"/>decoration = enable|disable
353   </literal></term>
354   <listitem>
355   <para>
356   Enable or disable window manager decoration of the main window. Default is
357   <emphasis role="bold">disable</emphasis>.
358   </para>
359   <note><para>
360   This isn't available for the playbar.
361   </para></note>
362   </listitem>
363 </varlistentry>
364
365 <varlistentry>
366   <term><literal>
367   <anchor id="skin-hpotmeter"/>hpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message
368   </literal></term>
369   <listitem><para>
370   </para></listitem>
371 </varlistentry>
372
373 <varlistentry>
374   <term><literal>
375   <anchor id="skin-vpotmeter"/>vpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message
376   </literal></term>
377   <listitem><para>
378   Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of
379   <literal>width</literal> * <literal>height</literal> size at position
380   <literal>X,Y</literal>. The image can be divided into different parts for the
381   different phases of the potmeter (for example, you can have a pot for volume
382   control that turns from green to red while its value changes from the minimum
383   to the maximum.). <literal>hpotmeter</literal> can have a button that can be
384   dragged horizontally. The parameters are:
385   <itemizedlist>
386   <listitem><para>
387     <literal>button</literal> - the image to be used for the
388     button (must have three parts below each other, like in case of
389     <link linkend="skin-button">button</link>)
390   </para></listitem>
391   <listitem><para>
392     <literal>bwidth</literal>, <literal>bheight</literal> - size
393     of the button
394   </para></listitem>
395   <listitem><para>
396     <literal>phases</literal> - the image to be used for the
397     different phases of the hpotmeter. A special value of <literal>NULL</literal>
398     can be used if you want no such image. The image must be divided into
399     <literal>numphases</literal> parts vertically like this:
400     <informalfigure><screen>
401 +------------+
402 |  phase #1  |
403 +------------+
404 |  phase #2  |
405 +------------+
406      ...
407 +------------+
408 |  phase #n  |
409 +------------+<!--
410     --></screen></informalfigure>
411   </para></listitem>
412   <listitem><para>
413     <literal>numphases</literal> - number of phases stored in the
414     <literal>phases</literal> image
415   </para></listitem>
416   <listitem><para>
417     <literal>default</literal> - default value for hpotmeter
418     (in the range <literal>0</literal> to <literal>100</literal>)
419   </para></listitem>
420   <listitem><para>
421     <literal>X</literal>, <literal>Y</literal> - position for the hpotmeter
422   </para></listitem>
423   <listitem><para>
424     <literal>width</literal>, <literal>height</literal> - width and height
425     of the <literal>hpotmeter</literal>
426   </para></listitem>
427   <listitem><para>
428     <literal>message</literal> - the message to be generated when the
429     value of <literal>hpotmeter</literal> is changed
430   </para></listitem>
431   </itemizedlist>
432   </para></listitem>
433 </varlistentry>
434
435 <varlistentry>
436   <term><literal>
437   <anchor id="skin-potmeter"/>potmeter = phases, numphases, default, X, Y, width, height, message
438   </literal></term>
439   <listitem><para>
440   A <literal>hpotmeter</literal> without a button. (I guess it is meant to be
441   turned around, but it reacts to horizontal dragging only.) For the description
442   of the parameters see <link linkend="skin-hpotmeter">hpotmeter</link>.
443   <literal>phases</literal> can be <literal>NULL</literal>, but it is quite
444   useless, since you cannot see where the <literal>potmeter</literal> is set.
445   </para></listitem>
446 </varlistentry>
447
448 <varlistentry>
449   <term><literal>
450   <anchor id="skin-font"/>font = fontfile
451   </literal></term>
452   <listitem><para>
453   Defines a font. <literal>fontfile</literal> is the name of a font description
454   file with a <filename>.fnt</filename> extension (do not specify the extension
455   here) and is used to refer to the font
456   (see <link linkend="skin-dlabel">dlabel</link>
457   and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined.
458   </para></listitem>
459 </varlistentry>
460
461 <varlistentry>
462   <term><literal>
463   <anchor id="skin-slabel"/>slabel = X, Y, fontfile, "text"
464   </literal></term>
465   <listitem><para>
466   Place a static label at the position <literal>X,Y</literal>.
467   <literal>text</literal> is displayed using the font identified by
468   <literal>fontfile</literal>. The text is just a raw string
469   (<literal>$x</literal> variables do not work) that must be enclosed between
470   double quotes (but the " character cannot be part of the text). The
471   label is displayed using the font identified by <literal>fontfile</literal>.
472   </para></listitem>
473 </varlistentry>
474
475 <varlistentry>
476   <term><literal>
477   <anchor id="skin-dlabel"/>dlabel = X, Y, width, align, fontfile, "text"
478   </literal></term>
479   <listitem>
480   <para>
481   Place a dynamic label at the position <literal>X,Y</literal>. The label is
482   called dynamic because its text is refreshed periodically. The maximum width
483   of the label is given by <literal>width</literal> (its height is the height
484   of a character). If the text to be displayed is wider than that, it will be
485   scrolled,
486   otherwise it is aligned within the specified space by the value of the
487   <literal>align</literal> parameter: <literal>0</literal> is for right,
488   <literal>1</literal> is for center, <literal>2</literal> is for left.
489   </para>
490   <para>
491   The text to be displayed is given by <literal>text</literal>: It must be
492   written between double quotes (but the " character cannot be part of the
493   text). The label is displayed using the font identified by
494   <literal>fontfile</literal>. You can use the following variables in the text:
495   </para>
496
497   <informaltable>
498   <tgroup cols="2">
499   <thead>
500     <row><entry>Variable</entry><entry>Meaning</entry></row>
501   </thead>
502   <tbody>
503   <row>
504     <entry>$1</entry>
505     <entry>elapsed time in <emphasis>hh:mm:ss</emphasis> format</entry>
506   </row>
507   <row>
508     <entry>$2</entry>
509     <entry>elapsed time in <emphasis>mmmm:ss</emphasis> format</entry>
510   </row>
511   <row>
512     <entry>$3</entry>
513     <entry>elapsed time in <emphasis>hh</emphasis> format (hours)</entry>
514   </row>
515   <row>
516     <entry>$4</entry>
517     <entry>elapsed time in <emphasis>mm</emphasis> format (minutes)</entry>
518   </row>
519   <row>
520     <entry>$5</entry>
521     <entry>elapsed time in <emphasis>ss</emphasis> format (seconds)</entry>
522   </row>
523   <row>
524     <entry>$6</entry>
525     <entry>running time in <emphasis>hh:mm:ss</emphasis> format</entry>
526   </row>
527   <row>
528     <entry>$7</entry>
529     <entry>running time in <emphasis>mmmm:ss</emphasis> format</entry>
530   </row>
531   <row>
532     <entry>$8</entry>
533     <entry>elapsed time in <emphasis>h:mm:ss</emphasis> format</entry>
534   </row>
535   <row>
536     <entry>$v</entry>
537     <entry>volume in <emphasis>xxx.xx</emphasis>% format</entry>
538   </row>
539   <row>
540     <entry>$V</entry>
541     <entry>volume in <emphasis>xxx.xx</emphasis> format</entry>
542   </row>
543   <row>
544     <entry>$b</entry>
545     <entry>balance in <emphasis>xxx.xx</emphasis>% format</entry>
546   </row>
547   <row>
548     <entry>$B</entry>
549     <entry>balance in <emphasis>xxx.xx</emphasis> format</entry>
550   </row>
551   <row>
552     <entry>$$</entry>
553     <entry>the $ character</entry>
554   </row>
555   <row>
556     <entry>$a</entry>
557     <entry>a character according to the audio type (none: <keycap>n</keycap>,
558     mono: <keycap>m</keycap>, stereo: <keycap>t</keycap>)</entry>
559   </row>
560   <row>
561     <entry>$t</entry>
562     <entry>track number (DVD, VCD, CD or playlist)</entry>
563   </row>
564   <row>
565     <entry>$o</entry>
566     <entry>filename</entry>
567   </row>
568   <row>
569     <entry>$f</entry>
570     <entry>filename in lower case</entry>
571   </row>
572   <row>
573     <entry>$F</entry>
574     <entry>filename in upper case</entry>
575   </row>
576   <row>
577     <entry>$T</entry>
578     <entry>
579     a character according to the stream type (file: <keycap>f</keycap>,
580     CD: <keycap>a</keycap>, Video CD: <keycap>v</keycap>, DVD: <keycap>d</keycap>,
581     URL: <keycap>u</keycap>)
582     </entry>
583   </row>
584   <row>
585     <entry>$p</entry>
586     <entry>the <keycap>p</keycap> character (if a movie is playing)</entry>
587   </row>
588   <row>
589     <entry>$s</entry>
590     <entry>the <keycap>s</keycap> character (if the movie is stopped)</entry>
591   </row>
592   <row>
593     <entry>$e</entry>
594     <entry>the <keycap>e</keycap> character (if playback is paused)</entry>
595   </row>
596   <row>
597     <entry>$x</entry>
598     <entry>video width</entry>
599   </row>
600   <row>
601     <entry>$y</entry>
602     <entry>video height</entry>
603   </row>
604   <row>
605     <entry>$C</entry>
606     <entry>name of the codec used</entry>
607   </row>
608   </tbody>
609   </tgroup>
610   </informaltable>
611
612   <note><para>
613   The <literal>$a, $T, $p, $s</literal> and <literal>$e</literal>
614   variables all return characters that should be displayed as special symbols
615   (for example, <keycap>e</keycap> is for the pause symbol that usually looks
616   something like ||). You should have a font for normal characters and
617   a different font for symbols. See the section about
618   <link linkend="skin-fonts-symbols">symbols</link> for more information.
619   </para></note>
620   </listitem>
621 </varlistentry>
622 </variablelist>
623 </sect2>
624
625 <!-- ********** -->
626
627 <sect2 id="skin-file-subwindow">
628 <title>Subwindow</title>
629
630 <para>
631 The following entries can be used in the
632 '<literal>window = sub</literal>' . . . '<literal>end</literal>' block.
633 </para>
634
635 <variablelist>
636 <varlistentry>
637   <term><literal>
638   <anchor id="skin-sub-base"/>base = image, X, Y, width, height
639   </literal></term>
640   <listitem><para>
641   The image to be displayed in the window. The window will be as large as the image.
642   <literal>width</literal> and <literal>height</literal>
643   denote the size of the window; they are optional (if they are missing, the
644   window is the same size as the image).
645   </para></listitem>
646 </varlistentry>
647
648 <varlistentry>
649   <term><literal>
650   <anchor id="skin-background"/>background = R, G, B
651   </literal></term>
652   <listitem><para>
653   Lets you set the background color. It is useful if the image is smaller than
654   the window. <literal>R</literal>, <literal>G</literal> and
655   <literal>B</literal> specifies the red, green and blue component of the color
656   (each of them is a decimal number from 0 to 255).
657   </para></listitem>
658 </varlistentry>
659 </variablelist>
660 </sect2>
661
662 <!-- ********** -->
663
664 <sect2 id="skin-file-menu">
665 <title>Skin menu</title>
666
667 <para>
668 As mentioned earlier, the menu is displayed using two images. Normal menu
669 entries are taken from the image specified by the <literal>base</literal> item,
670 while the currently selected entry is taken from the image specified by the
671 <literal>selected</literal> item. You must define the position and size of each
672 menu entry through the menu item.
673 </para>
674
675 <para>
676 The following entries can be used in the
677 '<literal>window = menu</literal>'. . .'<literal>end</literal>' block.
678 </para>
679
680 <variablelist>
681 <varlistentry>
682   <term><literal>
683   <anchor id="skin-menu-base"/>base = image
684   </literal></term>
685   <listitem><para>
686   The image for normal menu entries.
687   </para></listitem>
688 </varlistentry>
689
690 <varlistentry>
691   <term><literal>
692   <anchor id="skin-selected"/>selected = image
693   </literal></term>
694   <listitem><para>
695   The image showing the menu with all entries selected.
696   </para></listitem>
697 </varlistentry>
698
699 <varlistentry>
700   <term><literal>
701   <anchor id="skin-menu"/>menu = X, Y, width, height, message
702   </literal></term>
703   <listitem><para>
704   Defines the <literal>X,Y</literal> position and the size of a menu entry in
705   the image. <literal>message</literal> is the message to be generated when the
706   mouse button is released over the entry.
707   </para></listitem>
708 </varlistentry>
709 </variablelist>
710 </sect2>
711 </sect1>
712
713
714 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
715
716
717 <sect1 id="skin-fonts">
718 <title>Fonts</title>
719 <para>
720 As mentioned in the section about the parts of a skin, a font is defined by an
721 image and a description file. You can place the characters anywhere in the
722 image, but make sure that their position and size is given in the description
723 file exactly.
724 </para>
725
726 <para>
727 The font description file (with <filename>.fnt</filename> extension) can have
728 comments like the skin configuration file starting with '<literal>;</literal>'
729 (or '<literal>#</literal>', but only at the beginning of the line). The file must have a line
730 in the form
731 <anchor id="skin-font-image"/>
732 <programlisting>image = <replaceable>image</replaceable></programlisting>
733 Where <literal><replaceable>image</replaceable></literal> is the name of the
734 image file to be used for the font (you do not have to specify the extension).
735 <anchor id="skin-font-char"/>
736 <programlisting>"char" = X, Y, width, height</programlisting>
737 Here <literal>X</literal> and <literal>Y</literal> specify the position of the
738 <literal>char</literal> character in the image (<literal>0,0</literal> is the
739 upper left corner). <literal>width</literal> and <literal>height</literal> are
740 the dimensions of the character in pixels. The character <literal>char</literal>
741 shall be in UTF-8 encoding.
742 </para>
743
744 <para>
745 This example defines the A, B, C characters using <filename>font.png</filename>.
746 <programlisting>
747 ; Can be "font" instead of "font.png".
748 image = font.png
749
750 ; Three characters are enough for demonstration purposes :-)
751 "A" =  0,0, 7,13
752 "B" =  7,0, 7,13
753 "C" = 14,0, 7,13
754 </programlisting>
755 </para>
756
757 <!-- ********** -->
758
759 <sect2 id="skin-fonts-symbols">
760 <title>Symbols</title>
761
762 <para>
763 Some characters have special meanings when returned by some of the variables
764 used in <link linkend="skin-dlabel">dlabel</link>. These characters are meant
765 to be shown as symbols so that things like a nice DVD logo can be displayed
766 instead of the character '<literal>d</literal>' for a DVD stream.
767 </para>
768
769 <para>
770 The following table lists all the characters that can be used to display
771 symbols (and thus require a different font).
772 </para>
773
774 <informaltable>
775 <tgroup cols="2">
776 <thead>
777   <row><entry>Character</entry><entry>Symbol</entry></row>
778 </thead>
779 <tbody>
780   <row><entry><keycap>p</keycap></entry><entry>play</entry></row>
781   <row><entry><keycap>s</keycap></entry><entry>stop</entry></row>
782   <row><entry><keycap>e</keycap></entry><entry>pause</entry></row>
783   <row><entry><keycap>n</keycap></entry><entry>no sound</entry></row>
784   <row><entry><keycap>m</keycap></entry><entry>mono sound</entry></row>
785   <row><entry><keycap>t</keycap></entry><entry>stereo sound</entry></row>
786   <row><entry><keycap>f</keycap></entry><entry>stream is a file</entry></row>
787   <row><entry><keycap>a</keycap></entry><entry>stream is a CD</entry></row>
788   <row><entry><keycap>v</keycap></entry><entry>stream is a Video CD</entry></row>
789   <row><entry><keycap>d</keycap></entry><entry>stream is a DVD</entry></row>
790   <row><entry><keycap>u</keycap></entry><entry>stream is a URL</entry></row>
791 </tbody>
792 </tgroup>
793 </informaltable>
794 </sect2>
795 </sect1>
796
797
798 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
799
800
801 <sect1 id="skin-gui">
802 <title>GUI messages</title>
803
804 <para>
805 These are the messages that can be generated by buttons, potmeters and
806 menu entries.
807 </para>
808
809 <variablelist>
810 <varlistentry>
811   <term><emphasis role="bold">evNone</emphasis></term>
812   <listitem><para>
813   Empty message, it has no effect.
814   </para></listitem>
815 </varlistentry>
816
817 <title>Playback control:</title>
818 <varlistentry>
819   <term><emphasis role="bold">evPlay</emphasis></term>
820   <listitem><para>
821   Start playing.
822   </para></listitem>
823 </varlistentry>
824
825 <varlistentry>
826   <term><emphasis role="bold">evStop</emphasis></term>
827   <listitem><para>
828   Stop playing.
829   </para></listitem>
830 </varlistentry>
831 </variablelist>
832
833 <varlistentry>
834   <term><emphasis role="bold">evPause</emphasis></term>
835   <listitem><para>
836   Pause playing.
837   </para></listitem>
838 </varlistentry>
839
840 <varlistentry>
841   <term><emphasis role="bold">evPrev</emphasis></term>
842   <listitem><para>
843   Jump to previous track in the playlist.
844   </para></listitem>
845 </varlistentry>
846
847 <varlistentry>
848   <term><emphasis role="bold">evNext</emphasis></term>
849   <listitem><para>
850   Jump to next track in the playlist.
851   </para></listitem>
852 </varlistentry>
853
854 <varlistentry>
855   <term><emphasis role="bold">evLoad</emphasis></term>
856   <listitem><para>
857   Load a file (by opening a file browser window, where you can choose a file).
858   </para></listitem>
859 </varlistentry>
860
861 <varlistentry>
862   <term><emphasis role="bold">evLoadPlay</emphasis></term>
863   <listitem><para>
864   Does the same as <literal>evLoad</literal>, but it automatically starts
865   playing after the file is loaded.
866   </para></listitem>
867 </varlistentry>
868
869 <varlistentry>
870   <term><emphasis role="bold">evLoadAudioFile</emphasis></term>
871   <listitem><para>
872   Loads an audio file (with the file selector).
873   </para></listitem>
874 </varlistentry>
875
876 <varlistentry>
877   <term><emphasis role="bold">evLoadSubtitle</emphasis></term>
878   <listitem><para>
879   Loads a subtitle file (with the file selector).
880   </para></listitem>
881 </varlistentry>
882
883 <varlistentry>
884   <term><emphasis role="bold">evDropSubtitle</emphasis></term>
885   <listitem><para>
886   Disables the currently used subtitle.
887   </para></listitem>
888 </varlistentry>
889
890 <varlistentry>
891   <term><emphasis role="bold">evPlaylist</emphasis></term>
892   <listitem><para>
893   Open/close the playlist window.
894   </para></listitem>
895 </varlistentry>
896
897 <varlistentry>
898   <term><emphasis role="bold">evPlayCD</emphasis></term>
899   <listitem><para>
900   Tries to open the disc in the given CD-ROM drive.
901   </para></listitem>
902 </varlistentry>
903
904 <varlistentry>
905   <term><emphasis role="bold">evPlayVCD</emphasis></term>
906   <listitem><para>
907   Tries to open the disc in the given CD-ROM drive.
908   </para></listitem>
909 </varlistentry>
910
911 <varlistentry>
912   <term><emphasis role="bold">evPlayDVD</emphasis></term>
913   <listitem><para>
914   Tries to open the disc in the given DVD-ROM drive.
915   </para></listitem>
916 </varlistentry>
917
918 <varlistentry>
919   <term><emphasis role="bold">evLoadURL</emphasis></term>
920   <listitem><para>
921   Displays the URL dialog window.
922   </para></listitem>
923 </varlistentry>
924
925 <varlistentry>
926   <term><emphasis role="bold">evPlaySwitchToPause</emphasis></term>
927   <listitem><para>
928   The opposite of <literal>evPauseSwitchToPlay</literal>. This message starts
929   playing and the image for the <literal>evPauseSwitchToPlay</literal> button
930   is displayed (to indicate that the button can be pressed to pause playing).
931   </para></listitem>
932 </varlistentry>
933
934 <varlistentry>
935   <term><emphasis role="bold">evPauseSwitchToPlay</emphasis></term>
936   <listitem><para>
937   Forms a switch together with <literal>evPlaySwitchToPause</literal>. They can
938   be used to have a common play/pause button. Both messages should be assigned
939   to buttons displayed at the very same position in the window. This message
940   pauses playing and the image for the <literal>evPlaySwitchToPause</literal>
941   button is displayed (to indicate that the button can be pressed to continue
942   playing).
943   </para></listitem>
944 </varlistentry>
945
946 <variablelist>
947 <title>Seeking:</title>
948 <varlistentry>
949   <term><emphasis role="bold">evBackward10sec</emphasis></term>
950   <listitem><para>
951   Seek backward 10 seconds.
952   </para></listitem>
953 </varlistentry>
954
955 <varlistentry>
956   <term><emphasis role="bold">evBackward1min</emphasis></term>
957   <listitem><para>
958   Seek backward 1 minute.
959   </para></listitem>
960 </varlistentry>
961
962 <varlistentry>
963   <term><emphasis role="bold">evBackward10min</emphasis></term>
964   <listitem><para>
965   Seek backward 10 minutes.
966   </para></listitem>
967 </varlistentry>
968
969 <varlistentry>
970   <term><emphasis role="bold">evForward10sec</emphasis></term>
971   <listitem><para>
972   Seek forward 10 seconds.
973   </para></listitem>
974 </varlistentry>
975
976 <varlistentry>
977   <term><emphasis role="bold">evForward1min</emphasis></term>
978   <listitem><para>
979   Seek forward 1 minute.
980   </para></listitem>
981 </varlistentry>
982
983 <varlistentry>
984   <term><emphasis role="bold">evForward10min</emphasis></term>
985   <listitem><para>
986   Seek forward 10 minutes.
987   </para></listitem>
988 </varlistentry>
989
990 <varlistentry>
991   <term><emphasis role="bold">evSetMoviePosition</emphasis></term>
992   <listitem><para>
993   Seek to position (can be used by a potmeter; the
994   relative value (0-100%) of the potmeter is used).
995   </para></listitem>
996 </varlistentry>
997 </variablelist>
998
999 <variablelist>
1000 <title>Video control:</title>
1001 <varlistentry>
1002   <term><emphasis role="bold">evHalfSize</emphasis></term>
1003   <listitem><para>
1004   Set the video window to half size.
1005   </para></listitem>
1006 </varlistentry>
1007 <varlistentry>
1008   <term><emphasis role="bold">evDoubleSize</emphasis></term>
1009   <listitem><para>
1010   Set the video window to double size.
1011   </para></listitem>
1012 </varlistentry>
1013 <varlistentry>
1014   <term><emphasis role="bold">evFullScreen</emphasis></term>
1015   <listitem><para>
1016   Switch fullscreen mode on/off.
1017   </para></listitem>
1018 </varlistentry>
1019 <varlistentry>
1020   <term><emphasis role="bold">evNormalSize</emphasis></term>
1021   <listitem><para>
1022   Set the video window to its normal size.
1023   </para></listitem>
1024 </varlistentry>
1025 <varlistentry>
1026   <term><emphasis role="bold">evSetAspect</emphasis></term>
1027   <listitem><para>
1028   Set the video window to its original aspect ratio.
1029   </para></listitem>
1030 </varlistentry>
1031 </variablelist>
1032
1033 <variablelist>
1034 <title>Audio control:</title>
1035 <varlistentry>
1036   <term><emphasis role="bold">evDecVolume</emphasis></term>
1037   <listitem><para>
1038   Decrease volume.
1039   </para></listitem>
1040 </varlistentry>
1041
1042 <varlistentry>
1043   <term><emphasis role="bold">evIncVolume</emphasis></term>
1044   <listitem><para>
1045   Increase volume.
1046   </para></listitem>
1047 </varlistentry>
1048
1049 <varlistentry>
1050   <term><emphasis role="bold">evSetVolume</emphasis></term>
1051   <listitem><para>
1052   Set volume (can be used by a potmeter; the relative
1053   value (0-100%) of the potmeter is used).
1054   </para></listitem>
1055 </varlistentry>
1056
1057 <varlistentry>
1058   <term><emphasis role="bold">evMute</emphasis></term>
1059   <listitem><para>
1060   Mute/unmute the sound.
1061   </para></listitem>
1062 </varlistentry>
1063
1064 <varlistentry>
1065   <term><emphasis role="bold">evSetBalance</emphasis></term>
1066   <listitem><para>
1067   Set balance (can be used by a potmeter; the
1068   relative value (0-100%) of the potmeter is used).
1069   </para></listitem>
1070 </varlistentry>
1071
1072 <varlistentry>
1073   <term><emphasis role="bold">evEqualizer</emphasis></term>
1074   <listitem><para>
1075   Turn the equalizer on/off.
1076   </para></listitem>
1077 </varlistentry>
1078 </variablelist>
1079
1080 <variablelist>
1081 <title>Miscellaneous:</title>
1082 <varlistentry>
1083   <term><emphasis role="bold">evAbout</emphasis></term>
1084   <listitem><para>
1085   Open the about window.
1086   </para></listitem>
1087 </varlistentry>
1088
1089 <varlistentry>
1090   <term><emphasis role="bold">evPreferences</emphasis></term>
1091   <listitem><para>
1092   Open the preferences window.
1093   </para></listitem>
1094 </varlistentry>
1095
1096 <varlistentry>
1097   <term><emphasis role="bold">evSkinBrowser</emphasis></term>
1098   <listitem><para>
1099   Open the skin browser window.
1100   </para></listitem>
1101 </varlistentry>
1102
1103 <varlistentry>
1104   <term><emphasis role="bold">evMenu</emphasis></term>
1105   <listitem><para>
1106   Open the (default) menu.
1107   </para></listitem>
1108 </varlistentry>
1109
1110 <varlistentry>
1111   <term><emphasis role="bold">evIconify</emphasis></term>
1112   <listitem><para>
1113   Iconify the window.
1114   </para></listitem>
1115 </varlistentry>
1116
1117 <varlistentry>
1118   <term><emphasis role="bold">evExit</emphasis></term>
1119   <listitem><para>
1120   Quit the program.
1121   </para></listitem>
1122 </varlistentry>
1123 </variablelist>
1124 </sect1>
1125
1126
1127 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
1128
1129
1130 <sect1 id="skin-quality">
1131 <title>Creating quality skins</title>
1132
1133 <para>
1134 So you have read up on creating skins for the
1135 <application>MPlayer</application> GUI, done your best with the
1136 <application>Gimp</application> and wish to submit your skin to us?
1137 Read on for some guidelines to avoid common mistakes and produce
1138 a high quality skin.
1139 </para>
1140
1141 <para>
1142 We want skins that we add to our repository to conform to certain
1143 quality standards. There are also a number of things that you can do
1144 to make our lives easier.
1145 </para>
1146
1147 <para>
1148 As an example you can look at the <systemitem>Blue</systemitem> skin,
1149 it satisfies all the criteria listed below since version 1.5.
1150 </para>
1151
1152 <itemizedlist>
1153 <listitem><para>
1154   Each skin should come with a
1155   <filename>README</filename> file that contains information about
1156   you, the author, copyright and license notices and anything else
1157   you wish to add. If you wish to have a changelog, this file is a
1158   good place.
1159 </para></listitem>
1160
1161 <listitem><para>
1162   There should be a file <filename>VERSION</filename>
1163   with nothing more than the version number of the skin on a single
1164   line (e.g. 1.0).
1165 </para></listitem>
1166
1167 <listitem><para>
1168   Horizontal and vertical controls (sliders like volume
1169   or position) should have the center of the knob properly centered on
1170   the middle of the slider. It should be possible to move the knob to
1171   both ends of the slider, but not past it.
1172 </para></listitem>
1173
1174 <listitem><para>
1175   Skin elements should have the right sizes declared
1176   in the skin file. If this is not the case you can click outside of
1177   e.g. a button and still trigger it or click inside its area and not
1178   trigger it.
1179 </para></listitem>
1180
1181 <listitem><para>
1182   The <filename>skin</filename> file should be
1183   prettyprinted and not contain tabs. Prettyprinted means that the
1184   numbers should line up neatly in columns.
1185 </para></listitem>
1186 </itemizedlist>
1187
1188 </sect1>
1189 </appendix>