--- skin-en.html Thu Sep 27 14:56:01 2001 +++ skin-en-diego.html Fri May 24 04:38:11 2002 @@ -1,14 +1,20 @@ + - + MPlayer skin format - +

MPlayer skin format

@@ -18,90 +24,102 @@
-Last modified: Sep 10, 2001 +Last modified: 2002/05/24

1 Introduction

-The purpose of this document is to describe the MPlayer skin format. -The information contained here might be wrong, for a) it is not me -who wrote the GUI, b) the GUI is not finished, c) I might -be wrong. So do not be surprised if something does not work as described here. +The purpose of this document is to describe the MPlayer skin format. +The information contained here might be wrong, for + +
    +
  1. It is not me who wrote the GUI
    2. +
  2. The GUI is not finished
    3. +
  3. I might be wrong.
    4. +
+ +So do not be surprised if something does not work as described here.

Thanks to Zoltán Ponekker for his help. +

András Mohari <mayday@freemail.hu> +

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

2.1 Directories

The directories searched for skins are (in order): 
-    /usr/local/share/mplayer/Skin/
+    $(DATADIR)/Skin/
+    $(PREFIX)/share/mplayer/Skin/
     ~/.mplayer/Skin/

-Note that the first path may vary according to the way MPlayer was configured -(see the --datadir argument of the configure -script). +Note that the first path may vary according to the way MPlayer was +configured (see the --prefix and --datadir arguments +of the configure script). +

-

Every skin is installed into its own directory under one of the directories listed above, for example: 

-    /usr/local/share/mplayer/Skin/default/
+    $(PREFIX)/share/mplayer/Skin/default/

2.2 Image formats

-Images must be truecolor (24 or 32 bpp) and can be in -BMP, PNG and TGA format (note that TGA images must be uncompressed). -The preferred format is PNG as it compresses very well. +Images must be truecolor (24 or 32 bpp) and can be in BMP, PNG or uncompressed +TGA format. The preferred format is PNG as it compresses very well.

