MediaPortal Wiki 
MediaPortal-II skinning
This document explains how you can create own skinfiles or even create complete skins for MediaPortal-II. All UI screens in MediaPortal-II are rendered from a skinfile, so the term skinning refers generally to the job of designing and implementing UI screens.
Skin file format
MediaPortal-II uses XAML as skin file format. XAML is an XML based file format which is used to define UI elements, data binding, events and other features.
The XAML files are interpreted by a XAML engine which was implemented especially for MediaPortal-II. For a further explanation of the XAML engine, read the SkinEngine page.
The control library used by MediaPortal-II is similar to Microsoft WPF. We call it MediaPortal Presentation Foundation (MPF).
Learning XAML
There are many tutorials and books available on XAML.
Some online examples:
Search for Windows Presentation Foundation in the Microsoft MSDN
XAML design tools
There is a number of graphical design tools you can use to create XAML files. I suggest to use those tools at the beginning, or to fulfill special tasks (creating animations etc.). For the daily skinning use, you should edit the XAML files by hand, because this gives you a better feeling for what you are doing, and it produces much better and performanter code. Tools which support editing XAML files are for example:
Using these tools you can graphicly design your skin (or parts of it) and when you are done, you can export your work to XAML and use it in MP-II.
Creating Skins for MediaPortal-II
This section introduces into the development of skins for MediaPortal-II. It will focus on the skinner's view. To understand the reasons for some of the skinning precepts given here, and to get some technical background, you should read the SkinEngine page.
What constitutes a Skin?
From the users point of view, a skin is a set of definitions which make up the appearance of the application to the user. It can be also seen as a container for layout information and different themes. Technically, it is constituted by a set of files with different kinds:
Exactly one skin descriptor (skin.xml)
- 0-n screenfiles (*.xaml)
- 0-n Font declaration files
- 0-n Media files (pictures, sound, ...)
- 0-n Style resource files
- others (not specified yet)
Theme resources
Technically, all those files, except those written in italics, can be located both in the skin or in themes. Files located in the theme always override files in the skin with the same name. Sometimes it might be useful to define one resource file in the skin, which then will be overridden in some of the themes. But in most of the cases, resources have a fixed location, either in the skin or in the themes. In the following sections, the preferred location will be specified.
File locations
In the simplest form, all those files are located relative to one skin root directory. The skin root directory is located in a plugin, where it is declared as a "skin" resource directory by the plugin descriptor (the plugin.xml file). The name of the skin root directory has to match the logical skin name. For a description how to write a plugin and how to declare plugin resources, see the plugins wiki pages.
Skin descriptor (skin.xml)
The skin descriptor holds metadata for the skin, such as the name, its author, its native screen size, etc. The skin descriptor file has to be located in the skin's root directory.
Screenfiles
Screenfiles contain the skin's layout information, like the placement of the menu and the contents, for all screens. For every screen the system has to have at least one screenfile. Screenfiles are located in the skin's or theme's screenfiles subdirectory (preferred location: skin).
Font files
Font information can be given in several formats (to be completed). Font files are located in the skin's or theme's fonts subdirectory. All fonts have to be registered in the file fonts.xml (to be changed), also located in the fonts directory (preferred location: skin or theme).
Media files
Media files are all files which provide image or sound to the skin. They are referenced from the screen files. Media files are located in the skin's or theme's media subdirectory (preferred location: skin or theme).
Style resources
Style resource files contain style information like the appearance of controls, colors and animations. Style resource files are located in the skin's or theme's styles subdirectory (preferred location: theme).
HelloWorld Skinfile
To create a typical "Hello World" skinfile, we use a text- or XML-editor. As XAML files are XML files, we need to put an XML header at the top of the file. The root element to be shown can be any UI element, we'll use a panel here. Then we place a label into the panel, which shows our text.
<?xml version="1.0" encoding="utf-8"?>
<StackPanel
xmlns="www.team-mediaportal.com/2008/mpf/directx"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<Label Content="Hello World"/>
</StackPanel>As you can see, we use a default XML namespace of www.team-mediaportal.com/2008/mpf/directx. This namespace contains all MPF UI elements, and works exactly like the default WPF namesapce http://schemas.microsoft.com/winfx/2006/xaml/presentation for most of our supported UI elements. The XML namespace declaration xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml", which defines the x: prefix for the current element, is used in the XAML file exactly like it is used in WPF, although we make use of an own implementation of the namespace elements.
Deeper look into skinfiles
(To be continued)
Themes
(To be continued)
HelloWorld Skin
(To be continued)
Addendum
Find here some additional information regarding skin development.
Tipps and tricks for skinning in MP-II
Converting .svg to XAML
If you have a .svg file and want to use it in MediaPortal II, you can use ViewerSvg to covert the .svg file to a XAML file.
After the conversion, you can use the XAML file in MediaPortal-II.
Video playback
For video playback we introduced a VideoBrush.
A VideoBrush can be used like any brush in XAML.
Example:
<Canvas>
<Canvas.Background>
<VideoBrush Stream="0"/>
</Canvas.Background>
</Canvas>This example will render the background of the canvas with the video.
Note that the VideoBrush has an optional Stream property.
The stream indicates which video-stream to display in the brush.
So when for example two videos are playing, you can choose between Stream="0" and Stream="1"
For example PIP could be done like:
<Canvas Width="720" Height="576">
<Canvas.Background>
<VideoBrush Stream="0"/>
</Canvas.Background>
</Canvas>
<Canvas Width="160" Height="40">
<Canvas.Background>
<VideoBrush Stream="1"/>
</Canvas.Background>
</Canvas>This will render the main video fullscreen and the PIP video stream in the upper left corner
Disambiguation of terms
(Logical) Screen
A (logical) screen is a logical application state in respect to the GUI. A screen presents the current application state to the user. Every screen needs at least one skin file defining its appearance. The term Screen is used to describe a logical view without regard to a specific implementation, a skin file. There are some standard screens defined like home, fullscreenvideo, ..., and there are also new screens defined by skins or plugins, for example tetris-main.
Normally, screen sequences are all rendered in the current skin, but a sequence of screens shown to the user may also be displayed by skin files from different skins, maybe because the current skin doesn't define skin files for some screens to be shown. Then the GUI engine has to fallback to the default skin.
Screens are referenced by
- Other screens (for example when pressing the fullscreen media button, the fullscreenmedia screen will be shown)
- Models (for example a model may show a dialog when it needs user input)
The SkinEngine (for example when it starts up, it shows the home screen)
Theme
Set of colors, control appearances (styles), control animations, font, font sizes, background image, etc., to be used to render a skin. Every theme can inherit some properties of a parent theme, typically the default theme. Themes may replace the styles in the standard theme completely or just some of them, and/or add new styles and theme resources. Themes implement how controls will look like.
Skin
Set of files describing the arrangement of controls for every screen. A skin also defines the available screens and the control flow in the application.
Skins define which controls are shown where in every screen. Skins which support themes have to be flexible enough to show controls of different themes, so they must not have hardcoded control positions or colors.
Skins always have to cope with the problem, that multiple suppliers who don't know each other participate in the construction of the skin (i.e. MP main developers and developers of different additional plugins).
There needs to be at least one (standard) skin file for each screen. The MediaPortal-II system implements default skin files for each standard screen, and every model has to define default skin files for each of its screens.
Skin file
A skin file is a file containing XML/XAML data representing exactly one element (which may be a control or a helper instance instantiated from the XAML data), optionally with sub elements. A skin file may contain the root control to be shown as top element in a window (see definition of "window") or a helper instance (like a ?ResourceDictionary) which can be included in other skin files by a XAML "Include" element.
A skin file represents either a screen (see screen) or is an include.
Physical Screen
A physical screen is a graphics output device (for fullscreen display setting) or an (OS) window (for windowed display setting). A physical screen has a physical resolution.
Form
A form is the (OS) control to be rendered on a physical screen. It renders one (logical) screen at a time, typically a form runs fullscreen at a specific physical screen. But it is also possible to use MP-II in windowed mode, then you can have multiple forms which can be moved as (OS) windows on the physical screens.
Window (term is deprecated)
The term window was used in the past as a synonym of "logical screen". In fact it meant the materialized screen, consisting of the control instances which were instantiated for the XAML screen file.