Metamorphis SDK
(last updated May 9, 2002)
Version requirements: MJ 8.0.267 and above

File called Main.xml is main file for the skin. One skin can have multiple skins inside. For example Main skin can load other skin. So there can be mini-me and mini-mini-me and micro-mini-me etc. You need to include file named TheSkin.gif (jpg,bmp) (preferred size: 310x210) with your skin package, this image will be displayed in Skin Manager.

Main Skin components:

1. WINDOWS
2. SCRIPTS
3. EXTRAS
4. TOOLTIPS
5. MENUS

WINDOWS

Metamorphis skinning engine supports as many windows as needed. There is only one rule which should be followed when creating Metamorphis skin: Window with Type="Main" must be present in the XML file and this window must be always visible. The rest of windows you can call as you wish. There can be as few as one window (main window) and as many as 1000. Main window is going to be visible by default, other windows can be made visible on start up by using OnInitialize event of the main window and using script commands to display other windows.

The Metamorphis window can be any shape and the button layouts can be anything the theme designer desires. Care to leave out some buttons or display items you don't care for? Go ahead leave them out -- Metamorphis doesn't care.

If window has ParentWindow attribute it will belong to the window specified in the attribute, and will be always on top of the window and coordinates of this window will be relative to the window coordinates.

Window attributes:

• Name - name of the window
• Bitmap - This file provides the background image for the player, other bitmaps are layered over this background image to create the various states of "on" and "off", buttons, sliders, etc.
• TransColor - (optional) Color of transparent pixels of the bitmap.
• Type - (optional) currently only "Main" can be used in this attribute.
• ParentWindow - (optional) Name of parent window for this window.

Window can contain the following window items: Buttons, InfoDisplays, Placehoders, Sliders

ZOrder of all windows by default follows window order in the XML file (from top to bottom). It can be changed by using Window Object command SetWindowBehind, see Scripts

In addition to window item a window can handle Events.

EXTRAS

Script

If you want your skin to use script file please specify name of the file. There can be unlimited number of script files used in a skin.

• File - Path to the script file. See Scripts

Example:
    <Entry Type="Script" File="script.js" />

Fonts

If you use some fancy font in a theme, there is a good chance that other people will not have that font on their machine. In that case, you should include your font in the theme package. Please make sure that you have the right to distribute that font with theme. If you are unsure of the rights regarding fonts, you may want to use Microsoft's WebFonts, which you can redistribute.

Skin can contain as many fonts as needed, upon loading of a skin all fonts specified in the skin will be installed on the system

• File - Path to the file containing font.

Example:
    <Entry Type="Font" File="SomeCoolFont.ttf" />
    <Entry Type="Font" File="AnotherCoolFont.ttf" />

This or any other font can be used in skin items displaying text such as Menus, InfoDisplays, Tooltips

• SUBITEM Font
  
  • Facename - Specifies the typeface name of the font to use to draw text.
  • Size - Size of the font.
  • Weight - Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.
  • Italic - (optional) Specifies an italic font if set to 1, otherwise set it to 0.
     
• SUBITEM Colors
   
  • Text - Color of item's text. Items: Menus, Tooltips, Placeholders(TrackList), InfoDisplays
  • Background - Color of item's background. Items: Menus, Tooltips, Placeholders(TrackList)
  • HighlightText - Color of item's highlighted text. Items: Menus, Placeholders(TrackList)
  • HighlightBackground - Color of item's highlighted background. Items: Menus, Placeholders(TrackList)
  • Frame - Color of item's frame. Items: Menus, Tooltips
  • Disabled - Color of item's text when disabled. Items: Menus
  • Selected - Color of item's text when selected. Items: Placeholders(TrackList)

Visualization

• Group - Name of visualization group, can be predefined (Collage, Oscilloscope, Planetarium, Spectrum Analyzer) or user defined.
• File - Path to the file containing visualization information. Media Jukebox visualization file can be created using MJ Visualization Studio. For more information read Media Jukebox help file.

Example:
    <Entry Type="Visualization" Group="CoolSkin" File="Blue Spiral.mjv" />
    <Entry Type="Visualization" Group="Planetarium" File="Visualizations\Nevermore.mjv" />

COM

Metamorphis skins can work as a container for COM controls.

• File - Path to the COM control file .

Example:
    <Entry Type="COM" File="SomeVeryCoolControl.dll" />

Tooltips

Metamorphis skinning engine allows tooltips to be skinned.

• Type - currently only Global type of Tooltips is supported
• SUBITEM Colors, see SUBITEM Colors.
• SUBITEM Font, see SUBITEM Font.
  

Example:
    <Entry Type="Global">
        <Colors Text="C0C0C0" Background="333333" Frame="dddddd" />
        <Font Facename="Arial" Size="14" Weight="100" Italic="0"/>
    </Entry>

Menus

Metamorphis skinning engine allows menus to be skinned.

• Type - currently only Global type of Tooltips is supported
• SUBITEM Colors, see SUBITEM Colors.
• SUBITEM Font, see SUBITEM Font.
  

