How to skin MediaMonkey versions 3 and 4

Introduction

MediaMonkey offers a fair amount of flexibility to customize the look of the application. This document provides graphic designers with the information needed to make MediaMonkey even better looking than it already is.

The UI elements that can be modified are:

1. The MediaMonkey Skin
   • The application Theme (i.e. the look of buttons, borders, status bars, title bars, fonts, etc.)
   • The skin of the various incarnations of the player (the main player, mini-monkey, and micro-monkey) and the font of the text within
   • Background images for various panels
2. Icons within the application

The MediaMonkey Skin

A MediaMonkey skin consists of the Theme, the Player skins, and several background images that together make up a ‘skin’. Skins are packaged as .msz files, which are simply .zip files with an .msz extension, containing all skin elements, saved to:

\MediaMonkey\Skins\skinname.msz

so that users can choose a skin via Tools > Options > Skin.

Note that during the skin creation process, skin components can be created/edited in

\MediaMonkey\Skins\Skinname\<skin components>

so that there’s no need to continually repackage the skin during skin development. Once you’re satisfied with your edits, you can just Zip the contents of the \Test directory into a zip file, rename it to <Skinname>.msz, and place it in the \MediaMonkey\Skins\ directory to see the final result.

Customizing the Theme

The MediaMonkey Theme is what controls the overall look and feel of most aspects of the application (e.g. the titlebar, the buttons, the status bar, tabs, checkboxes, etc.). The theme is controlled by Theme.mskn which contains graphical elements and mappings of these elements to various UI objects. To edit a theme:

1. Extract a skin (e.g. Casino Blue.msz) to

   \MediaMonkey\Skins\Test\

2. Download the KSdev theme editor from

   http://www.mediamonkey.com/contrib/artwork/themeeditor7.exe

3. Run the Theme Editor and load Theme.mskn from the \Test directory into the theme editor and edit it and save it.
4. In MediaMonkey, Go to Tools > Options > Skins and select the new Test skin to see the results of your work (to refresh the skin, just switch skins in the Skins configuration panel).

During the editing process, there are 2 approaches you can take:

• If you have graphic expertise, but don't want to get into the details of configuring the size of buttons, their behaviour, setting margins, etc. the simplest approach is to create a new theme based on the graphics of an existing theme:
  1. Click File > Export Bitmaps and then edit the images, while making certain to maintain their exact dimensions
  2. Click the Images node in the ThemeEditor tree, select individual images and click 'Replace' to replace them with the newly edited images
  3. After replacing all the images, resave the .mskn file
  4. Switch to the skin entitled 'Test' to see how the changes look

• If you want much greater control and flexibility to control all aspects of a theme, you can create a new theme based on an existing one, but in addition to changing graphics images, you can also change various additional characteristics of the theme (e.g. fonts) by editing the properties of various objects that appear in the MediaMonkey UI.

Instructions on the use of Theme Editor is beyond the scope of this document. The best approach is to edit the properties of various objects in the tree and then saving the theme file and test out the Skin containing the new theme file by switching to it in MediaMonkey.

Below is a reference to all Theme.mskn objects used in the MediaMonkey UI:

Form

This defines the MediaMonkey frame, and buttons within the title bar

Caption\Title\Font - caption font

MenuBar

Only the ToolbarItem is used along with;

ItemButton (TSeButtonObject type) - This defines look of the top menu item (items like File, Tools etc.)

SubitemButton (TSeButtonObject type) - This defined buttons within menu (all items in menu)

Popup Menu

This defines the look of menus

CheckBox

Defines the look/behaviour of checkboxes

RadioButton

Defines the look/behaviour of radio buttons

ScrollBar

Defines the look/behaviour of scrollbars

NCArea - defines bottom right corner background (area between horizontal and vertical scrollbars)

Button

Defines the look/behaviour of OK/Cancel/Other buttons that appear within dialogs

SpeedButton

Defines the look/behaviour of buttons on the toolbar

GroupBox

Defines the group boxes that are used in some dialogs such as encoder selection dialog

ProgressBar

Defines the look of progress bar that's used to indicate status. Currently only the horizontal one is used.

TrackBar

Defines the look of the sliders/tracks used for the equalizer

Listbox

Defines the look of listboxes (e.g. the Scan Folders dialog, tracklist)

Item\ActiveBitmap - for selected item background

ItemAdv\ActiveBitmap - for unfocused selected text background

ItemAdv\ActiveFont - for unfocused control selected text font

-

ListBox colors and fonts:

Colors\ListBox\Body - used to set default background colour

Fonts\ListItemTextNormal - for normal text

Fonts\ListItemTextHot - for 'hot' text

Fonts\ListItemTextSelected - for selected text

Combobox

