ES

Extrastrength.com

Michael W. Hartman [my resume]

my email address
privacy policy
 

Jukebox Arcade Skinning


XML Format:

Skins definitions are created via an XML file. The base format of this file is as follows:

<Skin name="SkinName">     ... Skin Definition XML...  </Skin>   

Items within <> are called tags. All tags have a start <tag> and an end </tag>. The <Skin> tag is the required first level element. Items within the tag are called attributes. The "name" attribute specifies the name of the skin. The portion between the start <tag> and end </tag> is called the value. Tag contents can contain additional tags, or children.

For example:
<Skin name="MySkin">      <background>bg.png</background>      <examples>          <normal>normal.bmp</normal>          <down>down.bmp</down>          <hover>hover.bmp</hover>      </examples>  </Skin>

File Formats:

When specifying images the following are supported:
  • .JPG
  • .PNG (supports alpha blending, except for background image)
  • .BMP

Data Types:

When specifying a value or attribute the following types are allowed:
  • (string) - Alpha Numeric string
  • (bool) - A bool can either be specified "true", "false" or "0", "1".
  • (numeric) - a positive or negative number
  • (ARGB) - a color value. The format of a color value is a hexadecimal number either 6 digits or 8 digits long with the following format: RRGGBB or AARRGGBB. AA= Alpha Level, RR = Red Level, GG = Green Level, BB = Blue Level. If 6 digits are used, the AA is assumed to be equal to FF.
  • (alignment) - a string containing the horizontal and/or vertical alignment for text. The string can have multiple alignment specifiers separated by commas (one vertical and one horizontal only). Valid alignment specifiers are
    • "left" - Draw the text on the left side of the element
    • "center" - Center the text in the element
    • "right" - Draw the text on the right side of the element
    • "vcenter" - vertically center the text
    • "top" - shift the text towards the top of the element.
    • "bottom" - shift the text towards the bottom of the element.

File References:

File names are relative to the skin file location. The only exception to this is that when referencing another skin file, it may be located within the current skin's folder, or in it's parent folder.

Filters:

When specifying "artistfilter" buttons the <parameter> element defines the filter string, and the <parameter2> element defines the type of filter. Jukebox Arcade supports both Regular Expression filters and Pattern Matching filters. To specify Regular Expression type put "regex" into the <parameter2> value. use "pattern" in <parameter2> to specify standard Pattern Matching.

Pattern Matching is easier to understand. To specify "all" artists to match, you would use a "*". Specifying a "A*" string will match all artists beginning with "A" followed by any other text.

Regular Expressions are a much more powerful, and more difficult to understand mechanism. I recommend reading the following if you want to use Regular Expressions. http://www.regular-expressions.info/

Skin Root Tags:

