Window Structure



About the Window XML Files
Each window in an XBMC skin is represented by a single .xml file. See here for a list of the standard windows and links to their .xml files.

Each .xml file has the same basic structure – it starts with some heading information that pertains to the window as a whole, and then contains a block within which all the controls that describe the window are defined.

Window Header
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

The header contains the following tags:


 * onload
 * Optional: the build-in function to execute when the window opens


 * onunload
 * Optional: the build-in function to execute when the window closes


 * defaultcontrol
 * This specifies the default control of the window. This is the id of the control that will receive focus when the window is first opened. Note that most XBMC windows save the current focus when you leave the window, and will return to the last focused item when you return to a window. This behaviour can be stopped by specifying the attribute always="true".


 * backgroundcolor
 * Specifies whether the window needs clearing prior to rendering, and if so which colour to use. Defaults to clearing to black. Set to 0 (or 0x00000000) to have no clearing at all. If your skin always renders opaque textures over the entire screen (eg using a backdrop image or multiple backdrop images) then setting the background color to 0 is the most optimal value and may improve performance significantly on slow GPUs.


 * allowoverlay
 * Setting this tag to true, or yes, indicates that the music or video overlay may be shown when this window is active. If this tag is not present, the state of the previous (or parent) window is used.


 * visible
 * Specifies the conditions under which a dialog will be visible. XBMC evaluates this at render time, and shows or hides a dialog depending on the evaluation of this tag. See here for more details. Applies only to dialog .


 * animation
 * Specifies the animation effect to perform when opening or closing the window. See here for more details.


 * zorder
 * This specifies the “depth” that the window should be drawn at. Windows with higher zorder are drawn on top of windows with lower z-order. All dialogs by default have zorder 1, so if you have a particular dialog that you want underneath all others, give it a zorder of 0. (Note that the normal render order is: The base window, then the overlays (music + video), then dialogs. only effects the rendering of the dialogs.


 * coordinates
 * This block is used to specify how XBMC should compute the coordinates of all controls.


 * posx
 * Sets the horizontal “origin” position of the window. Defaults to 0 if not present.


 * posy
 * Sets the vertical “origin” position of the window. Defaults to 0 if not present.


 * origin
 * Sets a conditional origin for the window. The window will display at (x,y) whenever the origin condition is met. You can have as many origin tags as you like – they are evaluated in the order present in the file, and the first one for which the condition is met wins. If none of the origin conditions are met, we fall back to the and tags.


 * previouswindow
 * This can be used to specify a window to force XBMC to go to on press of the Back button. Normally XBMC keeps a “window stack” of previous windows to handle this. This tag allows you to override this behaviour. The value is the name of the window.


 * views
 * This tag lets you use view id's beyond 50 to 59 it also lets you set the order in which they cycle with the change view button in the skin. Only useful in My.xml windows.


 * controls
 * This is the block the defines all controls that will appear on this window.

The Different Types of Controls
XBMC supports many different types of controls.

Click here for the control types and what they all do.

Some of these controls are required on specific windows, as they're necessary for that window to perform it's duty, or, the contents of the control are only valid on a particular window. The mandatory controls for each window are listed here. While the controls are mandatory, you can ofcourse move them about and change their appearance within the windows to your hearts content!

Adding Extra Windows
All of the windows in the window list are defined within the executeable of XBMC itself, as most of them have a specific purpose. However, the skinner may add extra windows as and when they are needed or wanted. The only restriction to this is that only controls that do not require specific source code to operate can be used. This is not too much of a restriction though, as many skinners have found out.

To add an extra window, all you need to do is design up the window's .xml file in the usual way, assign it an  outside of the ones defined in the window list, and then name the file customN.xml, where N is a number. You can have as many as you like, as long as they have unique 's, and are named differently. Then just define the of window you want, the coordinate system and so on, add the controls and setup the navigation. To activate your window, you can do it by adding a button control elsewhere in the skin, or you can get it to popup on a press of the controller or remote via keymap.xml and so on. Basically you just need to run XBMC.ActivateWindow(id) from a suitable place.