21 Aug 2020 - The wiki is undergoing a major cleanup. If you arrived here from a search engine and cannot find the page, please use the wiki search instead (top right corner of page)
More info can be found on the forum


From Official Kodi Wiki
Jump to: navigation, search
Incomplete.png INCOMPLETE:
This page or section is incomplete. Please add information or correct uncertain data which is marked with a ?

This page or section has not been updated in a long time, no longer applies, refers to features that have been replaced/removed, and/or may not be reliable.

This page is only kept for historical reasons, or in case someone wants to try updating it.

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 Kodi 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 Kodi and involved having to add extra stuff to the controls in order to give more control over the creation of controls, WindowXML uses the WindowXML class in Kodi 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 Kodi to create their scripts, not really useful for general users.

1 class WindowXML

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

1.1 Constructor

1.1.1 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.

2 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")'

2.1 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

2.2 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

2.3 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

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

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

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

    def onFocus(self, controlID):

3 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.

4 Fallback Explained

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 Kodi media/texture handling works. For the 'DefaultSkin' its best to choose names that are unique so it won't conflict with a skin.

  • 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

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: Kodi holds its skins in a folder call skin, but for in the fallbackpath (typically script folder) use the folder skins

4.1 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