diff options
author | 2006-12-08 11:38:06 +0000 | |
---|---|---|
committer | 2006-12-08 11:38:06 +0000 | |
commit | dc86f6ed17b8e7a702856baefc1d8c3dbd8e229a (patch) | |
tree | c264928fb78e3044f7bf3d8c2eafe2ca607561c4 /DOCS/xml/en/skin.xml | |
parent | bd007d8968b264bda27028d280c042f3e23178fa (diff) |
General reformatting round:
- fix some " -> "
- reindent with more consistency
- visual markup of <sect?> tags
- break overly long lines
- add missing <replaceable> tags in examples
- cola truck standing by
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@21537 b3059339-0415-0410-9bf9-f77b7e298cf2
Diffstat (limited to 'DOCS/xml/en/skin.xml')
-rw-r--r-- | DOCS/xml/en/skin.xml | 922 |
1 files changed, 506 insertions, 416 deletions
diff --git a/DOCS/xml/en/skin.xml b/DOCS/xml/en/skin.xml index 5556847fac..f1a1e5da8b 100644 --- a/DOCS/xml/en/skin.xml +++ b/DOCS/xml/en/skin.xml @@ -5,33 +5,39 @@ <sect1 id="skin-overview"> <title>Overview</title> + <para> It does not really have anything to do with the skin format, but you should -know that <application>MPlayer</application> has <emphasis role="bold">no</emphasis> -builtin skin, so <emphasis role="bold">at least one skin must be installed -in order to be able to use the GUI.</emphasis> +know that <application>MPlayer</application> has +<emphasis role="bold">no</emphasis> builtin skin, so +<emphasis role="bold">at least one skin must be installed in order to be able +to use the GUI.</emphasis> </para> +<!-- ********** --> + <sect2 id="skin-overview-directories"> <title>Directories</title> + <para> The directories searched for skins are (in order): <orderedlist> <listitem><para> -<filename class="directory">$(DATADIR)/skins/</filename> + <filename class="directory">$(DATADIR)/skins/</filename> </para></listitem> <listitem><para> -<filename class="directory">$(PREFIX)/share/mplayer/skins/</filename> + <filename class="directory">$(PREFIX)/share/mplayer/skins/</filename> </para></listitem> <listitem><para> -<filename class="directory">~/.mplayer/skins/</filename> + <filename class="directory">~/.mplayer/skins/</filename> </para></listitem> </orderedlist> </para> <para> -Note that the first path may vary according to the way <application>MPlayer</application> -was configured (see the <option>--prefix</option> and <option>--datadir</option> +Note that the first path may vary according to the way +<application>MPlayer</application> was configured (see the +<option>--prefix</option> and <option>--datadir</option> arguments of the <command>configure</command> script). </para> @@ -42,8 +48,11 @@ listed above, for example: </para> </sect2> +<!-- ********** --> + <sect2 id="skin-overview-formats"> <title>Image formats</title> + <para>Images must be truecolor (24 or 32 bpp) PNGs.</para> <para> In the main window and in the playbar (see below) you can use images with @@ -55,6 +64,7 @@ that you can even have shaped windows if your X server has the XShape extension. <sect2 id="skin-overview-components"> <title>Skin components</title> + <para> Skins are quite free-format (unlike the fixed-format skins of <application>Winamp</application>/<application>XMMS</application>, @@ -70,48 +80,61 @@ Currently there are four windows to be decorated: the by a right click). <itemizedlist> -<listitem><para> +<listitem> + <para> The <emphasis role="bold">main window</emphasis> and/or the <emphasis role="bold">playbar</emphasis> is where you can control <application>MPlayer</application>. The background of the window is an image. - Various items can (and must) be placed in the window: <emphasis>buttons</emphasis>, - <emphasis>potmeters</emphasis> (sliders) and <emphasis>labels</emphasis>. + Various items can (and must) be placed in the window: + <emphasis>buttons</emphasis>, <emphasis>potmeters</emphasis> (sliders) and + <emphasis>labels</emphasis>. For every item, you must specify its position and size. -</para><para> + </para> + + <para> A <emphasis role="bold">button</emphasis> has three states (pressed, released, disabled), thus its image must be divided into three parts vertically. See the <link linkend="skin-button">button</link> item for details. -</para><para> + </para> + + <para> A <emphasis role="bold">potmeter</emphasis> (mainly used for the seek bar and volume/balance control) can have any number of phases by dividing its image into different parts below each other. See <link linkend="skin-hpotmeter">hpotmeter</link> and <link linkend="skin-potmeter">potmeter</link> for details. -</para><para> + </para> + + <para> <emphasis role="bold">Labels</emphasis> are a bit special: The characters needed to draw them are taken from an image file, and the characters in the - image are described by a <link linkend="skin-fonts">font description file</link>. + image are described by a + <link linkend="skin-fonts">font description file</link>. The latter is a plain text file which specifies the x,y position and size of each character in the image (the image file and its font description file - form a font <emphasis>together</emphasis>). See <link linkend="skin-dlabel">dlabel</link> + form a font <emphasis>together</emphasis>). + See <link linkend="skin-dlabel">dlabel</link> and <link linkend="skin-slabel">slabel</link> for details. -</para> -<note><para>All images can have full transparency as described in the section about + </para> + + <note><para> + All images can have full transparency as described in the section about <link linkend="skin-overview-formats">image formats</link>. If the X server doesn't support the XShape extension, the parts marked transparent will be black. If you'd like to use this feature, the width of the main window's background image must be dividable by 8. -</para></note> + </para></note> </listitem> <listitem><para> The <emphasis role="bold">subwindow</emphasis> is where the movie appears. It can display a specified image if there is no movie loaded (it is quite boring - to have an empty window :-)) <emphasis role="bold">Note:</emphasis> transparency - is <emphasis role="bold">not allowed</emphasis> here. + to have an empty window :-)) <emphasis role="bold">Note:</emphasis> + transparency is <emphasis role="bold">not allowed</emphasis> here. </para></listitem> -<listitem><para> +<listitem> + <para> The <emphasis role="bold">skin menu</emphasis> is just a way to control <application>MPlayer</application> by means of menu entries. Two images are required for the menu: one of them is the base image that shows the @@ -120,24 +143,30 @@ by a right click). the mouse over the menu entries, the currently selected entry is copied from the second image over the menu entry below the mouse pointer (the second image is never shown as a whole). -</para><para> + </para> + <para> A menu entry is defined by its position and size in the image (see the - section about the <link linkend="skin-file-menu">skin menu</link> for details). -</para></listitem> + section about the <link linkend="skin-file-menu">skin menu</link> for + details). + </para> +</listitem> </itemizedlist> </para> <para> - There is an important thing not mentioned yet: For buttons, potmeters and - menu entries to work, <application>MPlayer</application> must know what to - do if they are clicked. This is done by <link linkend="skin-gui">messages</link> - (events). For these items you must define the messages to be generated when - they are clicked. +There is an important thing not mentioned yet: For buttons, potmeters and +menu entries to work, <application>MPlayer</application> must know what to +do if they are clicked. This is done by <link linkend="skin-gui">messages</link> +(events). For these items you must define the messages to be generated when +they are clicked. </para> </sect2> +<!-- ********** --> + <sect2 id="skin-files"> <title>Files</title> + <para> You need the following files to build a skin: <itemizedlist> @@ -168,12 +197,17 @@ You need the following files to build a skin: </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-file"> <title>The skin file</title> + <para> As mentioned above, this is the skin configuration file. It is line oriented; -comment lines start with a '<literal>;</literal>' character at the beginning -of the line (only spaces and tabs are allowed before the '<literal>;</literal>'). +comment lines start with a '<literal>;</literal>' character at the beginning of +the line (only spaces and tabs are allowed before the '<literal>;</literal>'). </para> <para> @@ -189,8 +223,8 @@ end </para> <para> -Currently there is only one application, so you need only one section: its name is -<emphasis role="bold">movieplayer</emphasis>. +Currently there is only one application, so you need only one section: its name +is <emphasis role="bold">movieplayer</emphasis>. </para> <para> @@ -207,10 +241,18 @@ end <para> where <replaceable>window name</replaceable> can be one of these strings: <itemizedlist> -<listitem><para><emphasis role="bold">main</emphasis> - for the main window</para></listitem> -<listitem><para><emphasis role="bold">sub</emphasis> - for the subwindow</para></listitem> -<listitem><para><emphasis role="bold">menu</emphasis> - for the skin menu</para></listitem> -<listitem><para><emphasis role="bold">playbar</emphasis> - playbar</para></listitem> +<listitem><para> + <emphasis role="bold">main</emphasis> - for the main window +</para></listitem> +<listitem><para> + <emphasis role="bold">sub</emphasis> - for the subwindow +</para></listitem> +<listitem><para> + <emphasis role="bold">menu</emphasis> - for the skin menu +</para></listitem> +<listitem><para> + <emphasis role="bold">playbar</emphasis> - playbar +</para></listitem> </itemizedlist> </para> @@ -262,12 +304,19 @@ and <literal>PNG</literal> are tried for <filename><ext></filename> </para> <para> -Finally some words about positioning. The main window and the subwindow can -be placed in the different corners of the screen by giving <literal>X</literal> and -<literal>Y</literal> coordinates. <literal>0</literal> is top or left, +Here is an example to make this clear. Suppose that you have an image called +<filename>main.png</filename> that you use for the main window: +<programlisting>base = main, -1, -1</programlisting> +<application>MPlayer</application> tries to load <filename>main</filename>, +<filename>main.png</filename>, <filename>main.PNG</filename> files. +</para> + +<para> +Finally some words about positioning. The main window and the subwindow can be +placed in the different corners of the screen by giving <literal>X</literal> +and <literal>Y</literal> coordinates. <literal>0</literal> is top or left, <literal>-1</literal> is center and <literal>-2</literal> is right or bottom, as shown in this illustration: -</para> <informalfigure> <screen> (0, 0)----(-1, 0)----(-2, 0) @@ -279,18 +328,13 @@ shown in this illustration: (0,-2)----(-1,-2)----(-2,-2) </screen> </informalfigure> - -<para> -Here is an example to make this clear. Suppose that you have an image called -<filename>main.png</filename> that you use for the main window: -<programlisting>base = main, -1, -1</programlisting> -<application>MPlayer</application> tries to load <filename>main</filename>, -<filename>main.png</filename>, <filename>main.PNG</filename> files. </para> +<!-- ********** --> <sect2 id="skin-file-main"> <title>Main window and playbar</title> + <para> Below is the list of entries that can be used in the '<literal>window = main</literal>' ... '<literal>end</literal>', @@ -303,40 +347,44 @@ blocks. <term><literal> <anchor id="skin-main-base"/>base = image, X, Y </literal></term> - <listitem><para> -Lets you specify the background image to be used for the main window. -The window will appear at the given <literal>X,Y</literal> position on -the screen The window will have the size of the image. - </para> - <note><para>These coordinates do not currently work for the display window.</para></note> - <warning><para>Transparent regions in the image (colored #FF00FF) appear black - on X servers without the XShape extension. The image's width must be dividable - by 8.</para></warning> - </listitem> + <listitem> + <para> + Lets you specify the background image to be used for the main window. + The window will appear at the given <literal>X,Y</literal> position on + the screen The window will have the size of the image. + </para> + <note><para> + These coordinates do not currently work for the display window. + </para></note> + <warning><para>Transparent regions in the image (colored #FF00FF) appear black + on X servers without the XShape extension. The image's width must be dividable + by 8.</para></warning> + </listitem> </varlistentry> <varlistentry> <term><literal> <anchor id="skin-button"/>button = image, X, Y, width, height, message </literal></term> - <listitem><para> -Place a button of <literal>width</literal> * <literal>height</literal> size at -position <literal>X,Y</literal>. The specified <literal>message</literal> is -generated when the button is clicked. The image given by <literal>image</literal> -must have three parts below each other (according to the possible states of the -button), like this: -</para> -<informalfigure> -<screen> + <listitem> + <para> + Place a button of <literal>width</literal> * <literal>height</literal> size at + position <literal>X,Y</literal>. The specified <literal>message</literal> is + generated when the button is clicked. The image given by + <literal>image</literal> must have three parts below each other (according to + the possible states of the button), like this: + </para> + <informalfigure> + <screen> +------------+ | pressed | +------------+ | released | +------------+ | disabled | -+------------+ -</screen> -</informalfigure> ++------------+<!-- + --></screen> + </informalfigure> </listitem> </varlistentry> @@ -344,11 +392,14 @@ button), like this: <term><literal> <anchor id="skin-decoration"/>decoration = enable|disable </literal></term> - <listitem><para> -Enable or disable window manager decoration of the main window. Default is -<emphasis role="bold">disable</emphasis>. - </para> - <note><para>This doesn't work for the display window, there is no need to.</para></note> + <listitem> + <para> + Enable or disable window manager decoration of the main window. Default is + <emphasis role="bold">disable</emphasis>. + </para> + <note><para> + This doesn't work for the display window, there is no need to. + </para></note> </listitem> </varlistentry> @@ -357,8 +408,7 @@ Enable or disable window manager decoration of the main window. Default is <anchor id="skin-hpotmeter"/>hpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> - - </para></listitem> + </para></listitem> </varlistentry> <varlistentry> @@ -366,29 +416,29 @@ Enable or disable window manager decoration of the main window. Default is <anchor id="skin-vpotmeter"/>vpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> -Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of -<literal>width</literal> * <literal>height</literal> size at position -<literal>X,Y</literal>. The image can be divided into different parts for the -different phases of the potmeter (for example, you can have a pot for volume -control that turns from green to red while its value changes from the minimum -to the maximum.). <literal>hpotmeter</literal> can have a button that can be -dragged horizontally. The parameters are: - </para> - <itemizedlist> - <listitem><para><literal>button</literal> - the image to be used for the + Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of + <literal>width</literal> * <literal>height</literal> size at position + <literal>X,Y</literal>. The image can be divided into different parts for the + different phases of the potmeter (for example, you can have a pot for volume + control that turns from green to red while its value changes from the minimum + to the maximum.). <literal>hpotmeter</literal> can have a button that can be + dragged horizontally. The parameters are: + <itemizedlist> + <listitem><para> + <literal>button</literal> - the image to be used for the button (must have three parts below each other, like in case of <link linkend="skin-button">button</link>) - </para></listitem> - <listitem><para><literal>bwidth</literal>, <literal>bheight</literal> - size + </para></listitem> + <listitem><para> + <literal>bwidth</literal>, <literal>bheight</literal> - size of the button - </para></listitem> - <listitem><para><literal>phases</literal> - the image to be used for the - different phases of the hpotmeter. A special value of <literal>NULL</literal> - can be used if you want no such image. The image must be divided into - <literal>numphases</literal> parts vertically like this: - </para> -<informalfigure> -<screen> + </para></listitem> + <listitem><para> + <literal>phases</literal> - the image to be used for the + different phases of the hpotmeter. A special value of <literal>NULL</literal> + can be used if you want no such image. The image must be divided into + <literal>numphases</literal> parts vertically like this: + <informalfigure><screen> +------------+ | phase #1 | +------------+ @@ -397,27 +447,30 @@ dragged horizontally. The parameters are: ... +------------+ | phase #n | -+------------+ -</screen> -</informalfigure> - </listitem> - <listitem><para><literal>numphases</literal> - number of phases stored in the ++------------+<!-- + --></screen></informalfigure> + </para></listitem> + <listitem><para> + <literal>numphases</literal> - number of phases stored in the <literal>phases</literal> image - </para></listitem> - <listitem><para><literal>default</literal> - default value for hpotmeter + </para></listitem> + <listitem><para> + <literal>default</literal> - default value for hpotmeter (in the range <literal>0</literal> to <literal>100</literal>) - </para></listitem> - <listitem><para><literal>X</literal>, <literal>Y</literal> - position for the hpotmeter - </para></listitem> - <listitem><para><literal>width</literal>, <literal>height</literal> - width and height + </para></listitem> + <listitem><para> + <literal>X</literal>, <literal>Y</literal> - position for the hpotmeter + </para></listitem> + <listitem><para> + <literal>width</literal>, <literal>height</literal> - width and height of the <literal>hpotmeter</literal> - </para></listitem> - <listitem><para><literal>message</literal> - the message to be generated when the + </para></listitem> + <listitem><para> + <literal>message</literal> - the message to be generated when the value of <literal>hpotmeter</literal> is changed - </para></listitem> - </itemizedlist> - - </listitem> + </para></listitem> + </itemizedlist> + </para></listitem> </varlistentry> <varlistentry> @@ -425,12 +478,12 @@ dragged horizontally. The parameters are: <anchor id="skin-potmeter"/>potmeter = phases, numphases, default, X, Y, width, height, message </literal></term> <listitem><para> -A <literal>hpotmeter</literal> without a button. (I guess it is meant to be -turned around, but it reacts to horizontal dragging only.) For the description -of the parameters see <link linkend="skin-hpotmeter">hpotmeter</link>. -<literal>phases</literal> can be <literal>NULL</literal>, but it is quite useless, -since you cannot see where the <literal>potmeter</literal> is set. - </para></listitem> + A <literal>hpotmeter</literal> without a button. (I guess it is meant to be + turned around, but it reacts to horizontal dragging only.) For the description + of the parameters see <link linkend="skin-hpotmeter">hpotmeter</link>. + <literal>phases</literal> can be <literal>NULL</literal>, but it is quite + useless, since you cannot see where the <literal>potmeter</literal> is set. + </para></listitem> </varlistentry> <varlistentry> @@ -438,11 +491,12 @@ since you cannot see where the <literal>potmeter</literal> is set. <anchor id="skin-font"/>font = fontfile, fontid </literal></term> <listitem><para> -Defines a font. <literal>fontfile</literal> is the name of a font description file -with a <filename>.fnt</filename> extension (do not specify the extension here). -<literal>fontid</literal> is used to refer to the font (see <link linkend="skin-dlabel">dlabel</link> -and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined. - </para></listitem> + Defines a font. <literal>fontfile</literal> is the name of a font description + file with a <filename>.fnt</filename> extension (do not specify the extension + here). <literal>fontid</literal> is used to refer to the font + (see <link linkend="skin-dlabel">dlabel</link> + and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined. + </para></listitem> </varlistentry> <varlistentry> @@ -450,12 +504,13 @@ and <link linkend="skin-slabel">slabel</link>). Up to 25 fonts can be defined. <anchor id="skin-slabel"/>slabel = X, Y, fontid, "text" </literal></term> <listitem><para> -Place a static label at the position <literal>X,Y</literal>. <literal>text</literal> -is displayed using the font identified by <literal>fontid</literal>. The text is -just a raw string (<literal>$x</literal> variables do not work) that must be enclosed -between double quotes (but the " character cannot be part of the text). The -label is displayed using the font identified by <literal>fontid</literal>. - </para></listitem> + Place a static label at the position <literal>X,Y</literal>. + <literal>text</literal> is displayed using the font identified by + <literal>fontid</literal>. The text is just a raw string + (<literal>$x</literal> variables do not work) that must be enclosed between + double quotes (but the " character cannot be part of the text). The + label is displayed using the font identified by <literal>fontid</literal>. + </para></listitem> </varlistentry> <varlistentry> @@ -463,154 +518,159 @@ label is displayed using the font identified by <literal>fontid</literal>. <anchor id="skin-dlabel"/>dlabel = X, Y, length, align, fontid, "text" </literal></term> <listitem> -<para> -Place a dynamic label at the position <literal>X,Y</literal>. The label is called -dynamic because its text is refreshed periodically. The maximum length of the -label is given by <literal>length</literal> (its height is the height of a -character). If the text to be displayed is wider than that, it will be scrolled, -otherwise it is aligned within the specified space by the value of the -<literal>align</literal> parameter: <literal>0</literal> is for right, -<literal>1</literal> is for center, <literal>2</literal> is for left. -</para> -<para> -The text to be displayed is given by <literal>text</literal>: It must be written -between double quotes (but the " character cannot be part of the text). The -label is displayed using the font identified by <literal>fontid</literal>. You -can use the following variables in the text: -</para> - -<informaltable> -<tgroup cols="2"> -<thead> - <row><entry>Variable</entry><entry>Meaning</entry></row> -</thead> -<tbody> -<row> -<entry>$1</entry> -<entry>play time in <emphasis>hh:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$2</entry> -<entry>play time in <emphasis>mmmm:ss</emphasis> format</entry> -</row> -<row> -<entry>$3</entry> -<entry>play time in <emphasis>hh</emphasis> format (hours)</entry> -</row> -<row> -<entry>$4</entry> -<entry>play time in <emphasis>mm</emphasis> format (minutes)</entry> -</row> -<row> -<entry>$5</entry> -<entry>play time in <emphasis>ss</emphasis> format (seconds)</entry> -</row> -<row> -<entry>$6</entry> -<entry>movie length in <emphasis>hh:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$7</entry> -<entry>movie length in <emphasis>mmmm:ss</emphasis> format</entry> -</row> -<row> -<entry>$8</entry> -<entry>play time in <emphasis>h:mm:ss</emphasis> format</entry> -</row> -<row> -<entry>$v</entry> -<entry>volume in <emphasis>xxx.xx</emphasis>% format</entry> -</row> -<row> -<entry>$V</entry> -<entry>volume in <emphasis>xxx.xx</emphasis> format</entry> -</row> -<row> -<entry>$b</entry> -<entry>balance in <emphasis>xxx.xx</emphasis>% format</entry> -</row> -<row> -<entry>$B</entry> -<entry>balance in <emphasis>xxx.xx</emphasis> format</entry> -</row> -<row> -<entry>$$</entry> -<entry>the $ character</entry> -</row> -<row> -<entry>$a</entry> -<entry>a character according to the audio type (none: <literal>n</literal>, -mono: <literal>m</literal>, stereo: <literal>t</literal>)</entry> -</row> -<row> -<entry>$t</entry> -<entry>track number (in playlist)</entry> -</row> -<row> -<entry>$o</entry> -<entry>filename</entry> -</row> -<row> -<entry>$f</entry> -<entry>filename in lower case</entry> -</row> -<row> -<entry>$F</entry> -<entry>filename in upper case</entry> -</row> -<row> -<entry>$T</entry> -<entry>a character according to the stream type (file: <literal>f</literal>, -Video CD: <literal>v</literal>, DVD: <literal>d</literal>, URL: <literal>u</literal>)</entry> -</row> -<row> -<entry>$p</entry> -<entry>the <keycap>p</keycap> character (if a movie is playing and the font has -the <keycap>p</keycap> character)</entry> -</row> -<row> -<entry>$s</entry> -<entry>the <keycap>s</keycap> character (if the movie is stopped and the font has -the <keycap>s</keycap> character)</entry> -</row> -<row> -<entry>$e</entry> -<entry>the <keycap>e</keycap> character (if playback is paused and the font has -the <keycap>e</keycap> character)</entry> -</row> -<row> -<entry>$x</entry> -<entry>movie width</entry> -</row> -<row> -<entry>$y</entry> -<entry>movie height</entry> -</row> -<row> -<entry>$C</entry> -<entry>name of the codec used</entry> -</row> - -</tbody> -</tgroup> -</informaltable> -</listitem> - + <para> + Place a dynamic label at the position <literal>X,Y</literal>. The label is + called dynamic because its text is refreshed periodically. The maximum length + of the label is given by <literal>length</literal> (its height is the height + of a character). If the text to be displayed is wider than that, it will be + scrolled, + otherwise it is aligned within the specified space by the value of the + <literal>align</literal> parameter: <literal>0</literal> is for right, + <literal>1</literal> is for center, <literal>2</literal> is for left. + </para> + <para> + The text to be displayed is given by <literal>text</literal>: It must be + written between double quotes (but the " character cannot be part of the + text). The label is displayed using the font identified by + <literal>fontid</literal>. You can use the following variables in the text: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row><entry>Variable</entry><entry>Meaning</entry></row> + </thead> + <tbody> + <row> + <entry>$1</entry> + <entry>play time in <emphasis>hh:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$2</entry> + <entry>play time in <emphasis>mmmm:ss</emphasis> format</entry> + </row> + <row> + <entry>$3</entry> + <entry>play time in <emphasis>hh</emphasis> format (hours)</entry> + </row> + <row> + <entry>$4</entry> + <entry>play time in <emphasis>mm</emphasis> format (minutes)</entry> + </row> + <row> + <entry>$5</entry> + <entry>play time in <emphasis>ss</emphasis> format (seconds)</entry> + </row> + <row> + <entry>$6</entry> + <entry>movie length in <emphasis>hh:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$7</entry> + <entry>movie length in <emphasis>mmmm:ss</emphasis> format</entry> + </row> + <row> + <entry>$8</entry> + <entry>play time in <emphasis>h:mm:ss</emphasis> format</entry> + </row> + <row> + <entry>$v</entry> + <entry>volume in <emphasis>xxx.xx</emphasis>% format</entry> + </row> + <row> + <entry>$V</entry> + <entry>volume in <emphasis>xxx.xx</emphasis> format</entry> + </row> + <row> + <entry>$b</entry> + <entry>balance in <emphasis>xxx.xx</emphasis>% format</entry> + </row> + <row> + <entry>$B</entry> + <entry>balance in <emphasis>xxx.xx</emphasis> format</entry> + </row> + <row> + <entry>$$</entry> + <entry>the $ character</entry> + </row> + <row> + <entry>$a</entry> + <entry>a character according to the audio type (none: <literal>n</literal>, + mono: <literal>m</literal>, stereo: <literal>t</literal>)</entry> + </row> + <row> + <entry>$t</entry> + <entry>track number (in playlist)</entry> + </row> + <row> + <entry>$o</entry> + <entry>filename</entry> + </row> + <row> + <entry>$f</entry> + <entry>filename in lower case</entry> + </row> + <row> + <entry>$F</entry> + <entry>filename in upper case</entry> + </row> + <row> + <entry>$T</entry> + <entry> + a character according to the stream type (file: <literal>f</literal>, + Video CD: <literal>v</literal>, DVD: <literal>d</literal>, + URL: <literal>u</literal>) + </entry> + </row> + <row> + <entry>$p</entry> + <entry>the <keycap>p</keycap> character (if a movie is playing and the font + has the <keycap>p</keycap> character)</entry> + </row> + <row> + <entry>$s</entry> + <entry>the <keycap>s</keycap> character (if the movie is stopped and the + font has the <keycap>s</keycap> character)</entry> + </row> + <row> + <entry>$e</entry> + <entry>the <keycap>e</keycap> character (if playback is paused and the font + has the <keycap>e</keycap> character)</entry> + </row> + <row> + <entry>$x</entry> + <entry>movie width</entry> + </row> + <row> + <entry>$y</entry> + <entry>movie height</entry> + </row> + <row> + <entry>$C</entry> + <entry>name of the codec used</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <note><para> + The <literal>$a, $T, $p, $s</literal> and <literal>$e</literal> + variables all return characters that should be displayed as special symbols + (for example, <keycap>e</keycap> is for the pause symbol that usually looks + something like ||). You should have a font for normal characters and + a different font for symbols. See the section about + <link linkend="skin-fonts-symbols">symbols</link> for more information. + </para></note> + </listitem> </varlistentry> </variablelist> - -<note><para> -The <literal>$a, $T, $p, $s</literal> and <literal>$e</literal> -variables all return characters that should be displayed as special symbols (for -example, <keycap>e</keycap> is for the pause symbol that usually looks something -like ||). You should have a font for normal characters and a different font for -symbols. See the section about <link linkend="skin-fonts-symbols">symbols</link> -for more information. -</para></note> </sect2> +<!-- ********** --> + <sect2 id="skin-file-subwindow"> <title>Subwindow</title> + <para> The following entries can be used in the '<literal>window = sub</literal>' . . . '<literal>end</literal>' block. @@ -622,14 +682,15 @@ The following entries can be used in the <anchor id="skin-sub-base"/>base = image, X, Y, width, height </literal></term> <listitem><para> -The image to be displayed in the window. The window will appear at the given -<literal>X,Y</literal> position on the screen (<literal>0,0</literal> is the -top left corner). You can specify <literal>-1</literal> for center and <literal>-2</literal> -for right (<literal>X</literal>) and bottom (<literal>Y</literal>). The window -will be as large as the image. <literal>width</literal> and <literal>height</literal> -denote the size of the window; they are optional (if they are missing, the -window is the same size as the image). - </para></listitem> + The image to be displayed in the window. The window will appear at the given + <literal>X,Y</literal> position on the screen (<literal>0,0</literal> is the + top left corner). You can specify <literal>-1</literal> for center and + <literal>-2</literal> for right (<literal>X</literal>) and bottom + (<literal>Y</literal>). The window will be as large as the image. + <literal>width</literal> and <literal>height</literal> + denote the size of the window; they are optional (if they are missing, the + window is the same size as the image). + </para></listitem> </varlistentry> <varlistentry> @@ -637,17 +698,20 @@ window is the same size as the image). <anchor id="skin-background"/>background = R, G, B </literal></term> <listitem><para> -Lets you set the background color. It is useful if the image is smaller than -the window. <literal>R</literal>, <literal>G</literal> and <literal>B</literal> -specifies the red, green and blue component of the color (each of them is a -decimal number from 0 to 255). - </para></listitem> + Lets you set the background color. It is useful if the image is smaller than + the window. <literal>R</literal>, <literal>G</literal> and + <literal>B</literal> specifies the red, green and blue component of the color + (each of them is a decimal number from 0 to 255). + </para></listitem> </varlistentry> </variablelist> </sect2> +<!-- ********** --> + <sect2 id="skin-file-menu"> <title>Skin menu</title> + <para> As mentioned earlier, the menu is displayed using two images. Normal menu entries are taken from the image specified by the <literal>base</literal> item, @@ -667,8 +731,8 @@ The following entries can be used in the <anchor id="skin-menu-base"/>base = image </literal></term> <listitem><para> -The image for normal menu entries. - </para></listitem> + The image for normal menu entries. + </para></listitem> </varlistentry> <varlistentry> @@ -676,8 +740,8 @@ The image for normal menu entries. <anchor id="skin-selected"/>selected = image </literal></term> <listitem><para> -The image showing the menu with all entries selected. - </para></listitem> + The image showing the menu with all entries selected. + </para></listitem> </varlistentry> <varlistentry> @@ -685,22 +749,26 @@ The image showing the menu with all entries selected. <anchor id="skin-menu"/>menu = X, Y, width, height, message </literal></term> <listitem><para> -Defines the <literal>X,Y</literal> position and the size of a menu entry in -the image. <literal>message</literal> is the message to be generated when the -mouse button is released over the entry. - </para></listitem> + Defines the <literal>X,Y</literal> position and the size of a menu entry in + the image. <literal>message</literal> is the message to be generated when the + mouse button is released over the entry. + </para></listitem> </varlistentry> </variablelist> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-fonts"> <title>Fonts</title> <para> As mentioned in the section about the parts of a skin, a font is defined by an -image and a description file. You can place the characters anywhere in the image, -but make sure that their position and size is given in the description file -exactly. +image and a description file. You can place the characters anywhere in the +image, but make sure that their position and size is given in the description +file exactly. </para> <para> @@ -732,14 +800,18 @@ image = font.png </programlisting> </para> +<!-- ********** --> + <sect2 id="skin-fonts-symbols"> <title>Symbols</title> + <para> Some characters have special meanings when returned by some of the variables used in <link linkend="skin-dlabel">dlabel</link>. These characters are meant to be shown as symbols so that things like a nice DVD logo can be displayed instead of the character '<literal>d</literal>' for a DVD stream. </para> + <para> The following table lists all the characters that can be used to display symbols (and thus require a different font). @@ -751,24 +823,29 @@ symbols (and thus require a different font). <row><entry>Character</entry><entry>Symbol</entry></row> </thead> <tbody> -<row><entry><keycap>p</keycap></entry><entry>play</entry></row> -<row><entry><keycap>s</keycap></entry><entry>stop</entry></row> -<row><entry><keycap>e</keycap></entry><entry>pause</entry></row> -<row><entry><keycap>n</keycap></entry><entry>no sound</entry></row> -<row><entry><keycap>m</keycap></entry><entry>mono sound</entry></row> -<row><entry><keycap>t</keycap></entry><entry>stereo sound</entry></row> -<row><entry><keycap>f</keycap></entry><entry>stream is a file</entry></row> -<row><entry><keycap>v</keycap></entry><entry>stream is a Video CD</entry></row> -<row><entry><keycap>d</keycap></entry><entry>stream is a DVD</entry></row> -<row><entry><keycap>u</keycap></entry><entry>stream is a URL</entry></row> + <row><entry><keycap>p</keycap></entry><entry>play</entry></row> + <row><entry><keycap>s</keycap></entry><entry>stop</entry></row> + <row><entry><keycap>e</keycap></entry><entry>pause</entry></row> + <row><entry><keycap>n</keycap></entry><entry>no sound</entry></row> + <row><entry><keycap>m</keycap></entry><entry>mono sound</entry></row> + <row><entry><keycap>t</keycap></entry><entry>stereo sound</entry></row> + <row><entry><keycap>f</keycap></entry><entry>stream is a file</entry></row> + <row><entry><keycap>v</keycap></entry><entry>stream is a Video CD</entry></row> + <row><entry><keycap>d</keycap></entry><entry>stream is a DVD</entry></row> + <row><entry><keycap>u</keycap></entry><entry>stream is a URL</entry></row> </tbody> </tgroup> </informaltable> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-gui"> <title>GUI messages</title> + <para> These are the messages that can be generated by buttons, potmeters and menu entries. @@ -779,49 +856,50 @@ menu entries. <varlistentry> <term><emphasis role="bold">evNext</emphasis></term> <listitem><para> -Jump to next track in the playlist. - </para></listitem> + Jump to next track in the playlist. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPause</emphasis></term> <listitem><para> -Forms a switch together with <literal>evPlaySwitchToPause</literal>. They can -be used to have a common play/pause button. Both messages should be assigned to -buttons displayed at the very same position in the window. This message pauses -playing and the image for the <literal>evPlaySwitchToPause</literal> button is -displayed (to indicate that the button can be pressed to continue playing). - </para></listitem> + Forms a switch together with <literal>evPlaySwitchToPause</literal>. They can + be used to have a common play/pause button. Both messages should be assigned + to buttons displayed at the very same position in the window. This message + pauses playing and the image for the <literal>evPlaySwitchToPause</literal> + button is displayed (to indicate that the button can be pressed to continue + playing). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlay</emphasis></term> <listitem><para> -Start playing. - </para></listitem> + Start playing. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlaySwitchToPause</emphasis></term> <listitem><para> -The opposite of <literal>evPauseSwitchToPlay</literal>. This message starts -playing and the image for the <literal>evPauseSwitchToPlay</literal> button -is displayed (to indicate that the button can be pressed to pause playing). - </para></listitem> + The opposite of <literal>evPauseSwitchToPlay</literal>. This message starts + playing and the image for the <literal>evPauseSwitchToPlay</literal> button + is displayed (to indicate that the button can be pressed to pause playing). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPrev</emphasis></term> <listitem><para> -Jump to previous track in the playlist. - </para></listitem> + Jump to previous track in the playlist. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evStop</emphasis></term> <listitem><para> -Stop playing. - </para></listitem> + Stop playing. + </para></listitem> </varlistentry> </variablelist> @@ -830,51 +908,51 @@ Stop playing. <varlistentry> <term><emphasis role="bold">evBackward10sec</emphasis></term> <listitem><para> -Seek backward 10 seconds. - </para></listitem> + Seek backward 10 seconds. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evBackward1min</emphasis></term> <listitem><para> -Seek backward 1 minute. - </para></listitem> + Seek backward 1 minute. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evBackward10min</emphasis></term> <listitem><para> -Seek backward 10 minutes. - </para></listitem> + Seek backward 10 minutes. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward10sec</emphasis></term> <listitem><para> -Seek forward 10 seconds. - </para></listitem> + Seek forward 10 seconds. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward1min</emphasis></term> <listitem><para> -Seek forward 1 minute. - </para></listitem> + Seek forward 1 minute. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evForward10min</emphasis></term> <listitem><para> -Seek forward 10 minutes. - </para></listitem> + Seek forward 10 minutes. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetMoviePosition</emphasis></term> <listitem><para> -Seek to position (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - </para></listitem> + Seek to position (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> </variablelist> @@ -883,26 +961,26 @@ relative value (0-100%) of the potmeter is used). <varlistentry> <term><emphasis role="bold">evHalfSize</emphasis></term> <listitem><para> -Set the movie window to half size. - </para></listitem> + Set the movie window to half size. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDoubleSize</emphasis></term> <listitem><para> -Set the movie window to double size. - </para></listitem> + Set the movie window to double size. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evFullScreen</emphasis></term> <listitem><para> -Switch fullscreen mode on/off. - </para></listitem> + Switch fullscreen mode on/off. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evNormalSize</emphasis></term> <listitem><para> -Set the movie window to its normal size. - </para></listitem> + Set the movie window to its normal size. + </para></listitem> </varlistentry> </variablelist> @@ -911,66 +989,66 @@ Set the movie window to its normal size. <varlistentry> <term><emphasis role="bold">evDecAudioBufDelay</emphasis></term> <listitem><para> -Decrease audio buffer delay. - </para></listitem> + Decrease audio buffer delay. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDecBalance</emphasis></term> <listitem><para> -Decrease balance. - </para></listitem> + Decrease balance. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDecVolume</emphasis></term> <listitem><para> -Decrease volume. - </para></listitem> + Decrease volume. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncAudioBufDelay</emphasis></term> <listitem><para> -Increase audio buffer delay. - </para></listitem> + Increase audio buffer delay. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncBalance</emphasis></term> <listitem><para> -Increase balance. - </para></listitem> + Increase balance. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIncVolume</emphasis></term> <listitem><para> -Increase volume. - </para></listitem> + Increase volume. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evMute</emphasis></term> <listitem><para> -Mute/unmute the sound. - </para></listitem> + Mute/unmute the sound. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetBalance</emphasis></term> <listitem><para> -Set balance (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - </para></listitem> + Set balance (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetVolume</emphasis></term> <listitem><para> -Set volume (can be used by a potmeter; the relative -value (0-100%) of the potmeter is used). - </para></listitem> + Set volume (can be used by a potmeter; the relative + value (0-100%) of the potmeter is used). + </para></listitem> </varlistentry> </variablelist> @@ -979,126 +1057,129 @@ value (0-100%) of the potmeter is used). <varlistentry> <term><emphasis role="bold">evAbout</emphasis></term> <listitem><para> -Open the about window. - </para></listitem> + Open the about window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evDropSubtitle</emphasis></term> <listitem><para> -Disables the currently used subtitle. - </para></listitem> + Disables the currently used subtitle. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evEqualizer</emphasis></term> <listitem><para> -Turn the equalizer on/off. - </para></listitem> + Turn the equalizer on/off. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evExit</emphasis></term> <listitem><para> -Quit the program. - </para></listitem> + Quit the program. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evIconify</emphasis></term> <listitem><para> -Iconify the window. - </para></listitem> + Iconify the window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoad</emphasis></term> <listitem><para> -Load a file (by opening a file browser window, where you can choose a file). - </para></listitem> + Load a file (by opening a file browser window, where you can choose a file). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadPlay</emphasis></term> <listitem><para> -Does the same as <literal>evLoad</literal>, but it automatically starts playing after -the file is loaded. - </para></listitem> + Does the same as <literal>evLoad</literal>, but it automatically starts + playing after the file is loaded. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadSubtitle</emphasis></term> <listitem><para> -Loads a subtitle file (with the fileselector) - </para></listitem> + Loads a subtitle file (with the fileselector) + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evLoadAudioFile</emphasis></term> <listitem><para> -Loads an audio file (with the fileselector) - </para></listitem> + Loads an audio file (with the fileselector) + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evNone</emphasis></term> <listitem><para> -Empty message, it has no effect (except maybe in Subversion versions :-)). - </para></listitem> + Empty message, it has no effect (except maybe in Subversion versions :-)). + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlaylist</emphasis></term> <listitem><para> -Open/close the playlist window. - </para></listitem> + Open/close the playlist window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlayDVD</emphasis></term> <listitem><para> -Tries to open the disc in the given DVD-ROM drive. - </para></listitem> + Tries to open the disc in the given DVD-ROM drive. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPlayVCD</emphasis></term> <listitem><para> -Tries to open the disc in the given CD-ROM drive. - </para></listitem> + Tries to open the disc in the given CD-ROM drive. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evPreferences</emphasis></term> <listitem><para> -Open the preferences window. - </para></listitem> + Open the preferences window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetAspect</emphasis></term> <listitem><para> -Sets displayed image aspect. - </para></listitem> + Sets displayed image aspect. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSetURL</emphasis></term> <listitem><para> -Displays the URL dialog window. - </para></listitem> + Displays the URL dialog window. + </para></listitem> </varlistentry> <varlistentry> <term><emphasis role="bold">evSkinBrowser</emphasis></term> <listitem><para> -Open the skin browser window. - </para></listitem> + Open the skin browser window. + </para></listitem> </varlistentry> </variablelist> - </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="skin-quality"> <title>Creating quality skins</title> @@ -1122,31 +1203,40 @@ it satisfies all the criteria listed below since version 1.5. </para> <itemizedlist> - <listitem><para>Each skin should come with a +<listitem><para> + Each skin should come with a <filename>README</filename> file that contains information about you, the author, copyright and license notices and anything else you wish to add. If you wish to have a changelog, this file is a - good place.</para></listitem> + good place. +</para></listitem> - <listitem><para>There should be a file <filename>VERSION</filename> +<listitem><para> + There should be a file <filename>VERSION</filename> with nothing more than the version number of the skin on a single - line (e.g. 1.0).</para></listitem> + line (e.g. 1.0). +</para></listitem> - <listitem><para>Horizontal and vertical controls (sliders like volume +<listitem><para> + Horizontal and vertical controls (sliders like volume or position) should have the center of the knob properly centered on the middle of the slider. It should be possible to move the knob to - both ends of the slider, but not past it.</para></listitem> + both ends of the slider, but not past it. +</para></listitem> - <listitem><para>Skin elements should have the right sizes declared +<listitem><para> + Skin elements should have the right sizes declared in the skin file. If this is not the case you can click outside of e.g. a button and still trigger it or click inside its area and not - trigger it.</para></listitem> + trigger it. +</para></listitem> - <listitem><para>The <filename>skin</filename> file should be +<listitem><para> + The <filename>skin</filename> file should be prettyprinted and not contain tabs. Prettyprinted means that the - numbers should line up neatly in columns.</para></listitem> + numbers should line up neatly in columns. +</para></listitem> </itemizedlist> </sect1> - </appendix> |