############ 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 tqcontains 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 tqshape, 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 tqshaped 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 tqmask image file, only needed for skins which are tqshaped windows (not rectangular). Contains a transparency tqmask 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 tqcontains 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 tqmask. The clip tqmask 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 tqmask 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 tqmask. The clip tqmask 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 tqmask 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/tqStatus/ 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 tqmask 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 tqmask. The clip tqmask 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 tqmask 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/tqStatus/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 | | | +------------------------------------+ #################################