HOW-TO:Add a new window or dialog via skinning
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 thumb panel 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 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. XBMC loads all files of the form custom-<foo>.xml, where <foo> is a name or 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 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="1234" type="dialog"> <defaultcontrol>2</defaultcontrol> <allowoverlay>yes</allowoverlay> <visible>true</visible> <coordinates> <system>1</system> <posX>200</posX> <posY>100</posY> </coordinates> <controls> ... </controls> </window>
The most important tags here are:
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).|
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(1234) 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.
4 See also