HOW-TO:Add a new window or dialog via skinning

From Official Kodi Wiki
Revision as of 12:23, 9 April 2016 by Ronie (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Home icon grey.png   ▶ Development ▶ Add-on development ▶ Skinning ▶ Skinning Tutorials ▶ HOW-TO:Add a new window or dialog via skinning

Kodi allows skinners to add as many custom windows as they like. The skinner does this by creating an xml file for the new window, and then adding xml code as necessary to dictate when the new window should be displayed.

Note that the skinner cannot just create arbitrary controls on each window, as some controls (such as spincontrols) can only be controlled and filled by Kodi itself. However, for buttons, labels, images, rss controls etc. there's no problem at all. You can make custom windows up that display all sorts of relevant information. See the references section for more information.

This tutorial will show you how to add a new dialog window that pops up when the user clicks on a button elsewhere in the skin.

1 Create the custom xml file

We start by creating the new window's xml file. Kodi loads all files of the form custom-<foo>.xml (note: the 'custom' prefix is mandatory), where <foo> is a name or number. These are loaded from the location from which it obtained it's Home.xml file.

Let's create a new xml file custom_help.xml. The most important section of custom_help.xml will be the header section which defines where the window is positioned, it's unique identifier, and what type of window we are wanting.

<window id="1100" type="dialog">

The most important tags here are:


We have reserved the 1100–1199 id range for custom windows. ID's outside of this range (not advisable) may also work if they are not already in use in Kodi. Here is a list of the id's to avoid.

type We set this to dialog as we want a popup dialog that displays on top of other windows. A normal window does not have this behaviour, as it will always be displayed fullscreen, on it's own.
coordinates We've set this up to use relative coordinates, so that all control positions will be defined relative to the window's top left corner, which we've specified to be (200, 100).

See here for more information on the rest of the tags available.

Now that this is done, you can add whatever controls you wish inside the <controls> block. Remember that their positioning is determined by the <coordinates> system you are using.

2 Determining when it should popup

The last thing to do is determine when the window will be on screen. This will, of course, be determined by how you want the window to operate:

It should popup on a press of a controller or remote key
If so, you can achieve this by adding ActivateWindow(1100) to a button in keymap.xml.
It should be activated from a button in the skin
If so, add a button control to the appropriate window, and set it's <onclick> tag to
It should automatically popup when another window is active
You can achieve this by changing the <visible> tag in the xml above to <visible>Window.IsActive(window)</visible>, where window is the string identifier of the window that you want. For instance,

will make the window popup whenever the user is playing a video in fullscreen. More information on the <visible> tags can be found here.

3 References

More information on the structure of skin xml files can be found here

More information on the different skin files, window names, and id's can be found here

More information on the $INFO[] label can be found here

Information on Button controls

Information on Image controls

Information on Label controls

4 See also