path: root/noatun/modules/kaiman/SKIN-SPECS

        ############ GQmpeg skin specifications file. ############

       (A quick reference of what is required in the image files
        for each widget type is located at the end of this document )

Skins are simply a directory which contain image files and
a skindata file (named skindata).

All skin features are configured in the skindata file.

Note: when using an alternate skin, it's specs go into a file named
skindata_alt, it uses the same format as the skindata file. Pressing
the Alt_Skin_Button button switches between the two skins.
(each skin must contain an Alt_Skin_Button if you want the alternate
skin feature to work)

Any line can be made into a comment by prefacing it with a '#' symbol.

All image files can be any size, GQmpeg will calculate the drawing data
for you. Skins can have any size buttons, display items, digits,
fonts, etc. The files can be of any type supported by gdk-pixbuf (xpm, png,
jpeg, gif, etc.) The recommended file format is png.

Prelights are optional on all items that support them. A prelight is an
alternate image that is displayed when the mouse is over a pressable
item (button, slider, dial). For example, the default skin includes prelights
for all buttons, notice the buttons 'brighten' when the mouse moves over
them.

Every image within a file must have the same width and height, for example
if the play button was 30 by 20, the resulting image file would be
180 by 20. (6 button states total, including status lights and prelights)

 Addendum: If the above button was specified with the status light and
           prelight options as false, the resulting image file would be
           60 by 20. (2 button states total, 1 for normal, 1 for pressed)

Note that images for buttons and numbers contain the items horizontally,
the images for items contain the items vertically, the image for a font
contains 3 rows of 32 items, and the slider contains the background and
handle horizontally or vertically (depending if a slider is horizontal
or verticle, respectivley).

Only the background image is required, all other elements are optional
(although it would be nice to always have a play button :)
If you do not want an item displayed, comment out the line with
a '#' symbol.

IMPORTANT:
Slots enclosed in "[]" are optional, but are so only to retain backward
compatibility of skins. Please specify all options for each type as in the
future the options enclosed in "[]" may no longer be "optional". Please
separate each option with a single space, and do not add extra characters
at the end of the line, as the extra info may be mistaken for expanded
options in the event that options are added to the skin spec in the future.

PROPER TRANSPARENCY:
The main background image uses a threshold of 1 (out of 256 levels) for the
window shape, the rest is used for partially overwiting the background when
the Transparency option is true.

Portions of items, buttons, sliders, numbers, and text that never change and
are the same as the background image should be set transparent so that the
'force transparent' option works properly.

        ############# skindata file format #################

Note: For an example skindata file see the file skindata-template.

x and y are always the position in the window (use the -skinhelp command line
option to have GQmpeg print out the mouse coordinates as the mouse moves)

And finally, to what is available:

==========================
 Main options
==========================

Background: filename

 filename
  The background image file, the window will be the same size as this image.
  Add transparency to this image for shaped skins, the cutoff threshold for
  transparency is 1 on images with muli-level alpha (like in png).

Transparency: flag

 flag
  True or False, this specifies if the background image (above) has a multiple
  level alpha channel (as in png files) to apply when overwriting the root
  window's background.

Mask: filename

(this is DEPRECATED!, for transparent skins just add transparency to the
 Background image, Mask remains merely for backwards compatibility)
 filename
  The mask image file, only needed for skins which are shaped windows (not
  rectangular). Contains a transparency mask for the main window.

==========================
 Text display
==========================