These are the root tags supported by the Jukebox Arcade skinning system. They are placed within the <Skin> tag.

  • <background>
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Filename (string) of the background image to use.

  • <transparency>
    • Attributes:
      • enabled (bool).
    • Children:
      • None
    • Value:
      • (ARGB) - Color of the transparent color to use for the background image. The transparent color will be "cutout" of the background, and will allow you to create non-rectangular window shapes.
  • <def_album_img>
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Filename of the image to use for albums that have no "folder.jpg" file.

  • <width>
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Width of the window. For best results this should match the background image.

  • <height>
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Height of the window. For best results this should match the background image.

  • <format>
    • The format value string contains a string with a combination of text and variables to be displayed.
    • Attributes:
      • name (string) - Name of the string to format. Supported names are:
        • library_info - The format of the text when displaying the "num_albums" element.
        • queue_info - The format of the text when displaying the "num_queued" element.
        • playlist - The format of playlist items in a "playlist" <list> element.
        • album - The format of the text overlayed on "albums" <list> element images.
        • album_title - The format of the text when displaying the "album_title" element.
        • cursong - The format of the text when displaying the current playing song.
        • nextsong - The format of the text when displaying the next song in the playlist.
        • songlist - The format of the song text in the currently selected album "songs" <list>
        • "playlist" - The format of playlist items in a "playlist" <list> element.
        • "album" - The format of the text overlayed on "albums" <list> element images.
        • "songlist" - The format of the song text in the currently selected album "songs" <list>
        • "cursong" - The format of the text when displaying the current playing song.
        • "nextsong" - The format of the text when displaying the next song in the playlist.
    • Children:
      • None
    • Value:
      • Not all Variables are available for all formats. For instance when the format name is "album", the "%song%" variable doesn't make sense.
      • All text not within the % pairs will always be displayed.
      • Additional text can be placed within the % pairs that is only displayed when the variable result is not empty. For instance %[year]% may display [1998] if the year is 1998. If the MP3 tag for the year is blank, then nothing will be displayed.
      • Available variables are:
        • %total_albums%
        • %total_songs%
        • %album%
        • %num_songs%
        • %album_duration%
        • %duration%
        • %song%
        • %track%
        • %artist%
        • %album%
        • %year%
        • %queue_count%

  • <def_click_snd>
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • The filename of the .WAV file to play whenever a button is clicked.

  • <examples>
    • The examples tag allows you to specify a sample set of images (normal, button pressed, and button hover) images. If a specified button image does not exist when the skin is loaded, the image will be cut from the example image at the specified coordinates and the image file will be created. This is a quick way to create or refresh a skin.
    • Attributes:
      • None
    • Children:
      • <normal>(string)</normal> - file name of the normal example image
      • <down>(string)</down> - file name of the down example image
      • <hover>(string)</hover> - file name of the hover example image
    • Value:
      • None
  • <font>
    Default Font to use. This is the name of the font only, sizes are specified for each element independently.
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Name of font (i.e. Arial)
  • <comment>
    Put anything you want in here, it is ignored. Technically any tag that is unknown is ignored.
    • Attributes:
      • None
    • Children:
      • None
    • Value:
      • Anything you want. It is ignored.
  • <button>, <area>, <list>, <slide>, <tree>
    Each of these tags are for creating elements on the skin display page. The order in which you put them into the skin.xml definition file is the order that they will be drawn. So the last element defined will be the top most element drawn. If elements overlap, this top most element will be drawn over top the others. When clicking on elements that overlap, elements that are on top of others will be processed first.

    * All these elements have very similar attributes and child elements but not all attributes and children apply to each type. If not specified it applies to all five types.
    • Attributes:
      • "name" (string) - The name of the button (or group). If an element does not have a "name" tag, then the name is set to the <function> value.
      • "hidden" (bool) - Whether this button is initially hidden or not. To change the hidden status create a button with a function of "toggle_hidden". Hidden buttons are useful when "chaining" events (see <chain> child tag) or when specifying "artistfilter" values to be used with a "nextartistfilter" button.
      • "toggle" (bool) - If this button is a toggle type button. These buttons stay depressed when pushed until they are pushed again. Buttons of this type should be tied to functions that toggle states. Currently this is limited to: "mute", "shuffle", and "loop".
      • "radio" (bool) - If this button is part of a group of buttons that act like radio buttons. All buttons with the same "name" attribute will be group together. Radio button groups force one and only button in their group to be "selected" at a time.
      • "selected: (bool) - If this button is initially selected or not (for radio buttons, and toggle buttons)
      • "x" (numeric) - The x coordinate where the button is located.
      • "y" (numeric) - The y coordinate where the button is located.
      • "w" (numeric) - The width of the button. (<area>, <button>, <tree>, <slide>)
      • "h" (numeric) - The height of the button. (<area>, <button>, <tree>, <slide>)
      • "cell_w" (numeric) - The width of each cell in a list (<list>)
      • "cell_h" (numeric) - The height of each cell in a list (<list>)
      • "x_cnt" (numeric) - The number of elements to draw horizontally (<list>)
      • "y_cnt" (numeric) - The number of elements to draw vertically (<list>)
      • "border" (numeric) - This thickness of the border of the element. (<area>, <list>, <tree>, <slide>)
      • "selborder" (numeric) - This thickness of the border of a selected element. (<list>)
    • Children:
      • <function>(string)</function> - The function defines what the button does when you click it. See the "Button Functions" section for a full list.
      • <parameter>(string) or (numeric)</parameter> - This parameter is specific to the function specified, and will be passed to the function when the element is clicked. (<button>)
      • <parameter2>(string) or (numeric)</parameter2> - This parameter is specific to the function specified, and will be passed to the function when the element is clicked. (<button>)
      • <chain>(string)</parameter> - Specifying a chain event will cause the specified button (by name) to be executed.
      • <clicksnd> (string) </clicksnd> - File name of a ".WAV" file that will play when the button is clicked. This overrides the "def_click_snd" element. (<button>)
      • <repeating> (bool) </repeating> - Whether or not holding the button down will cause it to repeatedly "press". (<button>)
      • <scroll>(bool)</scroll> - Whether the area scrolls or not. Used with text display areas like "cursong".
        • Attributes: "speed" (numeric) - The speed to scroll. Larger number is faster. It is actually the number of pixels to move the text every 100 milliseconds. defaults to 2 pixels.
      • <textoffsets> - Text offsets provide a way to specify a sub rectangle within the element rectangle for aligning the text that is drawn within it. It is specified as offsets from the edges, and can be positive or negative. (<area>, <list>)
        • Children:
          • <left>(numeric)</left> - Offset value to apply to the element left edge.
          • <top>(numeric)</top> - Offset value to apply to the element top edge.
          • <right>(numeric)</right> - Offset value to apply to the element right edge.
          • <bottom>(numeric)</bottom> - Offset value to apply to the element bottom edge.
      • <bgimg>(string)</bgimg> - The file name of the image to draw first, behind all states. (<area>, <button>)
      • <upimg>(string)</upimg> - The file name of the image to use in the normal state. (<area>, <button>)
        • <upimg>(string)</upimg> - When using this with <slide> elements, this image is a full version of the slider (as if the slider is at max) <slide>
      • <dnimg>(string)</dnimg> - The file name of the image to use when clicked. (<button>)
        • <dnimg>(string)</dnimg> -When using this with <slide> elements, this image is the empty version of the slider (as if the slider is at minimum)
      • <hoverimg>(string)</hoverimg> - The file name of the image to use when the mouse hover over the element. (<button>)
        • <hoverimg>(string)</hoverimg> -When using this with <slide> elements, this image is the "knob" of the slider. This is optional.
      • <text>(string)</text> - Static text to draw on the element. (<button>)
      • <align>(alignment)</text> - The text alignment to use. (<area>, <list>, <button>)
      • <font>(string)</font> - The name of the font to use (default: "arial")
        • Attributes:
          • "style" (string) - One of the following strings: "normal", "bold", "italic", "bolditalic", "italicbold", "underline", "strikeout"
          • "size: (numeric) - Point size of the font to use
      • <fonteffect>(string)</fonteffect> - The Font effect to use when rendering the font.
        • Attributes:
          • "param" (string) or (numeric) - Parameter passed to the effect function specified
          • "clr" (ARGB) - The color to be used for the effect
        • Value: The effect to be used
          • "none" - No effect, just render the text.
          • "shadow" - Render a drop shadow with the specified color. The "param" is interpreted as a number which is a pixel offset from the original text location to render the shadow.
          • "outline" - Render an outline around the text in the specified color. The "param" is interpreted as a number which is a pixel offset from the original text location to render the outline.
          • "fillbg" - Draw a rectangle behind the text with the specified color.
      • <clr>(ARGB)</clr> - Primary color of the element. This is the color which is used to draw text.
      • <bg_clr>(ARGB)</bg_clr> -
      • <sel_clr>(ARGB)</sel_clr>
      • <txt_sel_clr>(ARGB)</txt_sel_clr>
      • <dark_clr>(ARGB)</dark_clr> - For areas and non bitmap buttons, this is the dark color used to draw the border to give depth.
      • <hilite_clr>(ARGB)</hilite_clr> - For areas and non bitmap buttons, this is the light color used to draw the border to give depth.
      • <menu>
        • Attributes:
        • Children:
        • Value:
    • Value:
      • None

  • <popup>
    The contents of the popup element define a new set of controls that "pop-up" when hit. Use the "popup" button function and specify the "name" of the popup to open when clicked. Define a "close_popup" button within the popup to allow the user to close the popup.
    • Attributes:
      • "name" (string) - The name of the popup to being defined. Specify this name in the button <parameter> element that opens this popup,
      • "autoclose" (bool) - Specifies whether the popup closes automatically when the user clicks outside the area defined
    • Children:
      • <list>, <button>, <slide>< and <area> elements that define the popup. Use an area element to define the background. Just like regular elements, they are drawn first defined to last defined. So define the <area> of the background first, then the <button> or <list> elements. Also The popup will be drawn relative to the main page elements, so a popup may be "behind" elements defined later than the popup elements. If this makes sense?
    • Value:
      • None

