From dc86f6ed17b8e7a702856baefc1d8c3dbd8e229a Mon Sep 17 00:00:00 2001 From: torinthiel Date: Fri, 8 Dec 2006 11:38:06 +0000 Subject: General reformatting round: - fix some " -> " - reindent with more consistency - visual markup of tags - break overly long lines - add missing tags in examples - cola truck standing by git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@21537 b3059339-0415-0410-9bf9-f77b7e298cf2 --- DOCS/xml/en/skin.xml | 922 ++++++++++++++++++++++++++++----------------------- 1 file changed, 506 insertions(+), 416 deletions(-) (limited to 'DOCS/xml/en/skin.xml') 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 @@ Overview + It does not really have anything to do with the skin format, but you should -know that MPlayer has no -builtin skin, so at least one skin must be installed -in order to be able to use the GUI. +know that MPlayer has +no builtin skin, so +at least one skin must be installed in order to be able +to use the GUI. + + Directories + The directories searched for skins are (in order): -$(DATADIR)/skins/ + $(DATADIR)/skins/ -$(PREFIX)/share/mplayer/skins/ + $(PREFIX)/share/mplayer/skins/ -~/.mplayer/skins/ + ~/.mplayer/skins/ -Note that the first path may vary according to the way MPlayer -was configured (see the and +Note that the first path may vary according to the way +MPlayer was configured (see the + and arguments of the configure script). @@ -42,8 +48,11 @@ listed above, for example: + + Image formats + Images must be truecolor (24 or 32 bpp) PNGs. 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. Skin components + Skins are quite free-format (unlike the fixed-format skins of Winamp/XMMS, @@ -70,48 +80,61 @@ Currently there are four windows to be decorated: the by a right click). - + + The main window and/or the playbar is where you can control MPlayer. The background of the window is an image. - Various items can (and must) be placed in the window: buttons, - potmeters (sliders) and labels. + Various items can (and must) be placed in the window: + buttons, potmeters (sliders) and + labels. For every item, you must specify its position and size. - + + + A button has three states (pressed, released, disabled), thus its image must be divided into three parts vertically. See the button item for details. - + + + A potmeter (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 hpotmeter and potmeter for details. - + + + Labels 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 font description file. + image are described by a + font description file. 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 together). See dlabel + form a font together). + See dlabel and slabel for details. - -All images can have full transparency as described in the section about + + + + All images can have full transparency as described in the section about image formats. 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. - + The subwindow 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 :-)) Note: transparency - is not allowed here. + to have an empty window :-)) Note: + transparency is not allowed here. - + + The skin menu is just a way to control MPlayer 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). - + + A menu entry is defined by its position and size in the image (see the - section about the skin menu for details). - + section about the skin menu for + details). + + - There is an important thing not mentioned yet: For buttons, potmeters and - menu entries to work, MPlayer must know what to - do if they are clicked. This is done by messages - (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, MPlayer must know what to +do if they are clicked. This is done by messages +(events). For these items you must define the messages to be generated when +they are clicked. + + Files + You need the following files to build a skin: @@ -168,12 +197,17 @@ You need the following files to build a skin: + + + + The skin file + As mentioned above, this is the skin configuration file. It is line oriented; -comment lines start with a ';' character at the beginning -of the line (only spaces and tabs are allowed before the ';'). +comment lines start with a ';' character at the beginning of +the line (only spaces and tabs are allowed before the ';'). @@ -189,8 +223,8 @@ end -Currently there is only one application, so you need only one section: its name is -movieplayer. +Currently there is only one application, so you need only one section: its name +is movieplayer. @@ -207,10 +241,18 @@ end where window name can be one of these strings: -main - for the main window -sub - for the subwindow -menu - for the skin menu -playbar - playbar + + main - for the main window + + + sub - for the subwindow + + + menu - for the skin menu + + + playbar - playbar + @@ -262,12 +304,19 @@ and PNG are tried for <ext> -Finally some words about positioning. The main window and the subwindow can -be placed in the different corners of the screen by giving X and -Y coordinates. 0 is top or left, +Here is an example to make this clear. Suppose that you have an image called +main.png that you use for the main window: +base = main, -1, -1 +MPlayer tries to load main, +main.png, main.PNG files. + + + +Finally some words about positioning. The main window and the subwindow can be +placed in the different corners of the screen by giving X +and Y coordinates. 0 is top or left, -1 is center and -2 is right or bottom, as shown in this illustration: - (0, 0)----(-1, 0)----(-2, 0) @@ -279,18 +328,13 @@ shown in this illustration: (0,-2)----(-1,-2)----(-2,-2) - - -Here is an example to make this clear. Suppose that you have an image called -main.png that you use for the main window: -base = main, -1, -1 -MPlayer tries to load main, -main.png, main.PNG files. + Main window and playbar + Below is the list of entries that can be used in the 'window = main' ... 'end', @@ -303,40 +347,44 @@ blocks. base = image, X, Y - -Lets you specify the background image to be used for the main window. -The window will appear at the given X,Y position on -the screen The window will have the size of the image. - - These coordinates do not currently work for the display window. - 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. - + + + Lets you specify the background image to be used for the main window. + The window will appear at the given X,Y position on + the screen The window will have the size of the image. + + + These coordinates do not currently work for the display window. + + 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. + button = image, X, Y, width, height, message - -Place a button of width * height size at -position X,Y. The specified message is -generated when the button is clicked. The image given by image -must have three parts below each other (according to the possible states of the -button), like this: - - - + + + Place a button of width * height size at + position X,Y. The specified message is + generated when the button is clicked. The image given by + image must have three parts below each other (according to + the possible states of the button), like this: + + + +------------+ | pressed | +------------+ | released | +------------+ | disabled | -+------------+ - - ++------------+ + @@ -344,11 +392,14 @@ button), like this: decoration = enable|disable - -Enable or disable window manager decoration of the main window. Default is -disable. - - This doesn't work for the display window, there is no need to. + + + Enable or disable window manager decoration of the main window. Default is + disable. + + + This doesn't work for the display window, there is no need to. + @@ -357,8 +408,7 @@ Enable or disable window manager decoration of the main window. Default is hpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message - - + @@ -366,29 +416,29 @@ Enable or disable window manager decoration of the main window. Default is vpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message -Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of -width * height size at position -X,Y. 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.). hpotmeter can have a button that can be -dragged horizontally. The parameters are: - - - button - the image to be used for the + Place a horizontal (hpotmeter) or vertical (vpotmeter) potmeter of + width * height size at position + X,Y. 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.). hpotmeter can have a button that can be + dragged horizontally. The parameters are: + + + button - the image to be used for the button (must have three parts below each other, like in case of button) - - bwidth, bheight - size + + + bwidth, bheight - size of the button - - phases - the image to be used for the - different phases of the hpotmeter. A special value of NULL - can be used if you want no such image. The image must be divided into - numphases parts vertically like this: - - - + + + phases - the image to be used for the + different phases of the hpotmeter. A special value of NULL + can be used if you want no such image. The image must be divided into + numphases parts vertically like this: + +------------+ | phase #1 | +------------+ @@ -397,27 +447,30 @@ dragged horizontally. The parameters are: ... +------------+ | phase #n | -+------------+ - - - - numphases - number of phases stored in the ++------------+ + + + numphases - number of phases stored in the phases image - - default - default value for hpotmeter + + + default - default value for hpotmeter (in the range 0 to 100) - - X, Y - position for the hpotmeter - - width, height - width and height + + + X, Y - position for the hpotmeter + + + width, height - width and height of the hpotmeter - - message - the message to be generated when the + + + message - the message to be generated when the value of hpotmeter is changed - - - - + + + @@ -425,12 +478,12 @@ dragged horizontally. The parameters are: potmeter = phases, numphases, default, X, Y, width, height, message -A hpotmeter 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 hpotmeter. -phases can be NULL, but it is quite useless, -since you cannot see where the potmeter is set. - + A hpotmeter 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 hpotmeter. + phases can be NULL, but it is quite + useless, since you cannot see where the potmeter is set. + @@ -438,11 +491,12 @@ since you cannot see where the potmeter is set. font = fontfile, fontid -Defines a font. fontfile is the name of a font description file -with a .fnt extension (do not specify the extension here). -fontid is used to refer to the font (see dlabel -and slabel). Up to 25 fonts can be defined. - + Defines a font. fontfile is the name of a font description + file with a .fnt extension (do not specify the extension + here). fontid is used to refer to the font + (see dlabel + and slabel). Up to 25 fonts can be defined. + @@ -450,12 +504,13 @@ and slabel). Up to 25 fonts can be defined. slabel = X, Y, fontid, "text" -Place a static label at the position X,Y. text -is displayed using the font identified by fontid. The text is -just a raw string ($x 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 fontid. - + Place a static label at the position X,Y. + text is displayed using the font identified by + fontid. The text is just a raw string + ($x 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 fontid. + @@ -463,154 +518,159 @@ label is displayed using the font identified by fontid. dlabel = X, Y, length, align, fontid, "text" - -Place a dynamic label at the position X,Y. The label is called -dynamic because its text is refreshed periodically. The maximum length of the -label is given by length (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 -align parameter: 0 is for right, -1 is for center, 2 is for left. - - -The text to be displayed is given by text: 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 fontid. You -can use the following variables in the text: - - - - - - VariableMeaning - - - -$1 -play time in hh:mm:ss format - - -$2 -play time in mmmm:ss format - - -$3 -play time in hh format (hours) - - -$4 -play time in mm format (minutes) - - -$5 -play time in ss format (seconds) - - -$6 -movie length in hh:mm:ss format - - -$7 -movie length in mmmm:ss format - - -$8 -play time in h:mm:ss format - - -$v -volume in xxx.xx% format - - -$V -volume in xxx.xx format - - -$b -balance in xxx.xx% format - - -$B -balance in xxx.xx format - - -$$ -the $ character - - -$a -a character according to the audio type (none: n, -mono: m, stereo: t) - - -$t -track number (in playlist) - - -$o -filename - - -$f -filename in lower case - - -$F -filename in upper case - - -$T -a character according to the stream type (file: f, -Video CD: v, DVD: d, URL: u) - - -$p -the p character (if a movie is playing and the font has -the p character) - - -$s -the s character (if the movie is stopped and the font has -the s character) - - -$e -the e character (if playback is paused and the font has -the e character) - - -$x -movie width - - -$y -movie height - - -$C -name of the codec used - - - - - - - + + Place a dynamic label at the position X,Y. The label is + called dynamic because its text is refreshed periodically. The maximum length + of the label is given by length (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 + align parameter: 0 is for right, + 1 is for center, 2 is for left. + + + The text to be displayed is given by text: 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 + fontid. You can use the following variables in the text: + + + + + + VariableMeaning + + + + $1 + play time in hh:mm:ss format + + + $2 + play time in mmmm:ss format + + + $3 + play time in hh format (hours) + + + $4 + play time in mm format (minutes) + + + $5 + play time in ss format (seconds) + + + $6 + movie length in hh:mm:ss format + + + $7 + movie length in mmmm:ss format + + + $8 + play time in h:mm:ss format + + + $v + volume in xxx.xx% format + + + $V + volume in xxx.xx format + + + $b + balance in xxx.xx% format + + + $B + balance in xxx.xx format + + + $$ + the $ character + + + $a + a character according to the audio type (none: n, + mono: m, stereo: t) + + + $t + track number (in playlist) + + + $o + filename + + + $f + filename in lower case + + + $F + filename in upper case + + + $T + + a character according to the stream type (file: f, + Video CD: v, DVD: d, + URL: u) + + + + $p + the p character (if a movie is playing and the font + has the p character) + + + $s + the s character (if the movie is stopped and the + font has the s character) + + + $e + the e character (if playback is paused and the font + has the e character) + + + $x + movie width + + + $y + movie height + + + $C + name of the codec used + + + + + + + The $a, $T, $p, $s and $e + variables all return characters that should be displayed as special symbols + (for example, e 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 + symbols for more information. + + - - -The $a, $T, $p, $s and $e -variables all return characters that should be displayed as special symbols (for -example, e 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 symbols -for more information. - + + Subwindow + The following entries can be used in the 'window = sub' . . . 'end' block. @@ -622,14 +682,15 @@ The following entries can be used in the base = image, X, Y, width, height -The image to be displayed in the window. The window will appear at the given -X,Y position on the screen (0,0 is the -top left corner). You can specify -1 for center and -2 -for right (X) and bottom (Y). The window -will be as large as the image. width and height -denote the size of the window; they are optional (if they are missing, the -window is the same size as the image). - + The image to be displayed in the window. The window will appear at the given + X,Y position on the screen (0,0 is the + top left corner). You can specify -1 for center and + -2 for right (X) and bottom + (Y). The window will be as large as the image. + width and height + denote the size of the window; they are optional (if they are missing, the + window is the same size as the image). + @@ -637,17 +698,20 @@ window is the same size as the image). background = R, G, B -Lets you set the background color. It is useful if the image is smaller than -the window. R, G and B -specifies the red, green and blue component of the color (each of them is a -decimal number from 0 to 255). - + Lets you set the background color. It is useful if the image is smaller than + the window. R, G and + B specifies the red, green and blue component of the color + (each of them is a decimal number from 0 to 255). + + + Skin menu + As mentioned earlier, the menu is displayed using two images. Normal menu entries are taken from the image specified by the base item, @@ -667,8 +731,8 @@ The following entries can be used in the base = image -The image for normal menu entries. - + The image for normal menu entries. + @@ -676,8 +740,8 @@ The image for normal menu entries. selected = image -The image showing the menu with all entries selected. - + The image showing the menu with all entries selected. + @@ -685,22 +749,26 @@ The image showing the menu with all entries selected. menu = X, Y, width, height, message -Defines the X,Y position and the size of a menu entry in -the image. message is the message to be generated when the -mouse button is released over the entry. - + Defines the X,Y position and the size of a menu entry in + the image. message is the message to be generated when the + mouse button is released over the entry. + + + + + Fonts 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. @@ -732,14 +800,18 @@ image = font.png + + Symbols + Some characters have special meanings when returned by some of the variables used in dlabel. These characters are meant to be shown as symbols so that things like a nice DVD logo can be displayed instead of the character 'd' for a DVD stream. + 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). CharacterSymbol -pplay -sstop -epause -nno sound -mmono sound -tstereo sound -fstream is a file -vstream is a Video CD -dstream is a DVD -ustream is a URL + pplay + sstop + epause + nno sound + mmono sound + tstereo sound + fstream is a file + vstream is a Video CD + dstream is a DVD + ustream is a URL + + + + GUI messages + These are the messages that can be generated by buttons, potmeters and menu entries. @@ -779,49 +856,50 @@ menu entries. evNext -Jump to next track in the playlist. - + Jump to next track in the playlist. + evPause -Forms a switch together with evPlaySwitchToPause. 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 evPlaySwitchToPause button is -displayed (to indicate that the button can be pressed to continue playing). - + Forms a switch together with evPlaySwitchToPause. 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 evPlaySwitchToPause + button is displayed (to indicate that the button can be pressed to continue + playing). + evPlay -Start playing. - + Start playing. + evPlaySwitchToPause -The opposite of evPauseSwitchToPlay. This message starts -playing and the image for the evPauseSwitchToPlay button -is displayed (to indicate that the button can be pressed to pause playing). - + The opposite of evPauseSwitchToPlay. This message starts + playing and the image for the evPauseSwitchToPlay button + is displayed (to indicate that the button can be pressed to pause playing). + evPrev -Jump to previous track in the playlist. - + Jump to previous track in the playlist. + evStop -Stop playing. - + Stop playing. + @@ -830,51 +908,51 @@ Stop playing. evBackward10sec -Seek backward 10 seconds. - + Seek backward 10 seconds. + evBackward1min -Seek backward 1 minute. - + Seek backward 1 minute. + evBackward10min -Seek backward 10 minutes. - + Seek backward 10 minutes. + evForward10sec -Seek forward 10 seconds. - + Seek forward 10 seconds. + evForward1min -Seek forward 1 minute. - + Seek forward 1 minute. + evForward10min -Seek forward 10 minutes. - + Seek forward 10 minutes. + evSetMoviePosition -Seek to position (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - + Seek to position (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + @@ -883,26 +961,26 @@ relative value (0-100%) of the potmeter is used). evHalfSize -Set the movie window to half size. - + Set the movie window to half size. + evDoubleSize -Set the movie window to double size. - + Set the movie window to double size. + evFullScreen -Switch fullscreen mode on/off. - + Switch fullscreen mode on/off. + evNormalSize -Set the movie window to its normal size. - + Set the movie window to its normal size. + @@ -911,66 +989,66 @@ Set the movie window to its normal size. evDecAudioBufDelay -Decrease audio buffer delay. - + Decrease audio buffer delay. + evDecBalance -Decrease balance. - + Decrease balance. + evDecVolume -Decrease volume. - + Decrease volume. + evIncAudioBufDelay -Increase audio buffer delay. - + Increase audio buffer delay. + evIncBalance -Increase balance. - + Increase balance. + evIncVolume -Increase volume. - + Increase volume. + evMute -Mute/unmute the sound. - + Mute/unmute the sound. + evSetBalance -Set balance (can be used by a potmeter; the -relative value (0-100%) of the potmeter is used). - + Set balance (can be used by a potmeter; the + relative value (0-100%) of the potmeter is used). + evSetVolume -Set volume (can be used by a potmeter; the relative -value (0-100%) of the potmeter is used). - + Set volume (can be used by a potmeter; the relative + value (0-100%) of the potmeter is used). + @@ -979,126 +1057,129 @@ value (0-100%) of the potmeter is used). evAbout -Open the about window. - + Open the about window. + evDropSubtitle -Disables the currently used subtitle. - + Disables the currently used subtitle. + evEqualizer -Turn the equalizer on/off. - + Turn the equalizer on/off. + evExit -Quit the program. - + Quit the program. + evIconify -Iconify the window. - + Iconify the window. + evLoad -Load a file (by opening a file browser window, where you can choose a file). - + Load a file (by opening a file browser window, where you can choose a file). + evLoadPlay -Does the same as evLoad, but it automatically starts playing after -the file is loaded. - + Does the same as evLoad, but it automatically starts + playing after the file is loaded. + evLoadSubtitle -Loads a subtitle file (with the fileselector) - + Loads a subtitle file (with the fileselector) + evLoadAudioFile -Loads an audio file (with the fileselector) - + Loads an audio file (with the fileselector) + evNone -Empty message, it has no effect (except maybe in Subversion versions :-)). - + Empty message, it has no effect (except maybe in Subversion versions :-)). + evPlaylist -Open/close the playlist window. - + Open/close the playlist window. + evPlayDVD -Tries to open the disc in the given DVD-ROM drive. - + Tries to open the disc in the given DVD-ROM drive. + evPlayVCD -Tries to open the disc in the given CD-ROM drive. - + Tries to open the disc in the given CD-ROM drive. + evPreferences -Open the preferences window. - + Open the preferences window. + evSetAspect -Sets displayed image aspect. - + Sets displayed image aspect. + evSetURL -Displays the URL dialog window. - + Displays the URL dialog window. + evSkinBrowser -Open the skin browser window. - + Open the skin browser window. + - + + + + Creating quality skins @@ -1122,31 +1203,40 @@ it satisfies all the criteria listed below since version 1.5. - Each skin should come with a + + Each skin should come with a README 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. + good place. + - There should be a file VERSION + + There should be a file VERSION with nothing more than the version number of the skin on a single - line (e.g. 1.0). + line (e.g. 1.0). + - Horizontal and vertical controls (sliders like volume + + 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. + both ends of the slider, but not past it. + - Skin elements should have the right sizes declared + + 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. + trigger it. + - The skin file should be + + The skin file should be prettyprinted and not contain tabs. Prettyprinted means that the - numbers should line up neatly in columns. + numbers should line up neatly in columns. + - -- cgit v1.2.3