Defines the look of combo boxes

SpinButton

Used for Up/Down arrows

Panel

Used for docked dialogs

Tabs

Used for TabSheets

ControlBar

Used to control the look of toolbars

Toolbar

Used to control the look of toolbar backgrounds.

SubitemFont (TextObject) - font for popped menu items.

Header

Used to control the headers in lists

Section\Font - header font

StatusBar

Controls the look of the status bar

ToolWindow

Controls the look of mini dialog frames (e.g. Equalizer, Album Browser)

Caption\Title\font - title font

Container

Used for some backgrounds

Splitter

Divides up the toolbar

VirtualTree

Defines the look of the VirtualTree (TrackList, MainTree etc.)

Panel - for defining border

DragSelection - selection color for mouse-use drag selection

DragTarget - selection color for dagging target node

TrackListOdd - background image for odd rows in tracklist

TrackListEven - background image for even rows in tracklist

NowPlayingOdd - background image for odd rows in now playing

NowPlayingEven - background image for even rows in now playing

InfoPopup

Defines background and fields positions within popup info window

Frame\Background\AlbumArt - position and size of the place for album art image

Frame\Background\* - all fields with English names can be defined as TextObject (like Artist, Title etc.)

NavBar

Navigation bar settings

Background - navigation panel background

Node\Selection - background for selected node (mouse is hover it)

Node\DropMark - drop down sign

Node\Background - background for path node

Node\Caption - path node font settings

Also keep in mind the following hints:

• MediaMonkey has a default theme of Default.mskn that's used if a xxx.msz archive doesn't contain a Theme.mskn file. You can edit this if you like.
• Minimize single-pixel transparency in bitmaps to avoid performance hits
• Try to minimize the use of margins in your objects as they decrease performance
• It is best to use bitmaps that are distinct for each object (rather than a single image containing all objects) to avoid performance hits
• ThemeEditor has a bug which sometimes causes the bottom right pixel in an image to become transparent. To avoid this, add an extra pixel of padding to the right of the image, but don't use the rightmost column of pixels in your objects.
• All fonts in the fonts node should be set to 'Arial' to ensure correct functionality in unicode environments
• For Font properties other that in 'Fonts' node (like ListBox\ItemAdv\ActiveFont). They allow to use 'MS Shell Dlg 2' font and thus it should be used when needed (such occasions are appear in the above list) -- the trick with 'Arial' font isn't used there).
• Before finalizing your theme, make sure to test it at different DPI settings

Customizing Background Images

