Kodi Documentation 18.0
Kodi is an open source media player and entertainment hub.
Modules | Classes | Functions
Window
Python » Library - xbmcgui

GUI window class for Add-Ons. More...

Modules

 Callback functions from Kodi to add-on
 GUI window callback functions.
 
 Subclass - WindowDialog
 GUI window dialog class for Add-Ons.
 
 Subclass - WindowXML
 GUI xml window class.
 

Classes

class  XBMCAddon::xbmcgui::Window
 

Functions

 XBMCAddon::xbmcgui::Window::show ()
 
 XBMCAddon::xbmcgui::Window::setFocus (...)
 
 XBMCAddon::xbmcgui::Window::setFocusId (...)
 
 XBMCAddon::xbmcgui::Window::getFocus ()
 
 XBMCAddon::xbmcgui::Window::getFocusId ()
 
 XBMCAddon::xbmcgui::Window::removeControl (...)
 
 XBMCAddon::xbmcgui::Window::removeControls (...)
 
 XBMCAddon::xbmcgui::Window::getHeight ()
 
 XBMCAddon::xbmcgui::Window::getWidth ()
 
 XBMCAddon::xbmcgui::Window::getResolution ()
 
 XBMCAddon::xbmcgui::Window::setCoordinateResolution (...)
 
 XBMCAddon::xbmcgui::Window::setProperty (...)
 
 XBMCAddon::xbmcgui::Window::getProperty (...)
 
 XBMCAddon::xbmcgui::Window::clearProperty (...)
 
 XBMCAddon::xbmcgui::Window::clearProperties ()
 
 XBMCAddon::xbmcgui::Window::close ()
 
 XBMCAddon::xbmcgui::Window::doModal ()
 
 XBMCAddon::xbmcgui::Window::addControl (...)
 
 XBMCAddon::xbmcgui::Window::addControls (...)
 
 XBMCAddon::xbmcgui::Window::getControl (...)
 

Detailed Description

GUI window class for Add-Ons.

This class allows over their functions to create and edit windows that can be accessed from an Add-On.

Likewise, all functions from here as well in the other window classes WindowDialog, WindowXML and WindowXMLDialog with inserted and available.

Constructor for window

Class: xbmcgui.Window([existingWindowId]):

Creates a new from Add-On usable window class. This is to create window for related controls by system calls.

Parameters
existingWindowId[opt] Specify an id to use an existing window.
Exceptions
ValueErrorif supplied window Id does not exist.
Exceptionif more then 200 windows are created.

Deleting this window will activate the old window that was active and resets (not delete) all controls that are associated with this window.

Example:

..
win = xbmcgui.Window()
width = win.getWidth()
..

Function Documentation

◆ addControl()

void XBMCAddon::xbmcgui::Window::addControl (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> addControl(Control) </big></font></span></code></h4> \endhtmlonly

Add a Control to this window.

Parameters
ControlControl to add
Exceptions
TypeErrorIf supplied argument is not a Control type
ReferenceErrorIf control is already used in another window
RuntimeErrorShould not happen :-)

The next controls can be added to a window atm

Control-class Description
ControlLabel Label control to show text
ControlFadeLabel The fadelabel has multiple labels which it cycles through
ControlTextBox To show bigger text field
ControlButton Brings a button to do some actions
ControlEdit The edit control allows a user to input text in Kodi
ControlFadeLabel The fade label control is used for displaying multiple pieces of text in the same space in Kodi
ControlList Add a list for something like files
ControlGroup Is for a group which brings the others together
ControlImage Controls a image on skin
ControlRadioButton For a radio button which handle boolean values
ControlProgress Progress bar for a performed work or something else
ControlSlider The slider control is used for things where a sliding bar best represents the operation at hand
ControlSpin The spin control is used for when a list of options can be chosen
ControlTextBox The text box is used for showing a large multipage piece of text in Kodi

◆ addControls()

void XBMCAddon::xbmcgui::Window::addControls (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> addControls(List) </big></font></span></code></h4> \endhtmlonly

Add a list of Controls to this window.

Parameters
ListList with controls to add
Exceptions
TypeErrorIf supplied argument is not of List type, or a control is not of Control type
ReferenceErrorIf control is already used in another window
RuntimeErrorShould not happen :-)

◆ clearProperties()

void XBMCAddon::xbmcgui::Window::clearProperties ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> clearProperties() </big></font></span></code></h4> \endhtmlonly

Clears all window properties.

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
win.clearProperties()
..

◆ clearProperty()