In the main window (see below) you can use images with `transparency': -regions filled with the color #FF00FF (magenta) -are fully transparent when viewed by MPlayer. This means that you can even +Regions filled with the color #FF00FF (magenta) +are fully transparent when viewed by MPlayer. This means that you can even have shaped windows if your X server has the XShape extension. +

-

2.3 Parts of a skin

+

2.3 Skin components

Skins are quite free-format (unlike the fixed-format skins of Winamp/XMMS, for example), so it is up to you to create something great. @@ -111,41 +129,47 @@ main window, the subwindow and the skin menu (which can be activated by a right click). +

-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. +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 genereated when they are clicked. +you must define the messages to be generated when they are clicked. +

2.4 Files

-You need the following files to build a skin. +You need the following files to build a skin: With the exception of the skin configuration file, you can name the other files whatever you want (but note that font description files must have -.fnt extension). +a .fnt extension). -

3 The skin file

+

3 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 ';'). +

The file is made up of sections. Each section describes the skin for an application and has the following form: +

+ 
 section = section name
 .
@@ -220,17 +249,24 @@
 

 Currently there is only one application, so you need only one section:
 its name is movieplayer.
+

 
 

-Within this section each window is described by a block in the following form:
+Within this section each window is described by a block of the following form:
+

+
 
 window = window name
 .
 .
 .
 end
-

+
+ +

where window name can be one of these strings: +

+

-(The sub and menu block is optional---you do not need to create a menu or -to decorate the subwindow.) +(The sub and menu blocks are optional - you do not need to create a menu or +decorate the subwindow.) +

Within a window block, you can define each item for the window by a line in this form: +

-
-
-item = parameter
-
-
- -

-where item is a string that identifies the type of the GUI item, -parameter is a numeric or textual value (or a list of values +

+
+item = parameter +
+
+Where item is a string that identifies the type of the GUI item, +parameter is a numeric or textual value (or a list of values separated by commas). -

+
+

Putting the above together, the whole file looks something like this: +

-

 section = movieplayer
   window = main
@@ -275,31 +312,49 @@
   ; ... items for skin menu ...
   end
 end
-
+

-Finally some words about specifying images for the various items. -
-The name of an image file must be given without leading directories--- -images are searched in the directory of the skins. You may (but you need not) -specify the file's extension. If the file doesn't exist, MPlayer tries to -load the file <filename>.<ext>, where tga, -TGA, bmp, BMP, png and PNG is tried -for <ext> (in this order). The first matching file will be used. +The name of an image file must be given without leading directories - images are +searched for in the Skin directory. You may (but you need not) +specify the extension of the file. If the file does not exist, MPlayer +tries to load the file <filename>.<ext>, where +tga, TGA, bmp, BMP, +png and PNG is tried for <ext> +(in this order). The first matching file will be used. +

+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)
+  |          |          |
+  |          |          |
+(0,-1)----(-1,-1)----(-2,-1)
+  |          |          |
+  |          |          |
+(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: +main.png that you use for the main window: 
     base = main, -1, -1
-MPlayer tries to load main, main.tga, main.TGA, -main.bmp etc, so main.png will be found. +MPlayer tries to load main, main.tga, +main.TGA, main.bmp etc, so that main.png +will be found.
If (by accident) you wrote
@@ -307,44 +362,43 @@ base = main.bmp, -1, -1
-then main.bmp, main.bmp.tga, main.bmp.TGA, -main.bmp.bmp would be searched and MPlayer would finally give up -because there is no main.bmp in the directory, but main.png. +then main.bmp, main.bmp.tga, main.bmp.TGA, +main.bmp.bmp would be searched for and MPlayer would finally +give up because there is no main.bmp in the directory, only +main.png.

3.1 Main window

-Below you can see the list of items that can be used in the +Below is the list of entries that can be used in the 'window = main' . . . 'end' block.
-base = image, x, y +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 (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. -

+The window will appear at the given X,Y position on the screen +The window will have the size of the image. +

-Warning: transparent regions in the image (colored #FF00FF) appear +Warning: Transparent regions in the image (colored #FF00FF) appear black on X servers without the XShape extension. +
-
-
-button = image, x, y, width, height, message
+button = image, X, Y, width, height, message
-Place a button of width * height size at the -x,y position. 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   |
 +------------+
@@ -352,57 +406,44 @@
 +------------+
 |  disabled  |
 +------------+
-
+
-
-
-decoration = enable|disable +decoration = enable|disable
Enable or disable window manager decoration of the main window. Default is disable.
-
-
-hpotmeter = butt, bw,bh, phases, numphases, default, x, y, w, h, msg +hpotmeter = button, bwidth, bheight, phases, numphases, default, X, Y, width, height, message
-Place a horizontal potmeter of w * h size at the -x,y position. The image can be divided into +Place a horizontal 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: +while its value changes from the minimum to the maximum.). +hpotmeter can have a button that can be dragged horizontally. + +
The parameters are:
+ -The image used for the different phases must look something like this: -

+
  • 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:
+
     +------------+
 |  phase #1  |
 +------------+
@@ -412,63 +453,78 @@
 +------------+
 |  phase #n  |
 +------------+
-
    • + + +
  • numphases - number of phases stored in the phases +image
    • +
  • default - default value for hpotmeter (in the range 0 to +100)
    • +
  • X, Y - position for the hpotmeter
    • +
  • width, height - width and height of the +hpotmeter
    • +
  • message - the message to be generated when the value of +hpotmeter is changed
    • + + -Note: there will be a vpotmeter item too, but is it not implemented -yet. +Note: There will be a vpotmeter item, too, but it is not +implemented yet.
    -
    -
    -potmeter = phases, numphases, default, x, y, w, h, msg +potmeter = phases, numphases, default, X, Y, width, height, message
    -A potmeter without a button. (I guess it is ment to be turned round, -but it reacts to horizontal dragging only.) +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 its quite useless, since you can not see where -the potmeter is set. +hpotmeter. phases can be +NULL, but it is quite useless, since you cannot see where +the potmeter is set.
    -
    -
    -font = fontfile, fontid +font = fontfile, fontid
    -Defines a font. fontfile is the name of a font description file -with .fnt extension (no need to specify the extension -here). -fontid is used to refer to the font +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.
    -
    -
    +
    +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. +
    +
    -dlabel = x, y, length, align, fontid, "text" +dlabel = X, Y, length, align, fontid, "text"
    -Place a dynamic label at the x,y position. 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, then 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. +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 " 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. +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: -
    - +
    @@ -481,9 +537,9 @@ - + - + @@ -509,7 +565,7 @@ -
    VariableMeaning
    $1 play time in hh:mm:ss format
    $5 play time in ss format (seconds)
    $6movie's length in hh:mm:ss format
    movie length in hh:mm:ss format
    $7movie's length in mmmm:ss format
    movie length in mmmm:ss format
    $8 play time in h:mm:ss format
    $vfilename in upper case
    $T a character according to the stream type (file: f, - video CD: v, DVD: d, URL: u) + Video CD: v, DVD: d, URL: u)
    $p the "p" character (if a movie is playing and the font has the "p" @@ -523,58 +579,46 @@ the "e" character (if playback is paused and the font has the "e" character)
    -

    + + + Note: 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. -

    -
    - -
    -
    -slabel = x, y, fontid, text -
    -
    -Place a static label at the x,y position. -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 (the " cannot be part of the text). -The label is displayed using the font identified by fontid. +

    3.2 Subwindow

    -The following items can be used in the +The following entries can be used in the 'window = sub' . . . 'end' block.
    -base = image, x, y, width, height +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 gives the size of the window; they are -optional (if they are missing, the window is the same size as the image). +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).
    -
    -
    -background = r, g, b +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 +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).
    @@ -583,41 +627,37 @@

    3.3 Skin menu

    As mentioned earlier, the menu is displayed using two images. -Normal menu entries are taken from the image specified by the base +Normal menu entries are taken from the image specified by the base item, while the currently selected entry is taken from the image specified -by the selected item. -You must define the position and size of each menu entry by the menu -item. +by the selected item. You must define the position and size of each +menu entry through the menu item.

    -These are the items that can be used in the 'window = menu' +These are the entries that can be used in the 'window = menu' . . . 'end' block. +

    -base = image +base = image
    The image for normal menu entries. -
    -
    -selected = image +selected = image
    The image showing the menu with all entries selected.
    -
    -
    -menu = x, y, width, height, message +menu = X, Y, width, height, message
    -Defines the x,y position and the size of a menu entry in -the images. message is the message to be generated when +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.
    @@ -631,39 +671,36 @@ their position and size is given in the description file exactly.

    -The font description file (with .fnt extension) can have comment -lines starting with ';'. -The file must have a line in the form -

    -
    -image = image
-
    -
    +The font description file (with .fnt extension) can have comment +lines starting with ';'. The file must have a line in the form +

    -

    -where image is the name of the image file to be used for +

    +
    +image = image +
    +
    +Where image is the name of the image file to be used for the font (you do not have to specify the extension). -The above line is followed by character definition lines of the form: - -
    -
    -"char" = x, y, w, h
-
    -
    +
    -

    -Here x and y specifies the position of the -char character in the image (0,0 is the upper left corner). -w and h is the width and height of the character -(in pixels, of course). +

    +"char" = X, Y, width, height +
    +
    +Here X and Y specify the position of the +char character in the image (0,0 is the upper left +corner). width and height are the dimensions of the +character in pixels. +
    +
    -

    -Here is an example that defines the A, B, C characters using font.png. +This example defines the A, B, C characters using font.png. 
    -; can be "font" instead of "font.png"
+; Can be "font" instead of "font.png".
 image = font.png
 
-; Three characters are enough for demonstration only. :-)
+; Three characters are enough for demonstration purposes :-)
 "A" =  0,0, 7,13
 "B" =  7,0, 7,13
 "C" = 14,0, 7,13
@@ -673,17 +710,16 @@
 
    4.1 Symbols
    
 
 Some characters have special meanings when returned by some of the variables
-used in
-dlabel; these characters are meant to be
-displayed as symbols. (For example, in case of a DVD stream, you could display
-a nice DVD logo instead of the character 'd'.)
+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).
+
    
 
-
    
-
+
    
@@ -700,16 +736,17 @@
 
-    
+    
    
 
    CharacterSymbol
    
 
    p
     play
    f
     stream is a file
    
 
    vstream is a video CD
    stream is a Video CD
    
 
    d
     stream is a DVD
    
 
    u
     stream is a URL
    
 
    
-
    
 
 
    
-Note: currently only 'p', 's', 'e', 'n', 'm' and 't' is used.
+
+Note: Currently only 'p', 's', 'e', 'n', 'm' and 't' are used.
+
 
    
 
 
    Appendix A: GUI messages
    
@@ -719,11 +756,12 @@
 
 
    
 
-Note: some of the messages might not work as expected (or not
-work at all). As you know, the GUI is under development.
+Note: Some of the messages might not work as expected (or not work at
+all). As you know, the GUI is under development.
+
    
 
-
    
-Playback control:
+
+
    Playback control:
    
 
    
 
    
 
    evNext
@@ -733,18 +771,18 @@
 
    Pause playing.
 
 
    evPauseSwitchToPlay
-
    Forms a switch together with evPlaySwitchToPause. They can be
+
    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
+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.
 
 
    evPlaySwitchToPause
-
    The opposite of evPauseSwitchToPlay. This message starts playing
-and the image for the evPauseSwitchToPlay button is displayed (to
+
    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
@@ -755,8 +793,8 @@
 
    
 
    
 
-
    
-Seeking in the stream:
+
+
    Seeking:
    
 
    
 
    
 
    evBackward10sec
@@ -775,8 +813,8 @@
 
    
 
    
   
-
    
-Video control:
+
+
    Video control:
    
 
    
 
    
 
    evDoubleSize
@@ -790,8 +828,8 @@
 
    
 
    
 
-
    
-Audio control:
+
+
    Audio control:
    
 
    
 
    
 
    evDecAudioBufDelay
@@ -825,8 +863,8 @@
 
    
 
    
 
-
    
-Miscellaneous:
+
+
    Miscellaneous:
    
 
    
 
    
 
    evAbout
@@ -836,7 +874,7 @@
 
    Turn the equalizer on/off.
 
 
    evExit
-
    Quit from the program.
+
    Quit the program.
 
 
    evIconify
 
    Iconify the window.
@@ -846,11 +884,11 @@
 file).
 
 
    evLoadPlay
-
    Does the same as evLoad, but it automatically starts
+
    Does the same as evLoad, but it automatically starts
 playing after the file is loaded.
 
 
    evNone
-
    Empty message, it has no effect. (Except maybe in CVS versions. :-))
+
    Empty message, it has no effect (except maybe in CVS versions :-)).
 
 
    evPlayList
 
    Open/close the playlist window.