Functions:

All <area>, <list>, <button>, <slide> and <tree> elements will have a function. The function defines what happens when you interact with the element, or what is displayed in the element. Functions are specific to the element type, so a button function cannot be used for an area function, or a list function.

Button Functions:
  • "close" - Close and Exit the application
  • "minimize" - Minimize the window to the toolbar
  • "songscroll" - Scroll the song list
  • "addsong" - Add the currently selected song to the playlist
  • "albumscroll" - Scroll the album list
  • "addalbum" - Add all the songs from the current album to the playlist
  • "clearplaylist" - clear the current playlist
  • "rngsong" - Add a random song to the playlist
  • "settings" - Open the settings window
  • "play" - Start playing
  • "stop" - Stop Playing
  • "next" - Skip to the next song in the playlist
  • "prev" - Skip back to the previous song in the playlist
  • "pause" - Pause playing
  • "volume" - Adjust the volume.
  • "menu" - Pop up a menu of options
  • "skin" - Select another skin
  • "about" - Open the about box
  • "mute" - Mute the volume
  • "shuffle" - Toggle shuffle mode
  • "loop" - Toggle looping of playlist
  • "toggle_fullscreen" - toggle fullscreen/windowed mode
  • "toggle_randomplay" - toggle random play mode
  • "toggle_attract" - toggle attract mode
  • "toggle_hidden" - toggle a hidden element or a group of elements
  • "popup" - Open a "popup" window with the specified element group
  • "close_popup" - Close the popup window.
  • "delete_playlist_item" - Delete the currently selected playlist item from the playlist
  • "move_playlist_item" - move the current playlist item
  • "playlistscroll" - scroll the playlist
  • "artistfilter" - set the album artist filter
  • "nextartistfilter" - advance to the next filter defined
  • "artistjump" - works like "artistfilter" but jumps to the next album that matches instead of filtering the album.
  • "shutdown" - Causes the computer to turn off. If the parameter is "force" then the user will not be prompted. *NEW v1.3.7