Title/Album/Artist/Genre: filename length [extended] x y

 filename
   Should contain a fixed font. With 3 or 6 lines of 32 characters each,
   these are the characters, they are listed in three rows so you can copy
   and past them into you graphics program. (first character in the top line
   is a space)

            !"#$%&'()*+,-./0123456789:;<=>?
           @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
           `abcdefghijklmnopqrstuvwxyz{|}~ 

   When extended is TRUE these are the 3 addition lines of international chars

           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
           XXXXXXX FIXME! TO DO! XXXXXXXXXX
           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

 length
   Maximum number of characters to display in window.

 extended
   (optional, absence defaults to FALSE)
   When TRUE, the image contains 3 additional lines for internation
   characters. The result is 6 lines of 32 characters each.

==========================
 Buttons                   (that optionally include an 'active' mode)
==========================

Play/Pause/Stop/Shuffle/Repeat/
            Time_Remaining/Time_Total_Button: filename prelight status_light x y [clip_filename]

 filename
  Image file. Contains the buttons horizontally in this order:
    normal, normal pressed, normal active, normal active pressed, prelit, prelit active
  (the actual number of images may vary, see next two options)

 prelight
  TRUE or FALSE, specifies whether or not prelight buttons are available, If
  FALSE, do not include the last two prelight buttons in the image file.

 status_light
  TRUE or FALSE, specifies whether or not button lights are available. If FALSE,
  do not include the 'lit up', 'lit down', and 'prelight lit up' buttons in the
  image file.

 clip_filename (optional)
  When specified, defines an image with transparency to be used as the button's
  draw clip mask. The clip mask is placed at location x, y The transparency is used to
  indicate the portions of the button that should be visible (drawn) and respond to
  mouse clicks. If the image contains a multiple level alpha channel, the mask is reduced
  such that levels above 50% are visible and those below 50% are not visible.

==========================
 Buttons                   (standard)
==========================

Next/Prev/FF/RW/Playlist/Config/Iconify/Mixer/Exit/Alt_Skin/Volume_Up/Volume_Down/
            Balance_Left/Balance_Right_Button: filename prelight x y [clip_filename]
Preset_1_/.../Preset_10_Button: filename prelight x y [clip_filename]

 filename
  Image file. Contains the buttons horizontally in this order:
    normal, normal pressed, prelit
  (the actual number of images may vary, see next option)

 prelight
  TRUE or FALSE, specifies whether or not prelight buttons are available. If
  FALSE, do not include the last prelight button in the image file.

 clip_filename (optional)
  When specified, defines an image with transparency to be used as the button's
  draw clip mask. The clip mask is placed at location x, y The transparency is used to
  indicate the portions of the button that should be visible (drawn) and respond to
  mouse clicks. If the image contains a multiple level alpha channel, the mask is reduced
  such that levels above 50% are visible and those below 50% are not visible.


==========================
 Items                     (with fixed number sections)
==========================

Stereo/Shuffle/Repeat/Mpegversion/Mpeglayer/Mpegmode/Status/
            Minus/Total_Item: filename x y

 filename
  Image file. Contains the items vertically in the order below:

        Stereo_Item:  blank, mono , stereo
        Shuffle_Item:  off, on
        Repeat_Item:  off, on
        Mpegversion_Item:  blank, 1, 2
        Mpeglayer_Item:  blank, 1, 2, 3
        Mpegmode_Item:  blank, stereo, joint-stereo, dual-channel, single-channel
	Status_Item: stop, pause, play
	Minus_Item: time counts up, time counts down
	Total_Item: time refers to current song only, to total playlist, to live

==========================
 Items                     (animation oriented)
==========================

Load_Item: filename sections x y

 filename
  Image file. Contains animations for the following items:

        Load_Item: Animation for loading playlist in background.

 sections
  The total number of sections in the image file. The first section is always
  blank (animation is off), the subsequent images are cycled through to create
  the animation. This number is a total count, so it will be 1 (first is always
  blank) plus the number of animation frames.

==========================
 Items                     (value oriented)
==========================

Position/Volume/Balance_Item: filename sections x y

 filename
  Image file. Contains images vertically in the order representing the lowest to
  highest values.

 sections
  The number of images within the file, recommended number of images is 16 to 32.
  The most possible usable images is 101 for volume and blance (from volume=0%
  to volume = 100%).

 Note:
  These items must be listed before their respective sliders:
  (see Position/Volume/Balance_Slider).

==========================
 Digit placeholder         (for convenience, less memory usage with many similar numbers)
==========================

Digit_Large/Digit_Small_Default: filename

 filename
  Image file. Contains digits horizontally from 0 to 9, and a blank space.

 These two digits are a convenience function, if you want to use a digit more than
 once it is quicker to load it into on of these two Q_SLOTS. Then when using the digit
 in the number item type below, use the words 'Large' or 'Small' in place of the
 filename.

==========================
 Numbers
==========================

Hour/Minute/Second/Song/Total/In_Rate/In_Hz/Out_Bits/Out_Hz/
            Song_Minute/Song_Second/Frame/Frame_Total/CPU/
            Hour_Total/Minute_Total/Second_Total_Number: filename [length center] x y

 filename
  Image file for the number's digit, or the word 'Large' or 'Small' (see above).
  If a filename is specified, the image should contain the digits horizontally
  from 0 to 9, and a blank space.

 length (optional)
  The number of digits to display, if not present the default is assumed.

 center (optional, but if specified length is required too)
  TRUE or FALSE, specify to center the number.

==========================
 Sliders
==========================

Position/Volume/Balance_Slider: filename prelight [verticle reversed] length x y

 filename
  Image file. Contains images horizontally in this order:
    slider background, handle normal, handle pressed, handle prelit
  (handles must have the same dimensions)

 prelight
  TRUE or FALSE, specifies whether or not a prelight handle is available, if FALSE,
  do not include a 'handle prelit' in the image file.

 verticle
  TRUE or FALSE. If false the slider is horizontal, if true, verticle.

 reversed
  TRUE or FALSE. If true, the slider works opposite than normal. For example
  when false the slider moves from left to right, when true the slider moves
  from right to left. On a verticle slider and reversed is false, the slider
  moves from top to bottom.

 length
  The width of the slider's background, this is the complete width the slider will
  be in the window, and must match the length of the 'slider background' in the
  image file.

==========================
 Dials                     (AKA knobs)
==========================

Position/Volume/Balance_Dial: filename has_press_image has_prelight_image reversed
                              angle_start angle_end handle_offset_x handle_offset_y center_x center_y
                              x y w h [clip_filename]

 filename
  Image file. Contains images for the dial's handle vertically in this order:
    normal
    pressed (being dragged with mouse, optional)
    prelit (mouse over highlight, optional)

 has_press_image
  TRUE or FALSE, specifies whether or not handle has a pressed image (above)

 has_prelight_image
  TRUE or FALSE, specifies whether or not handle has a pressed image (above)

 reversed
  TRUE of FALSE, normally a dial works clockwise with angle_start being the
  lowest (zero) value and angle_end being the highest value. When TRUE the dial
  works counter-clockwise with angle_end being the lowest (zero) value to
  angle_start being the highest position.

 angle_start
 angle_end
  The start and end angles define the end points of the dial's rotation in integer
  degrees, the degrees count from 0 located right of center axis increasing clockwise
  to a value of 359. (360 is equivelent to 0, but the only accepted numbers are 0 - 359.
  This (admittedly poor) figure might help:


                     270  ____ center axis
                     _|_ /
                    /   /
                   /   / \
             180 -|   +   |- 0 (360)
                   \     /
                    \_ _/
                      |
                      90

 handle_offset_x
 handle_offset_y
  The x and y coordinates into the handle image that represents the handle center
  of rotation (pivot point), this does not have to actually be within the image size.

 center_x
 center_y
  The x and y coordinates on the skin image for the handle center of rotation.

 x, y, width, height:
  Marks the clipping region to draw the dial, basically the handle is not drawn
  outside this region. (width and height will be ignored if a clip mask image
  is specified (see next option).

 clip_filename (optional)
  When specified, defines an image with transparency to be used as the dial's
  draw clip mask. The clip mask is placed at x, y (above) and the image's dimensions
  are used in place of width, height (above). The transparency is used to indicate the
  portions of the dial that should be visible (drawn) and respond to mouse clicks.
  If the image contains a multiple level alpha channel, the mask is reduced such that
  levels above 50% are visible and those below 50% are not visible.

==============================================================================
              ************ Quick reference tables **************
==============================================================================

Note: All example values below set (*)coordinates x=1 and y=1, and filename to fn.png.
      (*) Except Dials.

--------------------------
 Buttons (all button images contained horizontally)
--------------------------

Play/Pause/Stop/Shuffle/Repeat_Button: filename prelight status_light x y
Time_Remaining/Time_Total_Button: filename prelight status_light x y

Option line:           | # images | Normal | Pressed |  Lit   |   Lit   | Prelit | Prelit     |
                       |  total   |        |         | Normal | Pressed | Normal | Lit Normal |
-----------------------+----------+--------+---------+--------+---------+--------+------------+
 fn.png TRUE TRUE 1 1  |     6    |   X    |   X     |   X    |    X    |   X    |      X     |
 fn.png TRUE FALSE 1 1 |     3    |   X    |   X     |        |         |   X    |            |
 fn.png FALSE TRUE 1 1 |     4    |   X    |   X     |   X    |    X    |        |            |
 fn.png FALSE FALSE 1 1|     2    |   X    |   X     |        |         |        |            |

Next/Prev/FF/RW/Playlist/Config/Iconify/Mixer/Exit/Alt_Skin_Button: filename prelight x y
Volume_Up/Volume_Down/Balance_Left/Balance_Right_Button: filename prelight x y

Option line:           | # images | Normal | Pressed | Prelit |
                       |  total   |        |         | Normal |
-----------------------+----------+--------+---------+--------+
 fn.png TRUE 1 1       |     3    |   X    |   X     |   X    |
 fn.png FALSE 1 1      |     2    |   X    |   X     |        |


--------------------------
  Items (all item images contained vertically)
--------------------------

Stereo/Shuffle/Repeat/Mpegversion/Mpeglayer/Mpegmode/Status/Minus/Total_Item: filename x y

Item:                  | # images | Image 1 | Image 2 | Image 3 | Image 4 | Image 5 |
                       |  total   |         |         |         |         |         |
-----------------------+----------+---------+---------+---------+---------+---------+
 Stereo_Item           |    3     |  blank  |  mono   | stereo  |         |         |
 Shuffle_Item          |    2     |   off   |   on    |         |         |         |
 Repeat_Item           |    2     |   off   |   on    |         |         |         |
 Mpegversion_Item      |    3     |  blank  |  ver 1  |  ver 2  |         |         |
 Mpeglayer_Item        |    4     |  blank  | layer 1 | layer 2 | layer 3 |         |
 Mpegmode_Item         |    5     |  blank  | stereo  | j-stereo| dual-ch |single-ch|
 Status_Item           |    3     |  stop   | pause   |  play   |         |         |
 Minus_Item            |    2     |  normal |remaining|         |         |         |
 Total_Item            |    2     |  normal | total   |  live   |         |         |


Load_Item: filename section_count x y

(These are special Animation items, any number of sections can be included)

Option line:       | # images | Image 1 | Image 2 | ....... | Last Image |
                   |  total   |         |         |         |            |
-------------------+----------+---------+---------+---------+------------+
 fn.png 8 1 1      |    8     |  blank  | Frame 1 | F2...F6 |  Frame 7   |
 fn.png 4 1 1      |    4     |  blank  | Frame 1 | Frame 2 |  Frame 3   |


Position/Volume/Balance_Item: filename sections x y

Option Line: (*)            | # images | 1st Image | middle Image |  Last Image   |
                            |  total   |           |              |               |
----------------------------+----------+-----------+--------------+---------------+
 Volume_Item fn.png 17 1 1  |    17    | 1 - 0% vol| 9 - 50 % vol | 17 - 100% vol |
 Volume_Item fn.png 31 1 1  |    31    | 1 - 0% vol| 16 - 50 % vol| 31 - 100% vol |
 Balance_Item fn.png 17 1 1 |    17    | 1 - Left  | 9 - middle   | 17 - Right    |
 Balance_Item fn.png 13 1 1 |    13    | 1 - Left  | 6 - middle   | 13 - Right    |

 (*)note: The values (17, 31, 17, 13) above are only examples, any number of images
        can be specified.


--------------------------
 Sliders (all slider images contained horizontally)
--------------------------

Position/Volume/Balance_Slider: filename prelight [verticle reversed] length x y

Option line:                       | # images | Background  | Normal | Pressed | Prelit |
                                   |  total   |    width    |        |         | Normal |
-----------------------------------+----------+-------------+--------+---------+--------+
 fn.png TRUE FALSE FALSE 32 1 1    |     4    | 32 pixels   |   X    |   X     |   X    |
 fn.png FALSE FALSE FALSE 250 1 1  |     3    | 250 pixels  |   X    |   X     |        |


--------------------------
 Dials (can be confusing, see detailed description, above)
--------------------------

Position/Volume/Balance_Dial: filename has_press_image has_prelight_image reversed
                              angle_start angle_end handle_offset_x handle_offset_y center_x center_y
                              x y w h [clip_filename]

Option line:                                              | # images | Normal | Pressed | Prelit |
                                                          |  total   |        |         | Normal |
----------------------------------------------------------+----------+--------+---------+--------+
 fn.png TRUE TRUE TRUE 0 180 16 16 200 100 140 40 80 80   |     3    |   X    |   X     |   X    |
 fn.png FALSE TRUE TRUE 0 180 16 16 200 100 140 40 80 80  |     2    |   X    |         |   X    |
 fn.png FALSE FALSE TRUE 0 180 16 16 200 100 140 40 80 80 |     1    |   X    |         |        |

--------------------------
 Numbers (all number images contained horizontally)
--------------------------

*_Number: filename [length centered] x y

Option line:         | # images | Images in order (left to right)                |
                     |  total   |                                                |
---------------------+----------+------------------------------------------------+
 fn.png 1 1          |    11    | 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, " "(blank space) |
 fn.png 3 FALSE 1 1  |    11    | 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, " "(blank space) |


--------------------------
 Fonts  (all font images contained in 3 or 6 rows of 32 columns)
--------------------------

Title/Album/Artist/Genre: filename length [extended] x y

Option line:            | # images | Images in order    |
                        |  total   |                    |
------------------------+----------+--------------------+
 fn.png 16 1 1          |    96    | see grid 1 (below) |
 fn.png 16 FALSE 1 1    |    96    | see grid 1 (below) |
 fn.png 16 TRUE 1 1     |    192   | see grid 2 (below) |

                  +------------------------------------+
character grid 1: |                                    |
(standard)        |   !"#$%&'()*+,-./0123456789:;<=>?  |
                  |  @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_  |
                  |  `abcdefghijklmnopqrstuvwxyz{|}~   |
                  |                                    |
                  +------------------------------------+

                  +------------------------------------+
character grid 2: |                                    |
(international    |   !"#$%&'()*+,-./0123456789:;<=>?  |
 extended)        |  @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_  |
                  |  `abcdefghijklmnopqrstuvwxyz{|}~   |
                  |  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  |
                  |  XXXXXXX FIXME! TO DO! XXXXXXXXXX  |
                  |  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  |
                  |                                    |
                  +------------------------------------+

#################################