void XBMCAddon::xbmcgui::Window::clearProperty (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> clearProperty(key) </big></font></span></code></h4> \endhtmlonly

Clears the specific window property.

Parameters
keystring - property name.
Note
Key is NOT case sensitive. Equivalent to setProperty(key,'') You can use the above as keywords for arguments and skip certain optional arguments. Once you use a keyword, all following arguments require the keyword.

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
win.clearProperty('Category')
..

◆ close()

void XBMCAddon::xbmcgui::Window::close ( void  )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> close() </big></font></span></code></h4> \endhtmlonly

Closes this window.

Closes this window by activating the old window.

Note
The window is not deleted with this method.

◆ doModal()

void XBMCAddon::xbmcgui::Window::doModal ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> doModal() </big></font></span></code></h4> \endhtmlonly

Display this window until close() is called.

Todo:
garbear added this code to the python window.cpp class and commented in XBPyThread.cpp. I'm not sure how to handle this in this native implementation.

◆ getControl()

Control * XBMCAddon::xbmcgui::Window::getControl (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getControl(controlId) </big></font></span></code></h4> \endhtmlonly

Gets the control from this window.

Parameters
controlIdControl id to get
Exceptions
ExceptionIf Control doesn't exist
Remarks
controlId doesn't have to be a python control, it can be a control id from a Kodi window too (you can find id's in the xml files.
Note
Not python controls are not completely usable yet You can only use the Control functions

◆ getFocus()

Control * XBMCAddon::xbmcgui::Window::getFocus ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getFocus(Control) </big></font></span></code></h4> \endhtmlonly

Returns the control which is focused.

Returns
Focused control class
Exceptions
SystemErrorOn Internal error
RuntimeErrorIf no control has focus

◆ getFocusId()

long XBMCAddon::xbmcgui::Window::getFocusId ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getFocusId(int) </big></font></span></code></h4> \endhtmlonly

Returns the id of the control which is focused.

Returns
Focused control id
Exceptions
SystemErrorOn Internal error
RuntimeErrorIf no control has focus

◆ getHeight()

long XBMCAddon::xbmcgui::Window::getHeight ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getHeight() </big></font></span></code></h4> \endhtmlonly

Returns the height of this Window instance.

Returns
Window height in pixels
v18 Python API changes:
Function changed

◆ getProperty()

String XBMCAddon::xbmcgui::Window::getProperty (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getProperty(key) </big></font></span></code></h4> \endhtmlonly

Returns a window property as a string, similar to an infolabel.

Parameters
keystring - property name.
Note
Key is NOT case sensitive.
You can use the above as keywords for arguments and skip certain optional arguments. Once you use a keyword, all following arguments require the keyword.

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
category = win.getProperty('Category')
..

◆ getResolution()

long XBMCAddon::xbmcgui::Window::getResolution ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getResolution() </big></font></span></code></h4> \endhtmlonly

Returns The resolution of the screen

Returns
Used Resolution The returned value is one of the following:
value Resolution
0 1080i (1920x1080)
1 720p (1280x720)
2 480p 4:3 (720x480)
3 480p 16:9 (720x480)
4 NTSC 4:3 (720x480)
5 NTSC 16:9 (720x480)
6 PAL 4:3 (720x576)
7 PAL 16:9 (720x576)
8 PAL60 4:3 (720x480)
9 PAL60 16:9 (720x480)
v18 Python API changes:
Deprecated.

◆ getWidth()

long XBMCAddon::xbmcgui::Window::getWidth ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getWidth() </big></font></span></code></h4> \endhtmlonly

Returns the width of this Window instance.

Returns
Window width in pixels
v18 Python API changes:
Function changed

◆ removeControl()

void XBMCAddon::xbmcgui::Window::removeControl (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> removeControl(Control) </big></font></span></code></h4> \endhtmlonly

Removes the control from this window.

Parameters
ControlControl class to remove
Exceptions
TypeErrorIf supplied argument is not a Control type
RuntimeErrorIf control is not added to this window

This will not delete the control. It is only removed from the window.

◆ removeControls()

void XBMCAddon::xbmcgui::Window::removeControls (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> removeControls(List) </big></font></span></code></h4> \endhtmlonly

Removes a list of controls from this window.

Parameters
ListList with controls to remove
Exceptions
TypeErrorIf supplied argument is not a Control type
RuntimeErrorIf control is not added to this window

This will not delete the controls. They are only removed from the window.

◆ setCoordinateResolution()

void XBMCAddon::xbmcgui::Window::setCoordinateResolution (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setCoordinateResolution(int resolution) </big></font></span></code></h4> \endhtmlonly

Sets the resolution

That the coordinates of all controls are defined in. Allows Kodi to scale control positions and width/heights to whatever resolution Kodi is currently using.

Parameters
resCoordinate resolution to set Resolution is one of the following:
value Resolution
0 1080i (1920x1080)
1 720p (1280x720)
2 480p 4:3 (720x480)
3 480p 16:9 (720x480)
4 NTSC 4:3 (720x480)
5 NTSC 16:9 (720x480)
6 PAL 4:3 (720x576)
7 PAL 16:9 (720x576)
8 PAL60 4:3 (720x480)
9 PAL60 16:9 (720x480)

Example:

@code{py}

.. win = xbmcgui.Window(xbmcgui.getCurrentWindowId()) win.setCoordinateResolution(0) ..

v18 Python API changes:
Deprecated.

◆ setFocus()

void XBMCAddon::xbmcgui::Window::setFocus (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setFocus(Control) </big></font></span></code></h4> \endhtmlonly

Give the supplied control focus.

Parameters
ControlControl class to focus
Exceptions
TypeErrorIf supplied argument is not a Control type
SystemErrorOn Internal error
RuntimeErrorIf control is not added to a window

◆ setFocusId()

void XBMCAddon::xbmcgui::Window::setFocusId (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setFocusId(ControlId) </big></font></span></code></h4> \endhtmlonly

Gives the control with the supplied focus.

Parameters
ControlId[integer] On skin defined id of control
Exceptions
SystemErrorOn Internal error
RuntimeErrorIf control is not added to a window

◆ setProperty()

void XBMCAddon::xbmcgui::Window::setProperty (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setProperty(key, value) </big></font></span></code></h4> \endhtmlonly

Sets a window property, similar to an infolabel.

Parameters
keystring - property name.
valuestring or unicode - value of property.
Note
Key is NOT case sensitive. Setting value to an empty string is equivalent to clearProperty(key).
You can use the above as keywords for arguments and skip certain optional arguments.
Once you use a keyword, all following arguments require the keyword.

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
win.setProperty('Category', 'Newest')
..

◆ show()

void XBMCAddon::xbmcgui::Window::show ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> show() </big></font></span></code></h4> \endhtmlonly

Show this window.

Shows this window by activating it, calling close() after it wil activate the current window again.

Note
If your script ends this window will be closed to. To show it forever, make a loop at the end of your script or use doModal() instead.