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

From Official Kodi Wiki
Revision as of 14:05, 25 June 2006 by Dankula (talk) (References)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

XBMC has support for skinners adding 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 list and thumbpanel controls) can only be controlled and filled by XBMC itself. However, for buttons, labels, images, rss controls etc. there's no problem at all. With the recent additions of the <info> tags, you can make custom windows up that display all sorts of relavant 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. XBMC loads all files of the form custom#.xml, where # is a number. These are loaded from the location from which it obtained it's Home.xml file, so you may have to replicate the file for different resolutions if you want it to be loadable for all XBMC users.

Let's create a new xml file custom6.xml. I'm using 6 as the number, as the default skin (Project Mayhem 3) has 5 custom windows already! The most important section of custom6.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.

<xml> <window>

 <id>4567</id>
 <defaultcontrol>2</defaultcontrol>
 <allowoverlay>yes</allowoverlay>
 <type>dialog</type>
 <visible>true</visible>
 <coordinates>
   <system>1</system>
   <posX>200</posX>
   <posY>100</posY>
 </coordinates>
 <controls>
 ...
 </controls>

</window> </xml>

The most important tags here are:

id

This must be a unique number not already in use in XBMC. Here is a list of the id's to avoid.

type We set this to dialog as we want a popup dialog that renders over the top of other windows, with the other window showing through in any parts we don't render to. A normal window does not have this behaviour.
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, ofcourse, 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 XBMC.ActivateWindow(4567) 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

<xml> <onclick>XBMC.ActivateWindow(4567)</onclick> </xml>

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, or id number of the window that you want. For instance,

<xml> <visible>Window.IsActive(FullScreenVideo)</visible> </xml> 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> tag can be found here

Information on Button controls

Information on Image controls

Information on Label controls