WindowXML

WindowXML is a class available in the python scripting side of XBMC. The WindowXML GUI Toolkit is an application framework that allow python scripters to create dynamic windows from an XML file, just like how XBMC skinners creates windows from XML for Home, Music, Programs windows, and similar to how GUIBuilder.py (a library written in python for XBMC) can take the XML and make a window, how ever it was limited solely to controls that existed in XBMC and involved having to add extra stuff to the controls in order to give more control over the creation of controls, WindowXML uses class in XBMC for creating windows from XML, so it will always use the same XML format/style, as XBMC.

This page is meant for python scripters using XBMC to create their scripts, not really useful for general users.

class WindowXML
The WindowXML class, inherits Window it includes what is called a 'WindowList' more about below.

WindowXML(self, XMLname, fallbackPath[, defaultskinname, forceFallback)

 * XMLname is a the name of the XML file to load
 * fallbackPath is the directory to fallback to if the XML doesn't exist in the current skin, or if forceFallBack is true
 * defaultskinname is OPTIONAL, it takes the name of the folder in the fallback path to look in for the xml. 'Default' is used if this is not set.
 * forceFallback is OPTIONAL and takes a Boolean - if true then it will look only in the defaultskinname folder.

Window Lists
WindowXML has has what are termed 'Window Lists'. its a List thats actually stored in the window. It can be viewed using Lists or Panel Controls with id 50 to 59, and is accessed by using methods on the actual windowxml class, 'self.addItem("Hello")'

Methods
Methods for controlling and accessing the WindowLists
 * addItem(item) -- Add a new xbmcgui.ListItem to the window list.
 * clearList -- Clear the Window List
 * getCurrentListPosition -- Gets the current position in the Window List
 * getListItem(int) -- Returns a given ListItem in the WindowList at the specified position
 * getListSize   -- Returns the number of entries in the WindowList (the size of the WindowLists)
 * removeItem(itemPosition) -- Removes a specified item based on position in the list from the window list.
 * setCurrentListPosition -- Set the current position of the Window List

Controls
TODO) Write about how to use controls. (A Start) The key to using WindowXML is by id, onClick and onFocus both give you the ID of the control clicked (not a 'control object' like normal Python Windows and Dialogs do. To set visiblity on controls or change labels etc use .getControl(ID) which will return a object of the control type (provided it has a python equivalent). Need to see about having a generic control return if its not, its on the TODO list.

Important if you don't want to use the WindowLists you still need to remember not to use the ids for other stuff.
 * id 3 - Button - For the View button (to change between the lists)
 * id 4/5 - Reserved (Don't actually do anything at the moment)
 * id 12 - Label - For displaying the number of items in the WindowLists
 * id 50-59 - Lists/Panels - The actual lists for displaying the information in the window lists

Base 'FrameWork' for a WindowXML
class MyFirstWinXML(xbmcgui.WindowXMLDialog): def __init__(self,strXMLname, strFallbackPath, strDefaultName, forceFallback): # Changing the three varibles passed won't change, anything # Doing strXMLname = "bah.xml" will not change anything. # don't put GUI sensitive stuff here (as the xml hasn't been read yet       # Idea to initialize your variables here        pass

def onInit(self): # Put your List Populating code/ and GUI startup stuff here pass

def onAction(self, action): # Same as normal python Windows. pass

def onClick(self, controlID): """           Notice: onClick not onControl            Notice: it gives the ID of the control not the control object        """ pass

def onFocus(self, controlID): pass

Default Skin
The idea behind it is scripts using WindowXML should always come with a default skin, which shouldn't rely on includes and defaults, meaning all the tags for the controls should be implicitly defined so it will look the same regardless of skins. It should also include all the graphics such as backgrounds for a skins. Images should be uniquely named like defaultYoutubeBackground.png or dYoutubeBackground.png so it doesn't conflicts with a file of the same name included with a skin. Fonts are currently out of your control, scripters have no way of loading their own TTF fonts in and using them.

Fallback Explains
By default forceFallback is 'false' so it won't diminish looking in the current skins folder. Note: media doesn't fallback the same way. If an image has the same name as one in the current skin it will use that, this is due to the way XBMC media/texture handling works. For the 'DefaultSkin' its best to choose names that are unique so it won't conflict with a skin. Summary, is it will keep 'falling back' until it hopefuly finds it. Its set up so it will always check the pal folder just for consistency. Note: XBMC holds its skins in a folder call skin, but for in the fallbackpath (typically script folder) use the folder skins
 * Step 1) Looks in q:\skin\currentskin\currentresolution\ for XMLname
 * Step 2) If that wasn't found, check q:\skin\currentskin\pal
 * Step 3) If that wasn't found, check %fallbackpath%\skins\currentskin\currentresolution
 * Step 4) If that wasn't found, check %fallbackpath%\skins\currentskin\pal
 * Step 5) If that wasn't found, check %fallbackpath%\skins\Default\currentresolution
 * Step 6) If that wasn't found, check %fallbackpath%\skins\Default\pal

Example
Let’s assume, your running Project Mayhem III, in 720p, and XMLName is Script_WindowXMLExample.xml, and fallback path is q:\scripts\WinXMLExample\ and Default skin name is 'DefaultSkin' WindowXML will check
 * Q:\skin\Project Mayhem III\720p\Script_WindowXMLExample.xml
 * Q:\skin\Project Mayhem III\480p\Script_WindowXMLExample.xml
 * Q:\skin\Project Mayhem III\pal-16x9\Script_WindowXMLExample.xml
 * Q:\skin\Project Mayhem III\pal\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\Project Mayhem III\720p\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\Project Mayhem III\480p\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\Project Mayhem III\pal_16x9\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\Project Mayhem III\pal\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\DefaultSkin\720p\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\DefaultSkin\480p\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\DefaultSkin\pal_16x9\Script_WindowXMLExample.xml
 * Q:\scripts\WinXMLExample\DefaultSkin\pal\Script_WindowXMLExample.xml

It progresses onto the next path if it can't find it. Note: pal_16x9 may not be guaranteed based on the fact it depends on the skin.xml in the skin what the default resolution. However it always will end up in 'pal' as a safe guard.

See CSkinInfo::GetSkinPath in Skininfo.cpp and WindowXML_New in winxml.cpp for the code for how fallback works