Skinning Guide

From MediaMonkey Wiki
Jump to navigation Jump to search

MediaMonkey 5 offers unprecedented flexibility with its skins and layouts. Skins and layouts can range anywhere from changing colors and text size to overhauling the entire interface. This guide will walk you through the basics of how to create a new skin.

Introduction to the Skinning Framework

The structure of the MM5 user interface is controlled by HTML, and its styling (Colors, sizing, positioning, margins, padding, etc.) is controlled by CSS. The skinning framework uses a language extension called LESS. Skins are written in LESS, which is then compiled into CSS in runtime. It allows for cleaner and more modular styling, with extensive support for variables and combining classes. The full documentation is available at http://lesscss.org.

Folder structure

All of the LESS styling can be found under the skin folder. The "main" skin file is skin_complete.less, which imports all of the other LESS files. The skinning framework is split into multiple different files for organizational purposes.

  • Skin_base controls general properties such as colors;
  • Skin_layout controls structural properties such as sizing and structure;
  • Skin_animations controls definitions for animations;
  • Skin_menu controls pop-up menus (Context menus and header menus);
  • Skin_tabs controls tabs in the header;
  • Skin_mainwindow controls the general window;

as well as others which are self-explanatory by name.

Icons are held in the skin/icons subfolder. They must all be in SVG format. Icons are organized/named by filename, (Tip: To more easily browse and preview the icons, check out tibold's "svgsee" program, which shows thumbnail previews of svg files: https://github.com/tibold/svg-explorer-extension/releases)

Note: When creating your own skin, use the '_add' suffix in the filename to not overwrite the base file. So instead of 'skin_base.less' use 'skin_base_add.less' and thus values/variables defined in 'skin_base_add.less' is just complement to the base 'skin_base_add.less'. See other skin examples (e.g. unzip /skins/MeterialDesign.zip) to see and understand the structure.

Adding configurable settings to your skin

As of 5.0.2, you do not have to write JavaScript code to add user-configurable settings to your skin. Simply add an item to your skin's info.json, titled skin_options, containing an array of options. We will write detailed information on the supported controls & syntax soon, but you can get started by following the examples of Material Design and Monkey Groove. Additionally, the specifications are described here: https://www.ventismedia.com/mantis/view.php?id=18449

Make sure your JSON syntax is valid. We recommend using an IDE that supports syntax checking, such as Visual Studio Code (however, it is not necessary).

Creating Icons

For creating icons, we recommend a program like Inkscape, a free and open-source vector graphics software. If you use a program like Adobe Illustrator, more work must be done after exporting to clean up the SVG and make it display properly in MediaMonkey.

For info on how to use icons in code, see Getting Started (Addons)/Icons.

Creating a Document

Click File > New to create a new document. To resize your icon to 100x100:

  1. open Document Properties (Ctrl + Shift + D)
  2. Change Display Units to px
  3. Under Custom Size, change Width and Height to 100 and Units to px.

Creating Shapes and Text

It is important to convert any prebuilt shapes and text into pure paths, to ensure that the SVGs display properly on all systems. To do this:

  1. Right click the shape or text
  2. Click on Path > Object to Path

Colors

It is important that icons display properly on all skins. Please do not include colors in your icons, so that the user gets a consistent experience for all icons. To do this:

  1. Select all objects in the document
  2. Open the Fill and Stroke menu (Ctrl + Shift + F)
  3. Under the Fill tab, ensure that "Unset paint" is selected (Usually looks like a question mark)
  4. Under the Stroke tab, ensure that "Unset paint" is selected (Usually looks like a question mark)

SVG Export

To export SVGs correctly, change the export settings:

  1. Go to Edit > Preferences
  2. Navigate to Input/Output > SVG output
  3. Ensure that:
    1. Use named colors is unchecked
    2. XML formatting > Inline attributes is checked

When saving:

  1. Click File > Save As...
  2. Instead of "Inkscape SVG", select "Plain SVG"

After saving the icon

After saving, only one extra thing must be done to make sure the icon displays properly.

  1. Open the SVG icon in a text editor.
  2. Close to the top, you will see <svg width="100" height="100" viewBox...
  3. Change width="100" height="100" to width="100%" height="100%". This will prevent the icon from being sized incorrectly.

More coming soon