View source for How to skin MediaMonkey v3.0 and higher

''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:
#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
#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 <code>Tools > Options > Skin</code>.


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:
#Extract a skin (e.g. ''Casino Blue.msz'') to
#:''\MediaMonkey\Skins\Test\''
#Download the KSdev theme editor from
#:http://www.mediamonkey.com/contrib/artwork/themeeditor7.exe
#Run the Theme Editor and load ''Theme.mskn'' from the ''\Test'' directory into the theme editor and edit it and save it.
#In MediaMonkey, Go to <code>Tools > Options > Skins</code> 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:
*#Click <code>File > Export Bitmaps</code> and then edit the images, while making certain to maintain their exact dimensions
*#Click the Images node in the ThemeEditor tree, select individual images and click 'Replace' to replace them with the newly edited images
*#After replacing all the images, resave the .mskn file
*#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:
#Download all icons via http://www.mediamonkey.com/contrib/artwork/icons.zip
#Extract the icons from the .zip file to ''\Program Files\MediaMonkey\Icons\''
#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:
#Download all icons via http://www.mediamonkey.com/contrib/artwork/icons.zip
#Extract the icons from the .zip file to ''\Program Files\MediaMonkey\Skins\<Skinname>\Icons''
#Delete any icons that you do not plan to customize
#Edit any of the icons that you wish to include with the skin
#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:
#Classic player in the main window.
#Mini-player (MiniMonkey mode in older versions of MM)
#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)
<div style="margin-left: 25px;">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).</div>

'''SeekBar, BalanceBar, VolumeBar''' (SkinObject)
<div style="margin-left: 25px;">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</div>

'''Visualization {Left/Right}''' (BitmapObject)
<div style="margin-left: 25px;">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.</div>

'''Visualizations''' (SkinObject)
<div style="margin-left: 25px;">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 LeftBand''0''..LeftBand''n'', RightBand''0''..RightBand''n'' or Band''0''..Band''n'' for both channels. Number of steps is defined in INI file of the player.</div>

'''MonoStereoLabel''' (ButtonObject)
<div style="margin-left: 25px;">Indicator for mono/stereo. Mono indicator put into Bitmap and stereo into BitmapDisabled.</div>

'''DigitPanels''' (ButtonObject)
<div style="margin-left: 25px;">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.).</div>

'''Rating''' (ButtonObject)
<div style="margin-left: 25px;">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.</div>

'''StatusPanel''' (BitmapObject)
<div style="margin-left: 25px;">This panel is used as background for player’s status signs (like “playing”, “paused” etc.).</div>

'''StatusImages/*''' (TBitmapObject)
<div style="margin-left: 25px;">Status images for player’s status (can be defined StatusPlay, StatusStop and StatusPause).</div>

'''AlbumArt''' (TBitmapObject)
<div style="margin-left: 25px;">Custom defined AlbumArt image for tracks, that doesn’t have defined cover.</div>



====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.<br>
'''SwitchButton''' – switches to micro-player (in all cases)<br>
'''MaximizeButton''' – maximizes to main from mini-monkey or micro-monkey<br>
'''CloseButton''' – closes whole MM<br>

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)


<nowiki>#</nowiki> - 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.

<br> %A – Artist
<br> %R – Album artist
<br> %L – Album
<br> %S – Song
<br> %P – Playlist position
<br> %I – Song position
<br> %H – Song length
<br> %J – Time to play
<br> %G – Genre
<br> %C – Author
<br> %U – Custom1
<br> %V – Custom2
<br> %W – Custom3
<br> %E – Songs file extension 
<br> %F – Filename
<br> %Y – Year
<br> %T – Song order
<br> %B – Bitrate
<br> %M – Songs BPM
<br> %D – Temporary order
<br> 
<br> ''Available from MediaMonkey 3 Alpha 5 (build 1035);''
<br> %Cn - custom field (n must be between 1 and 5)
<br> %PC - current track in playlist
<br> %PT - total tracks in playlist