There are a number of background images used in MediaMonkey that are part of a skin (i.e. they are included within the <Skinname>.msz file. These include:

• sdb_background_playing.bmp – non-scrollable background for the Now Playing list (optional – use if scrollable background not defined in the Theme)
• sdb_background_list.bmp – non-scrollable background for the Track list (optional – use if scrollable background not defined in the Theme)
• sdb_background_tree.bmp – non-scrollable background of the tree

To customize these, just save the bitmaps to a skin directory or archive (msz file), and then switch skins or restart MediaMonkey to see your work.

Customizing Icons

The default MediaMonkey icons can be replaced globally to be used with any user-selected skin, or can be included with a specific skin if custom icons are desired for that skin.

To create a complete icon set to be used with any skin:

1. Download all icons via http://www.mediamonkey.com/contrib/artwork/icons.zip
2. Extract the icons from the .zip file to \Program Files\MediaMonkey\Icons\
3. To customize the icons, just edit any of the icons in the \Icons\ directory, and restart MediaMonkey. The new icons will appear.

To bundle specific custom icons within a Skin:

1. Download all icons via http://www.mediamonkey.com/contrib/artwork/icons.zip
2. Extract the icons from the .zip file to \Program Files\MediaMonkey\Skins\<Skinname>\Icons
3. Delete any icons that you do not plan to customize
4. Edit any of the icons that you wish to include with the skin
5. To customize the skin just save the icons to the skin directory or archive (msz file), and then switch skins or restart MediaMonkey to see your work.

Note that 2 icons aren’t exactly icons:

• NoAArt.png for unknown art in Album Art window
• NoAArtNew.png for unknown art in Album Art views

Customizing the Player

Basic Information

MediaMonkey v3 (MM3) comes with a new feature called Skinnable Player, which supports user defined player with its own skins (independent of MM skin).

There are 3 players in MM3:

1. Classic player in the main window.
2. Mini-player (MiniMonkey mode in older versions of MM)
3. Toolbar controller (new player placed on windows taskbar)

All of these players can be unique with different design and look.

Player Files

Every player skin is stored and defined in 2 files defining its skin and settings.

Classic player is defined in files Player.mskn and Player.ini. Mini-player player is defined in files FloatPlayer.mskn and FloatPlayer.ini. Toolbar controller can have two types: horizontal (when taskbar is on top or bottom edge of the screen) or vertical (when taskbar is on left or right edge of the screen). File name format for these types is MicroPlayerH (for horizontal) and MicroPlayerV (for vertical). Horizontal toolbar controller is then defined in MicroPlayerH.mskn and MicroPlayerH.ini, and vertical in MicroPlayerV.mskn and MicroPlayerV.ini.

MSKN file is standard ThemeEngine 6 (older version of TE can be used, but with no warranty) format with maximum compression. See to MSKN File section for more information about this file.

INI file is configuration file in a text mode and can be edited with any text editor.

All of these files must be stored in WSZ file with MM3s skin together. WSZ file is standard ZIP file with a changed file extension only.

When any of players in MM3 hasn’t its files in WSZ, MM3 uses built-in skin for missing player.

For development purposes, individual skin files don’t have to be packed in WSZ file, but can be stored all in a subfolder of MM\Skins folder.

MSKN File

Players MSKN file can contain these objects:

PlayerBackground (SkinObject)

Defines background of the Player. This object must contain object Frame and into this object you can store all parts of player background (like left side, center and right side).

Example:

PlayerBackground

Frame

LeftSide

Center

RightSide

With this hierarchy you can define player, which can be resized (center part can be tiled, stretched etc. when player is being resized).

Every player can have transparent parts of its design. One requirement is, that every transparent part must have the same color as color in upper left corner (point 0;0).

PlayButton, PauseButton, StopButton, PrevButton, NextButton, PlayPauseButton, ShuffleButton, ContinousButton, PlaylistButton, AutoDJButton (ButtonObject)

These objects represent basic player buttons. When you need to use more than 3 state buttons (like for PlayPauseButton where you need to design button for play and for pause both), then you can create objects with _UP and _DOWN postfixes and in INI file set to StateButton type (see below).

SeekBar, BalanceBar, VolumeBar (SkinObject)

Every seekbar can define its background (in these objects) and can define slider design with HorzSlider or VertSlider as its descendant.

Example:

SeekBar - this object defines seekbar background

HorzSlider - this object defines horizontal slider for seekbar

VertSlider - this object defines vertical slider for seekbar

Visualization {Left/Right} (BitmapObject)

This object defines bitmap for visualization background. If you use themed visualization then you must define VisualizationLeft and VisualizationRight (instead of Visualization) as backgrounds for left and right channels.

Visualizations (SkinObject)

Container for themed visualization bands. In this container you can define visualization steps for separate channels or for both together. All visualizations steps is defined as LeftBand0..LeftBandn, RightBand0..RightBandn or Band0..Bandn for both channels. Number of steps is defined in INI file of the player.

MonoStereoLabel (ButtonObject)

Indicator for mono/stereo. Mono indicator put into Bitmap and stereo into BitmapDisabled.

DigitPanels (ButtonObject)

Every digit panel uses bitmaps for its digits. In skin you can create 2 types of digits: small and normal.

Normal digits are named as Digit%, DigitEmpty and DigitNegative, where % is value (like Digit0, Digit4 etc.). Small digits have the same rules as normal digits, but name is SmallDigit.

For normal digits you can define TimeDivider object, which represents digits divider (like ‘:’, ‘-‘ etc.).

Rating (ButtonObject)

This button object is used for manage rating on a skin. There are need to be defined Bitmap and BitmapDisabled fields, where Bitmap is “highlighted” rating star and BitmapDisabled is “grayed” rating star.

StatusPanel (BitmapObject)

This panel is used as background for player’s status signs (like “playing”, “paused” etc.).

StatusImages/* (TBitmapObject)

Status images for player’s status (can be defined StatusPlay, StatusStop and StatusPause).

AlbumArt (TBitmapObject)

Custom defined AlbumArt image for tracks, that doesn’t have defined cover.

INI File

In ini file is many sections which corresponds with most names in MSKN file and can contain:

PlayerSkin

Basic information about skin and can contain these values:

EngineVersion

for which version of SkinnablePlayer is this skin designed (default 100 as 1.00 version)

Resizable

How can be skin resizeable. You can type 4 values with left, top, right and bottom sequence delimited with comma.

-

Example :

Resizeable=1,0,1,0 – skin can be resized by left and right edges

Size

Initial size of skin.

TimeFormat

Default time format.

DockAtMostBottom

This value defines if player can be docked at most bottom (under status bar) in main window.

DockLocked

If this value is set to 1, player is always docked on it’s default dock and can’t be docked to any other dock.

Sections can have these names:

PlayPauseButton, SeekBar, VolumeBar, BalanceBar, PrevButton, PlayButton, PauseButton, StopButton, NextButton, ShuffleButton, ContinousButton, AutoDJButton, MonoStereo, SongTitle, TimeDisplay, SearchBar, EQButton, PlaylistButton, KbpsDisplay, FreqDisplay, AlbumArt, Visualization (for standard MM build-in visualization), VisualizationLeft and VisualizationRight (for user themed visualization), MinimizeButton, MaximizeButton, CloseButton, SwitchButton, Rating, StatusPanel

Type of an object is defined by Type value and can be one of this:

Button, StateButton, DigitPanel, Text, TrackBar, BitmapLabel, Panel

Note : Rating and StatusPanel objects must be a type PANEL.

Other values, which can be defined:

Resizable

Defines, if object can be resized when user resizes player in Left,Top,Right,Bottom format. Also it defines controls alignment while resizing. If you define left/right or top/bottom to 0, control always stays in it’s position relative to resized size (e.g. if control in basic size will be on center and player is resized, then control will always be on center).

Pos

Position of the object in Left,Top format.

Size

Size of the object in Width,Height format. (Note: when height is greater than width, then object is defined as vertical .. this is usable for defining vertical seekbars).

Transperent

Ability to be transparent (1 indicates YES, 0 no).

TextMask

Text mask define which and how data is showed. See below for which masks can be used.

SmallDigits (only for DigitPanel type)

Defines, if digit panel uses small or normal digits (more about it at MSKN File section). 1 is Yes, 0 no.

ThumbSize (only for TrackBar type)

Defines thumb size.

ShowLimitH, ShowLimitV

These values defines horizontal and vertical limits for showing defined object. If players width/height is smaller than defined limit, then object is invisible.

FontColor

This value is used only for text objects. It defines font color in format RRGGBB (like FFFFFF is white color).

FontHeight

This value is used only for text objects. It defines font height in pixels.

FontName

User defined font for text object.

TextAlign

Text aligning. Can be -1 for left-align, 0 for center or 1 for right-align.

TrackReversed

Basic trackbar orientation have min value at the left or top of the trackbar. With this boolean value you can reverse this orientation (like for vertical volume bar which has max at the top of the trackbar). This is usable only for trackbars.

Steps

Defines steps of the user themed visualization. Images for this steps is defined in MSKN in Visualizations container.

Scrollable

For text objects it can be defined for enable/disable scrolling functionality (like for time display).

CenterOffsetX, CenterOffsetY

This values defines contant position of the object relative to player center (left/top edge of the object). Like CenterOffsetX=-20 defines, that the objects left edge will be always 20px left of the center of the player.

Lock<edge>Distange, Lock<edge>Object

Control can be locked by any of edge to any other control. If control, which is locked to is moved or sized, this control is automatically adjusted. Like:

LockRightDistance=-50 - right edge of the object will be always 50 pixels left from

LockRightObject=PrevButton - PrevButton’s left edge

By default, skinning engine detects buttons clicking area as non-transparent parts of the buttons. In some cases (like when you’re using images with alpha channel), this detection can be very limited. For this reason, every buttons can have it’s own mask in BitmapFocused property of the button object.

In addition you can use custom defined objects, which lets you to give to your skin more functionality and lucidity. Custom objects can be defined as Custom% (where % is unique number for anyone custom field, e.g. Custom1, Custom2, Custom3 etc.).

Switching between all players can be done via MediaMonkey (system’s minimize button and/or settings of the MediaMonkey) or you can use Player buttons:

MinimizeButton – in main player it switches to mini-monkey. In mini-monkey it uses MM settings for minimize.
SwitchButton – switches to micro-player (in all cases)
MaximizeButton – maximizes to main from mini-monkey or micro-monkey
CloseButton – closes whole MM

Custom objects can have this fields: Pos, Size, Transperent, TextMask, ShowLimitH, ShowLimitV

These fields has a same sense as above.

Type

Types for custom objects is same as for classic objects, but any new types are allowed :

IMAGE

Image control. Source of the image is defined in Source field (see below)

Source

Source for image object (image path and filename relative to MM directory) or “<Cover>” text to show album cover of the loaded track.

Usable Masks

mm:ss – time format (can be used with digit panels like TimeDisplay)

# - any digit: MM3 replaces # char with digit. You can use more than one # char (for 3 digits you can use ### etc.). This can be used with digit panels like FreqDisplay etc.

%A – Artist
%R – Album artist
%L – Album
%S – Song
%P – Playlist position
%I – Song position
%H – Song length
%J – Time to play
%G – Genre
%C – Author
%U – Custom1
%V – Custom2
%W – Custom3
%E – Songs file extension
%F – Filename
%Y – Year
%T – Song order
%B – Bitrate
%M – Songs BPM
%D – Temporary order