Area Functions:
  • "num_albums" - Display the number of albums in the library
  • "num_queued" - Display the number of songs in the playlist queue (not including the currently playing song)
  • "playlist_curitem" - Display the currently playing item
  • "playlist_nextitem" - Display the next item to be played
  • "album_title" - Display the title of the currently selected album
  • "selected_album_cover_art" - Display the currently selected albums album cover art
  • "cur_album_cover_art" - Display the album cover art of the currently playing song
  • "mediaplayer" - display the windows media player
  • "windowdrag" - defines the drag area for a window. Holding the button and moving the mouse in this area will "move' the window.
  • "generic" - Displays the bitmap or text specified
  • "song_pos" - Displays the song position as text (time value)
  • "next_album_cover_art" - Display the album cover art of the next song in the queue. *NEW v1.3.7

Slide Functions:
  • "song_pos" - Displays the song position as a slider.
  • "volume" - Displays a volume control slider.

List Functions:
  • "albums" - Display a list of the albums cover art
  • "songs" - Display the currently selected album songs
  • "playlist" - Display the current playlist entries

Tree Functions
Tree elements are not supported in popups. They are implemented using windows "standard" tree controls, and behave slightly different than the other elements. I am thinking of phasing them out.
  • "library" - Display the entire library of albums in a tree structure (artist->album->song)
  • "library_nosongs" - Display the entire library of albums in a tree structure, not including songs (artist->album)