Example:
    <Entry Type="Global">
        <Colors Text="C0C0C0" Background="333333" HighlightBackground="C0C0C0" HighlightText="333333" Frame="dddddd" />
        <Font Facename="Arial" Size="14" Weight="100" Italic="0"/>
    </Entry>

Button Items

Buttons in Metamorphis are bitmaps. It doesn't matter which bit depth your theme bitmaps are, but usually 256 color bitmaps will suffice while keeping the size of the skin down.

Button attributes:

• Name - name of the button, there are predefined button types which when pressed tell Metamorphis what action to perform. Metamorphis skinning engine also excepts user defined buttons which can execute action(s). There are three types of actions.
• Position - position of left-top corner of Button. Format "left, top"
• Bitmap - Bitmap which is going to be used to draw the button. Bitmap contains multiple state images for the button: 1 - Show ( UP), 2 - Down, 3 - Over, 4 - Disabled
• TransColor - (optional) Transparent color in the button bitmap.
• NumberImages - (optional) Number of images button bitmap contains, if not specified then 3, must be at least 2 ( UP, Down)
• Tip - (optional) Tooltip text
• FX - (optional) Transition effect, such as Blend, HFill, VFill, Scroll, OpenScroll, OpenFill and Rotate.
• FXSpeed - (optional) Speed with which the transition will be performed. Default value is 4.
• FXRepeat - (optional) How many times the effect will be repeated. If this value is -1 then effect will be repeated indefinitely . Default value is 1.

After button pressed OnButtonDown event will be sent notifying of state change.

NOTE: Initial State of a button can be changed by using Scripts in combination with Event

Example:
    <Entry Name="Close" Bitmap="Close.bmp" Tip="Close" Position="278,7" />

InfoDisplay Items

InfoDisplay Items define rectangular area in which text will be displayed.

InfoDisplay attributes:

• Name - name of the InfoDispay item.
• Rect - Rectangle in which to draw the text information. Format "left, top, right, bottom"
• Tip -  (optional) Tooltip text
• TrackInfo - (optional) template for track information , there are  predefined TrackInfo keywords which display information about currently playing track.
• Align - (optional) how to align text in the item. Predefined alignments are: Left (default), Right, Scroll, Rotate.
• SUBITEM Colors, see SUBITEM Colors.
• SUBITEM Font, see SUBITEM Font.
  

Example:
    <Entry Name="Bitrate" Tip="Bitrate" TrackInfo="BITRATE" Rect="156,137,189,155" Align="Right">
        <Colors Text="ffffff" />
        <Font Facename="Areal" Size="14" Weight="800" Italic="1"/>
    </Entry>

Placeholder Items

Placehoder attributes:

• Type - Type of the placeholder, There are predefined Placeholder types. Type ca also contain ClassID of a COM control.
• Name - name of the Placeholder item.
• Rect - Rectangle in which to insert item of specified type. Format "left, top, right, bottom"
• Bitmap - (optional) bitmap and transcolor are optional, but can be used to create non rectangular shapes.
• TransColor - (optional) transparent color for the bitmap, used to create non-rectangular areas.
• Tip - (optional) Tooltip text

Example 1:
    <Entry Type="Visualization" Name="Visualization" Rect="31,97,130,196" Tip="This is visualization" Bitmap="star.bmp" TransColor="FF00FF" />

Example 2:
    <Entry Type="8856F961-340A-11D0-A96B-00C04FD705A2" Name="Browser" Rect="10,70,380,350"/>

Slider Items

Slider attributes:

If bar width is more than height, then slider is vertical.
Thumb always aligned to the top the top of the slider bar image in case of Horizontal bar, and to the left in case of Vertical one.

• Name - Name of slider control, See Predefined Slider Types.
• Position -  position of left-top corner of the slider bar. Format "left, top"
• Bitmap - Bitmap which is going to be used to draw the slider body.
• NumberImages - (optional) 1 - normal state, 2 - fill state, by default 1.
• TransColor - (optional) Color of transparent pixels of the bitmap.
• Tip - (optional) Tooltip information
• SUBITEM Thumb:
  • Bitmap - Bitmap which is going to be used to draw the thumb.
  • TransColor - Color of transparent pixels of the bitmap.
  • NumberImages -  default number of images for thumb is 1, but 3 images can be used: 1 - Up, 2 - Down, 3 - Over
  • ZOrder - (optional) thumb ZOrder: -1 - under bar, 0 - above bar
  • Align - (optional)
    Vertical Slider - Left, Right and Center (Center is just Left aligned with default value set to 50%).
    Horizontal sliders - Top, Center and Bottom (Center is just Bottom aligned with default value set to 50%)
    Default value Left for Horizontal sliders, Bottom for Vertical.

Example:
    <Entry Name="Volume" Bitmap="volume_bar.bmp" Tip="Drag to change Volume" Position="277,50" NumberImages="2">
        <Thumb Bitmap="volume_thumb.bmp" />
    </Entry>

Events

Predefined Events:

Window Events:

    Main Window Events:

    NOTE: This event will be sent to the Main window only.

    Init and Exit events:

• OnInitialize - Called when skin loaded, this is first event window receives. Loading of a skin windows state should be done in this event.
• OnExit - Called when skin is about to be destroyed. Saving of a skin windows state should be done in this event.

    State changed events:

• OnMixerChanged - Called when system mixer is changed ( volume, balance and mute change), use MJMixerAutomation object to determine state of the mixer.
• OnPlayStateChanged - Called when playback state changes, use MJPlaybackAutomation object to determine state.
• OnEqualizerChanged - Called when Equalizer state changed.

    Generic Window Events:

• OnShow - Called when window becomes visible
• OnHide - Called when window is hidden.

Event attributes:

• Event - One of the predefined window events
• Action - Action type, there are predefined types of actions.
• ActionData - see predefined types of actions.

Example:
    <Entry Event="OnInitialize" Action="Script" ActionData="PlayerInitialUpdate" />

Item Events:

Event attributes:

• Event - One of the predefined button events
• Item - name of a button
• Action - Action type, there are predefined types of actions.
• ActionData - see predefined types of actions.

Generic Item Events - Generic events will be send to all skin items

• OnMouseOver - Called when mouse hovers over button.

Button Item Events - Sent only to Button items.

• OnButtonDown - Called when button pressed.

Slider Item Events - Sent only to Slider items.

• OnSliderPositionChanged - Called when slider position changes.

Example:
    <Entry Event="OnButtonDown" Item="ShowPlaylist" Action="Script" ActionData="PlayerInitialUpdate" />

COM Control Events:

• Event - Specific to the control
• Item - name of the placeholder.
• Action - Action type, there are predefined types of actions.
• ActionData - see predefined types of actions.

Example:
    <Entry Event="StatusTextChange" Item="Browser" Action="Script" ActionData="OnStatusTextChange" />

Appendix A

Predefined button types

These buttons can be located in any window.

Window State Buttons:

• Close - pressing this button will result in closing parent window.
• Minimize - pressing this button will result in parent window becoming minimized.
• Megaview - pressing this button will switch Metamorphis from mini-me to MEGA-ME mode.

Play State Buttons:

• Play - Starts playback
• Stop - Stops playback
• Pause - Pauses playback
• Previous - Switches to previous track
• Next - Switches to next track

Playlist State Buttons:

• TracklistScrollUp - Scrolls playlist one page up.
• TracklistScrollDown - Scrolls playlist one page down.

Equalizer State Buttons:

• EqOff - Turns Eq off
• EqOn - Turns Eq on
• EQToggle - toggles EQ between on and off

Volume:

• ToggleMute - toggle mute state of system volume.

Actions

• Script - Executes JScript function specified in ActionData field
• Link - Use this action to navigate to the resource identified ActionData field.
• LoadSkin - loads skin specified in ActionData field of the action.

Predefined TrackInfo keywords

These TrackInfo keywords can be used to display information about currently playing track

    General Info:

• ARTIST - artist name
• ALBUM - album name
• NAME - track title
• TRACK# - track number
• GENRE - genre
• YEAR - year
• COMMENT - comment

    Time keywords:

• ELAPSED_TIME - current time of the track
• REMAINING_TIME - time left in the track
• TOTAL_TIME - track duration

    Playback Info:

• SAMPLE_RATE - samplerate of the track
• BITRATE - bitrate information
• CHANNELS - number of channels
• PN_TRACKS - total number of tracks in current playlist
• PN_POSITION - position of current track in the playlist

You can also access this information through MJAutomation object is JScript, for more information about that see SDK for Interface Plug-ins.

Predefined Slider types

These Slider Items can be located in any window.

• Position - position of currently playing track
• Volume - volume slider
• Balance - balance slider
• TracklistPosition - this slider shows and sets TrackList placeholder position.
• EqSlider00 - preamp
• EqSlider01 - 60 Hz equalizer slider
• EqSlider02 - 170 Hz equalizer slider
• EqSlider03 - 310 Hz equalizer slider
• EqSlider04 - 600 Hz equalizer slider
• EqSlider05 - 1 KHz equalizer slider
• EqSlider06 - 3 KHz equalizer slider
• EqSlider07 - 6 KHz equalizer slider
• EqSlider08 - 12 KHz equalizer slider
• EqSlider09 - 14 KHz equalizer slider
• EqSlider10 - 16 KHz equalizer slider
• BaseSlider - base slider
• TrebleSlider - treble slider

Predefined Placeholder types

These Placeholder Items can be located in any window.

• Visualization - Visualization window. NOTE: there can be only one placeholder of this type.
   
• TrackList - Track list window. NOTE: there can be only one placeholder of this type.
  • SUBITEM Colors, see SUBITEM Colors
  • SUBITEM Font, see SUBITEM Font.
     
• Picture - Picture window.
  • SUBITEM Params
    • Picture - Bitmap file which should be loaded into Picture placeholder

If Type Attribute is a class id then Metamorphis engine will try to create control with specified Class ID.

Support

If you have questions or concerns not addressed by this SDK, or just have suggestions for making the SDK more understandable, please visit our developer's forum