How to skin MediaMonkey v3.0 and higher

From MediaMonkey Wiki
Revision as of 18:16, 25 May 2007 by Morten (talk | contribs) (Customizing the Theme: Added MainTreeBackground information)
Jump to: navigation, search

This entry is only for documentation purposes. For a walkthrough of how to skin your MediaMonkey interface, please see the Walkthrough on how to skin MediaMonkey v3.

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
MainTreeBackground - background image for the nodes (BitmapObject)
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 in it’s default position and can’t be docked to any other position.


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

Available from MediaMonkey 3 Alpha 5 (build 1035);
 %Cn - custom field (n must be between 1 and 5)
 %PC - current track in playlist
 %PT - total tracks in playlist