xbmcgui¶

GUI functions on Kodi.

Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.

Functions

`getCurrentWindowDialogId`()	Returns the id for the current 'active' dialog as an integer.
`getCurrentWindowId`()	Returns the id for the current 'active' window as an integer.
`getScreenHeight`()	Returns the height of this screen.
`getScreenWidth`()	Returns the width of this screen.

Classes

`Action`()	`Action` class.
`Control`()	Code based skin access.
`ControlButton`(x, y, width, height, label[, ...])	A standard push button control.
`ControlEdit`(x, y, width, height, label[, ...])	Used as an input control for the osd keyboard and other input fields.
`ControlFadeLabel`(x, y, width, height[, ...])	Used to show multiple pieces of text in the same position, by fading from one to the other.
`ControlGroup`(x, y, width, height)	Used to group controls together.
`ControlImage`(x, y, width, height, filename)	Used to show an image.
`ControlLabel`(x, y, width, height, label[, ...])	Used to show some lines of text.
`ControlList`(x, y, width, height[, font, ...])	**Used for a scrolling lists of items.
`ControlProgress`(x, y, width, height[, ...])	Used to show the progress of a particular operation.
`ControlRadioButton`(x, y, width, height, label)	A radio button control (as used for on/off settings).
`ControlSlider`(x, y, width, height[, ...])	Used for a volume slider.
`ControlSpin`()	Used for cycling up/down controls.
`ControlTextBox`(x, y, width, height[, font, ...])	Used to show a multi-page piece of text.
`Dialog`()	Kodi's dialog class
`DialogProgress`()	Kodi's progress dialog class (Duh!)
`DialogProgressBG`()	Kodi's background progress dialog class
`ListItem`([label, label2, path, offscreen])	Selectable window list item.
`Window`([existingWindowId])	GUI window class for Add-Ons.
`WindowDialog`()	GUI window dialog class for Add-Ons.
`WindowXML`(xmlFilename, scriptPath[, ...])	GUI xml window class.
`WindowXMLDialog`(xmlFilename, scriptPath[, ...])	GUI xml window dialog

class xbmcgui.Control[source]¶

Bases: object

Code based skin access.

Offers classes and functions that manipulate the add-on gui controls.

Code based skin access.

Kodi is noted as having a very flexible and robust framework for its GUI, making theme-skinning and personal customization very accessible. Users can create their own skin (or modify an existing skin) and share it with others.

Kodi includes a new GUI library written from scratch. This library allows you to skin/change everything you see in Kodi, from the images, the sizes and positions of all controls, colours, fonts, and text, through to altering navigation and even adding new functionality. The skin system is quite complex, and this portion of the manual is dedicated to providing in depth information on how it all works, along with tips to make the experience a little more pleasant.

getId() → int[source]¶

Returns the control’s current id as an integer.

Returns:: int - Current id

Example:

...
id = self.button.getId()
...

getX() → int[source]¶

Returns the control’s current X position.

Returns:: int - Current X position

Example:

...
posX = self.button.getX()
...

getY() → int[source]¶

Returns the control’s current Y position.

Returns:: int - Current Y position

Example:

...
posY = self.button.getY()
...

getHeight() → int[source]¶

Returns the control’s current height as an integer.

Returns:: int - Current height

Example:

...
height = self.button.getHeight()
...

getWidth() → int[source]¶

Returns the control’s current width as an integer.

Returns:: int - Current width

Example:

...
width = self.button.getWidth()
...

setEnabled(enabled: bool) → None[source]¶

Sets the control’s enabled/disabled state.

Parameters:: enabled – bool - True=enabled / False=disabled.

Example:

...
self.button.setEnabled(False)
...

setVisible(visible: bool) → None[source]¶

Sets the control’s visible/hidden state.

Parameters:: visible – bool - True=visible / False=hidden.

@python_v19 You can now define the visible state of a control before it being added to a window. This value will be taken into account when the control is later added.

Example:

...
self.button.setVisible(False)
...

isVisible() → bool[source]¶

Get the control’s visible/hidden state with respect to the container/window

Note

If a given control is set visible (c.f.`setVisible()` but was not yet added to a window, this method will return False (the control is not visible yet since it was not added to the window).

@python_v18 New function added.

Example:

...
if self.button.isVisible():
...

setVisibleCondition(visible: str, allowHiddenFocus: bool = False) → None[source]¶

Sets the control’s visible condition.

Allows Kodi to control the visible status of the control.

List of Conditions: https://kodi.wiki/view/List_of_boolean_conditions

Parameters:

visible – string - Visible condition
allowHiddenFocus – [opt] bool - True = gains focus even if hidden

Example:

...
# setVisibleCondition(visible[,allowHiddenFocus])
self.button.setVisibleCondition('[Control.IsVisible(41) + !Control.IsVisible(12)]', True)
...

setEnableCondition(enable: str) → None[source]¶

Sets the control’s enabled condition.

Allows Kodi to control the enabled status of the control.

List of Conditions

Parameters:: enable – string - Enable condition.

Example:

...
# setEnableCondition(enable)
self.button.setEnableCondition('System.InternetState')
...

setAnimations(eventAttr: List[Tuple[str, str]]) → None[source]¶

Sets the control’s animations.

[(event,attr,)*]: list - A list of tuples consisting of event and attributes pairs.

Animating your skin

Parameters:

event – string - The event to animate.
attr – string - The whole attribute string separated by spaces.

Example:

...
# setAnimations([(event, attr,)*])
self.button.setAnimations([('focus', 'effect=zoom end=90,247,220,56 time=0',)])
...

setPosition(x: int, y: int) → None[source]¶

Sets the controls position.

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.

Note

You may use negative integers. (e.g sliding a control into view)

Example:

...
self.button.setPosition(100, 250)
...

setWidth(width: int) → None[source]¶

Sets the controls width.

Parameters:: width – integer - width of control.

Example:

...
self.image.setWidth(100)
...

setHeight(height: int) → None[source]¶

Sets the controls height.

Parameters:: height – integer - height of control.

Example:

...
self.image.setHeight(100)
...

setNavigation(up: Control, down: Control, left: Control, right: Control) → None[source]¶

Sets the controls navigation.

Parameters:

up – control object - control to navigate to on up.
down – control object - control to navigate to on down.
left – control object - control to navigate to on left.
right – control object - control to navigate to on right.

Raises:

TypeError – if one of the supplied arguments is not a control type.
ReferenceError – if one of the controls is not added to a window.

Note

Same as controlUp(),`controlDown()`,`controlLeft()`,`controlRight()`. Set to self to disable navigation for that direction.

Example:

...
self.button.setNavigation(self.button1, self.button2, self.button3, self.button4)
...

controlUp(up: Control) → None[source]¶

Sets the controls up navigation.

Parameters:

control – control object - control to navigate to on up.

Raises:

TypeError – if one of the supplied arguments is not a control type.
ReferenceError – if one of the controls is not added to a window.

Note

You can also use setNavigation(). Set to self to disable navigation.

Example:

...
self.button.controlUp(self.button1)
...

controlDown(control: Control) → None[source]¶

Sets the controls down navigation.

Parameters:

control – control object - control to navigate to on down.

Raises:

TypeError – if one of the supplied arguments is not a control type.
ReferenceError – if one of the controls is not added to a window.

Note

You can also use setNavigation(). Set to self to disable navigation.

Example:

...
self.button.controlDown(self.button1)
...

controlLeft(control: Control) → None[source]¶

Sets the controls left navigation.

Parameters:

control – control object - control to navigate to on left.

Raises:

TypeError – if one of the supplied arguments is not a control type.
ReferenceError – if one of the controls is not added to a window.

Note

You can also use setNavigation(). Set to self to disable navigation.

Example:

...
self.button.controlLeft(self.button1)
...

controlRight(control: Control) → None[source]¶

Sets the controls right navigation.

Parameters:

control – control object - control to navigate to on right.

Raises:

TypeError – if one of the supplied arguments is not a control type.
ReferenceError – if one of the controls is not added to a window.

Note

You can also use setNavigation(). Set to self to disable navigation.

Example:

...
self.button.controlRight(self.button1)
...

class xbmcgui.ControlSpin[source]¶

Bases: Control

Used for cycling up/down controls.

Offers classes and functions that manipulate the add-on gui controls.

Code based skin access.

The spin control is used for when a list of options can be chosen (such as a page up/down control). You can choose the position, size, and look of the spin control.

Note

This class include also all calls from Control

Not working yet. You can’t create this object, it is returned by objects like ControlTextBox and ControlList.

setTextures(up: str, down: str, upFocus: str, downFocus: str, upDisabled: str, downDisabled: str) → None[source]¶

Sets textures for this control.

Texture are image files that are used for example in the skin

Not working yet.

Parameters:

up – label - for the up arrow when it doesn’t have focus.
down – label - for the down button when it is not focused.
upFocus – label - for the up button when it has focus.
downFocus – label - for the down button when it has focus.
upDisabled – label - for the up arrow when the button is disabled.
downDisabled – label - for the up arrow when the button is disabled.

Example:

...
# setTextures(up, down, upFocus, downFocus, upDisabled, downDisabled)

...

class xbmcgui.ControlLabel(x: int, y: int, width: int, height: int, label: str, font: str | None = None, textColor: str | None = None, disabledColor: str | None = None, alignment: int = 0, hasPath: bool = False, angle: int = 0)[source]¶

Bases: Control

Used to show some lines of text.

The label control is used for displaying text in Kodi. You can choose the font, size, colour, location and contents of the text to be displayed.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
label – string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled label’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled label’s label. (e.g. ‘0xFFFF3300’)
alignment – [opt] integer - alignment of label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Parameters:

hasPath – [opt] bool - True=stores a path / False=no path
angle – [opt] integer - angle of control. (+ rotates CCW, - rotates C)

Example:

...
# ControlLabel(x, y, width, height, label[, font, textColor,
#              disabledColor, alignment, hasPath, angle])
self.label = xbmcgui.ControlLabel(100, 250, 125, 75, 'Status', angle=45)
...

getLabel() → str[source]¶

Returns the text value for this label.

Returns:: This label

Example:

...
label = self.label.getLabel()
...

Sets text for this label.

Parameters:

label – string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled label’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled label’s label. (e.g. ‘0xFFFF3300’)
shadowColor – [opt] hexstring - color of button’s label’s shadow. (e.g. ‘0xFF000000’)
focusedColor – [opt] hexstring - color of focused button’s label. (e.g. ‘0xFF00FFFF’)
label2 – [opt] string or unicode - text string.

Example:

...
self.label.setLabel('Status')
...

class xbmcgui.ControlEdit(x: int, y: int, width: int, height: int, label: str, font: str | None = None, textColor: str | None = None, disabledColor: str | None = None, _alignment: int = 0, focusTexture: str | None = None, noFocusTexture: str | None = None)[source]¶

Bases: Control

Used as an input control for the osd keyboard and other input fields.

The edit control allows a user to input text in Kodi. You can choose the font, size, colour, location and header of the text to be displayed.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
label – string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled label’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled label’s label. (e.g. ‘0xFFFF3300’)
alignment – [opt] integer - alignment of label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Parameters:

focusTexture – [opt] string - filename for focus texture.
noFocusTexture – [opt] string - filename for no focus texture.

Note

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. After you create the control, you need to add it to the window with addControl().

@python_v18 Deprecated isPassword

@python_v19 Removed isPassword

Example:

...
self.edit = xbmcgui.ControlEdit(100, 250, 125, 75, 'Status')
...

Sets text heading for this edit control.

Parameters:

label – string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled label’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled label’s label. (e.g. ‘0xFFFF3300’)
shadowColor – [opt] hexstring - color of button’s label’s shadow. (e.g. ‘0xFF000000’)
focusedColor – [opt] hexstring - color of focused button’s label. (e.g. ‘0xFF00FFFF’)
label2 – [opt] string or unicode - text string.

Example:

...
self.edit.setLabel('Status')
...

getLabel() → str[source]¶

Returns the text heading for this edit control.

Returns:: Heading text

Example:

...
label = self.edit.getLabel()
...

setText(text: str) → None[source]¶

Sets text value for this edit control.

Parameters:: value – string or unicode - text string.

Example:

...
self.edit.setText('online')
...

getText() → str[source]¶

Returns the text value for this edit control.

Returns:: Text value of control

@python_v14 New function added.

Example:

...
value = self.edit.getText()
...

setType(type: int, heading: str) → None[source]¶

Sets the type of this edit control.

Parameters:: type – integer - type of the edit control.

Param	Definition
xbmcgui.INPUT_TYPE_TEXT	(standard keyboard)
xbmcgui.INPUT_TYPE_NUMBER	(format: #)
xbmcgui.INPUT_TYPE_DATE	(format: DD/MM/YYYY)
xbmcgui.INPUT_TYPE_TIME	(format: HH:MM)
xbmcgui.INPUT_TYPE_IPADDRESS	(format: #.#.#.#)
xbmcgui.INPUT_TYPE_PASSWORD	(input is masked)
xbmcgui.INPUT_TYPE_PASSWORD_MD5	(input is masked, return md5 hash of input)
xbmcgui.INPUT_TYPE_SECONDS	(format: SS or MM:SS or HH:MM:SS or MM min)
xbmcgui.INPUT_TYPE_PASSWORD_NUMBER_VERIFY_NEW	(numeric input is masked)

Parameters:: heading – string or unicode - heading that will be used for to numeric or keyboard dialog when the edit control is clicked.

@python_v18 New function added.

@python_v19 New option added to mask numeric input.

Example:

...
self.edit.setType(xbmcgui.INPUT_TYPE_TIME, 'Please enter the time')
...

class xbmcgui.ControlList(x: int, y: int, width: int, height: int, font: str | None = None, textColor: str | None = None, buttonTexture: str | None = None, buttonFocusTexture: str | None = None, selectedColor: str | None = None, _imageWidth: int = 10, _imageHeight: int = 10, _itemTextXOffset: int = 10, _itemTextYOffset: int = 2, _itemHeight: int = 27, _space: int = 2, _alignmentY: int = 4)[source]¶

Bases: Control

Used for a scrolling lists of items. Replaces the list control.

The list container is one of several containers used to display items from file lists in various ways. The list container is very flexible - it’s only restriction is that it is a list - i.e. a single column or row of items. The layout of the items is very flexible and is up to the skinner.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
font – [opt] string - font used for items label. (e.g. ‘font13’)
textColor – [opt] hexstring - color of items label. (e.g. ‘0xFFFFFFFF’)
buttonTexture – [opt] string - filename for focus texture.
buttonFocusTexture – [opt] string - filename for no focus texture.
selectedColor – [opt] integer - x offset of label.
imageWidth – [opt] integer - width of items icon or thumbnail.
imageHeight – [opt] integer - height of items icon or thumbnail.
itemTextXOffset – [opt] integer - x offset of items label.
itemTextYOffset – [opt] integer - y offset of items label.
itemHeight – [opt] integer - height of items.
space – [opt] integer - space between items.
alignmentY – [opt] integer - Y-axis alignment of items label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Parameters:: shadowColor – [opt] hexstring - color of items label’s shadow. (e.g. ‘0xFF000000’)

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
self.cList = xbmcgui.ControlList(100, 250, 200, 250, 'font14', space=5)
...

addItem(item: str | ListItem, sendMessage: bool = True) → None[source]¶

Add a new item to this list control.

Parameters:: item – string, unicode or ListItem - item to add.

Example:

...
cList.addItem('Reboot Kodi')
...

addItems(items: List[str | ListItem]) → None[source]¶

Adds a list of listitems or strings to this list control.

Parameters:: items – List - list of strings, unicode objects or ListItems to add.

Note

You can use the above as keywords for arguments.

Large lists benefit considerably, than using the standard addItem()

Example:

...
cList.addItems(items=listitems)
...

selectItem(item: int) → None[source]¶

Select an item by index number.

Parameters:: item – integer - index number of the item to select.

Example:

...
cList.selectItem(12)
...

removeItem(index: int) → None[source]¶

Remove an item by index number.

Parameters:: index – integer - index number of the item to remove.

@python_v13 New function added.

Example:

...
cList.removeItem(12)
...

reset() → None[source]¶

Clear all ListItems in this control list.

Calling```reset()``` will destroy any```ListItem``` objects in the```ControlList``` if not hold by any other class. Make sure you you don’t call```addItems()``` with the previous```ListItem``` references after calling```reset()```. If you need to preserve the```ListItem``` objects after```reset()``` make sure you store them as members of your```WindowXML``` class (see examples).

Examples:

...
cList.reset()
...

The below example shows you how you can reset the```ControlList``` but this time avoiding```ListItem``` object destruction. The example assumes self as a```WindowXMLDialog``` instance containing a```ControlList``` with id = 800. The class preserves the```ListItem``` objects in a class member variable.

::: … # Get all the ListItem objects in the control self.list_control = self.getControl(800) # ControlList object self.listitems = [self.list_control.getListItem(item) for item in range(0, self.list_control.size())] # Reset the ControlList control self.list_control.reset() # # do something with your ListItem objects here (e.g. sorting.) # … # # Add them again to the ControlList self.list_control.addItems(self.listitems) …

getSpinControl() → Control[source]¶

Returns the associated ControlSpin object.

Not working completely yet After adding this control list to a window it is not possible to change the settings of this spin control.

Example:

...
ctl = cList.getSpinControl()
...

getSelectedPosition() → int[source]¶

Returns the position of the selected item as an integer.

Note

Returns -1 for empty lists.

Example:

...
pos = cList.getSelectedPosition()
...

getSelectedItem() → ListItem[source]¶

Returns the selected item as a ListItem object.

Returns:: The selected item

Note

Same as getSelectedPosition(), but instead of an integer a ListItem object is returned. Returns None for empty lists. See windowexample.py on how to use this.

Example:

...
item = cList.getSelectedItem()
...

setImageDimensions(imageWidth: int, imageHeight: int) → None[source]¶

Sets the width/height of items icon or thumbnail.

Parameters:

imageWidth – [opt] integer - width of items icon or thumbnail.
imageHeight – [opt] integer - height of items icon or thumbnail.

Example:

...
cList.setImageDimensions(18, 18)
...

setSpace(space: int) → None[source]¶

Sets the space between items.

Parameters:: space – [opt] integer - space between items.

Example:

...
cList.setSpace(5)
...

setPageControlVisible(visible: bool) → None[source]¶

Sets the spin control’s visible/hidden state.

Parameters:: visible – boolean - True=visible / False=hidden.

Example:

...
cList.setPageControlVisible(True)
...

size() → int[source]¶

Returns the total number of items in this list control as an integer.

Returns:: Total number of items

Example:

...
cnt = cList.size()
...

getItemHeight() → int[source]¶

Returns the control’s current item height as an integer.

Returns:: Current item heigh

Example:

..
item_height = self.cList.getItemHeight()
...

getSpace() → int[source]¶

Returns the control’s space between items as an integer.

Returns:: Space between items

Example:

...
gap = self.cList.getSpace()
...

getListItem(index: int) → ListItem[source]¶

Returns a given ListItem in this List.

Parameters:: index – integer - index number of item to return.
Returns:: List item
Raises:: ValueError – if index is out of range.

Example:

...
listitem = cList.getListItem(6)
...

setStaticContent(items: List[ListItem]) → None[source]¶

Fills a static list with a list of listitems.

Parameters:: items – List - list of listitems to add.

Note

You can use the above as keywords for arguments.

Example:

...
cList.setStaticContent(items=listitems)
...

class xbmcgui.ControlFadeLabel(x: int, y: int, width: int, height: int, font: str | None = None, textColor: str | None = None, _alignment: int = 0)[source]¶

Bases: Control

Used to show multiple pieces of text in the same position, by fading from one to the other.

The fade label control is used for displaying multiple pieces of text in the same space in Kodi. You can choose the font, size, colour, location and contents of the text to be displayed. The first piece of information to display fades in over 50 frames, then scrolls off to the left. Once it is finished scrolling off screen, the second piece of information fades in and the process repeats. A fade label control is not supported in a list container.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of fadelabel’s labels. (e.g. ‘0xFFFFFFFF’)
alignment – [opt] integer - alignment of label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
self.fadelabel = xbmcgui.ControlFadeLabel(100, 250, 200, 50, textColor='0xFFFFFFFF')
...

addLabel(label: str) → None[source]¶

Add a label to this control for scrolling.

Parameters:: label – string or unicode - text string to add.

Note

To remove added text use```reset()``` for them.

Example:

...
self.fadelabel.addLabel('This is a line of text that can scroll.')
...

setScrolling(scroll: bool) → None[source]¶

Set scrolling. If set to false, the labels won’t scroll. Defaults to true.

Parameters:: scroll – boolean - True = enabled / False = disabled

Example:

...
self.fadelabel.setScrolling(False)
...

class xbmcgui.ControlTextBox(x: int, y: int, width: int, height: int, font: str | None = None, textColor: str | None = None)[source]¶

Bases: Control

Used to show a multi-page piece of text.

The text box is used for showing a large multipage piece of text in Kodi. You can choose the position, size, and look of the text.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
font – [opt] string - font used for text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of textbox’s text. (e.g. ‘0xFFFFFFFF’)

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
# ControlTextBox(x, y, width, height[, font, textColor])
self.textbox = xbmcgui.ControlTextBox(100, 250, 300, 300, textColor='0xFFFFFFFF')
...

As stated above, the GUI control is only created once added to a window. The example below shows how a ControlTextBox can be created, added to the current window and have some of its properties changed.

Extended example:

...
textbox = xbmcgui.ControlTextBox(100, 250, 300, 300, textColor='0xFFFFFFFF')
window = xbmcgui.Window(xbmcgui.getCurrentWindowId())
window.addControl(textbox)
textbox.setText("My Text Box")
textbox.scroll()
...

setText(text: str) → None[source]¶

Sets the text for this textbox.

Parameters:: text – string - text string.

@python_v19 setText can now be used before adding the control to the window (the defined value is taken into consideration when the control is created)

Example:

...
# setText(text)
self.textbox.setText('This is a line of text that can wrap.')
...

getText() → str[source]¶

Returns the text value for this textbox.

Returns:: To get text from box

@python_v19 getText() can now be used before adding the control to the window

Example:

...
# getText()
text = self.text.getText()
...

reset() → None[source]¶

Clear’s this textbox.

@python_v19 reset() will reset any text defined for this control even before you add the control to the window

Example:

...
# reset()
self.textbox.reset()
...

scroll(id: int) → None[source]¶

Scrolls to the given position.

Parameters:: id – integer - position to scroll to.

Note

scroll() only works after the control is added to a window.

Example:

...
# scroll(position)
self.textbox.scroll(10)
...

autoScroll(delay: int, time: int, repeat: int) → None[source]¶

Set autoscrolling times.

Parameters:

delay – integer - Scroll delay (in ms)
time – integer - Scroll time (in ms)
repeat – integer - Repeat time

Note

autoScroll only works after you add the control to a window.

@python_v15 New function added.

Example:

...
self.textbox.autoScroll(1, 2, 1)
...

class xbmcgui.ControlImage(x: int, y: int, width: int, height: int, filename: str, aspectRatio: int = 0, colorDiffuse: str | None = None)[source]¶

Bases: Control

Used to show an image.

The image control is used for displaying images in Kodi. You can choose the position, size, transparency and contents of the image to be displayed.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
filename – string - image filename.
aspectRatio – [opt] integer - (values 0 = stretch (default), 1 = scale up (crops), 2 = scale down (black bar)
colorDiffuse – hexString - (example, ‘0xC0FF0000’ (red tint))

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
# ControlImage(x, y, width, height, filename[, aspectRatio, colorDiffuse])
self.image = xbmcgui.ControlImage(100, 250, 125, 75, aspectRatio=2)
...

setImage(imageFilename: str, useCache: bool = True) → None[source]¶

Changes the image.

Parameters:

filename – string - image filename.
useCache – [opt] bool - True=use cache (default) / False=don’t use cache.

@python_v13 Added new option useCache.

Example:

...
# setImage(filename[, useCache])
self.image.setImage('special://home/scripts/test.png')
self.image.setImage('special://home/scripts/test.png', False)
...

setColorDiffuse(hexString: str) → None[source]¶

Changes the images color.

Parameters:: colorDiffuse – hexString - (example, ‘0xC0FF0000’ (red tint))

Example:

...
# setColorDiffuse(colorDiffuse)
self.image.setColorDiffuse('0xC0FF0000')
...

class xbmcgui.ControlProgress(x: int, y: int, width: int, height: int, texturebg: str | None = None, textureleft: str | None = None, texturemid: str | None = None, textureright: str | None = None, textureoverlay: str | None = None)[source]¶

Bases: Control

Used to show the progress of a particular operation.

The progress control is used to show the progress of an item that may take a long time, or to show how far through a movie you are. You can choose the position, size, and look of the progress control.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
filename – string - image filename.
texturebg – [opt] string - specifies the image file whichshould be displayed in the background of the progress control.
textureleft – [opt] string - specifies the image file whichshould be displayed for the left side of the progress bar. This is rendered on the left side of the bar.
texturemid – [opt] string - specifies the image file which should be displayed for the middl portion of the progress bar. This is the fill texture used to fill up the bar. It’s positioned on the right of the``<lefttexture>`` texture, and fills the gap between the``<lefttexture>`` and``<righttexture>`` textures, depending on how far progressed the item is.
textureright – [opt] string - specifies the image file which should be displayed for the right side of the progress bar. This is rendered on the right side of the bar.
textureoverlay – [opt] string - specifies the image file which should be displayed over the top of all other images in the progress bar. It is centered vertically and horizontally within the space taken up by the background image.

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
# ControlProgress(x, y, width, height, filename[, texturebg, textureleft, texturemid, textureright, textureoverlay])
self.image = xbmcgui.ControlProgress(100, 250, 250, 30, 'special://home/scripts/test.png')
...

setPercent(pct: float) → None[source]¶

Sets the percentage of the progressbar to show.

Parameters:: percent – float - percentage of the bar to show.

Note

valid range for percent is 0-100

Example:

...
# setPercent(percent)
self.progress.setPercent(60)
...

getPercent() → float[source]¶

Returns a float of the percent of the progress.

Returns:: Percent position

Example:

...
# getPercent()
print(self.progress.getPercent())
...

class xbmcgui.ControlButton(x: int, y: int, width: int, height: int, label: str, focusTexture: str | None = None, noFocusTexture: str | None = None, textOffsetX: int = 10, textOffsetY: int = 2, alignment: int = 4, font: str | None = None, textColor: str | None = None, disabledColor: str | None = None, angle: int = 0, shadowColor: str | None = None, focusedColor: str | None = None)[source]¶

Bases: Control

A standard push button control.

The button control is used for creating push buttons in Kodi. You can choose the position, size, and look of the button, as well as choosing what action(s) should be performed when pushed.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
label – string or unicode - text string.
focusTexture – [opt] string - filename for focus texture.
noFocusTexture – [opt] string - filename for no focus texture.
textOffsetX – [opt] integer - x offset of label.
textOffsetY – [opt] integer - y offset of label.
alignment – [opt] integer - alignment of label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Parameters:

font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled button’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled button’s label. (e.g. ‘0xFFFF3300’)
angle – [opt] integer - angle of control. (+ rotates CCW, - rotates CW)
shadowColor – [opt] hexstring - color of button’s label’s shadow. (e.g. ‘0xFF000000’)
focusedColor – [opt] hexstring - color of focused button’s label. (e.g. ‘0xFF00FFFF’)

Note

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. After you create the control, you need to add it to the window with addControl().

Example:

...
# ControlButton(x, y, width, height, label[, focusTexture, noFocusTexture, textOffsetX, textOffsetY,
#               alignment, font, textColor, disabledColor, angle, shadowColor, focusedColor])
self.button = xbmcgui.ControlButton(100, 250, 200, 50, 'Status', font='font14')
...

Sets this buttons text attributes.

Parameters:

label – [opt] string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled button’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled button’s label. (e.g. ‘0xFFFF3300’)
shadowColor – [opt] hexstring - color of button’s label’s shadow. (e.g. ‘0xFF000000’)
focusedColor – [opt] hexstring - color of focused button’s label. (e.g. ‘0xFFFFFF00’)
label2 – [opt] string or unicode - text string.

Note

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:

...
# setLabel([label, font, textColor, disabledColor, shadowColor, focusedColor])
self.button.setLabel('Status', 'font14', '0xFFFFFFFF', '0xFFFF3300', '0xFF000000')
...

setDisabledColor(color: str) → None[source]¶

Sets this buttons disabled color.

Parameters:: disabledColor – hexstring - color of disabled button’s label. (e.g. ‘0xFFFF3300’)

Example:

...
# setDisabledColor(disabledColor)
self.button.setDisabledColor('0xFFFF3300')
...

getLabel() → str[source]¶

Returns the buttons label as a unicode string.

Returns:: Unicode string

Example:

...
# getLabel()
label = self.button.getLabel()
...

getLabel2() → str[source]¶

Returns the buttons label2 as a string.

Returns:: string of label 2

Example:

...
# getLabel2()
label = self.button.getLabel2()
...

class xbmcgui.ControlGroup(x: int, y: int, width: int, height: int)[source]¶

Bases: Control

Used to group controls together.

The group control is one of the most important controls. It allows you to group controls together, applying attributes to all of them at once. It also remembers the last navigated button in the group, so you can set the <onup> of a control to a group of controls to have it always go back to the one you were at before. It also allows you to position controls more accurately relative to each other, as any controls within a group take their coordinates from the group’s top left corner (or from elsewhere if you use the r attribute). You can have as many groups as you like within the skin, and groups within groups are handled with no issues.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.

Example:

...
self.group = xbmcgui.ControlGroup(100, 250, 125, 75)
...

class xbmcgui.ControlRadioButton(x: int, y: int, width: int, height: int, label: str, focusOnTexture: str | None = None, noFocusOnTexture: str | None = None, focusOffTexture: str | None = None, noFocusOffTexture: str | None = None, focusTexture: str | None = None, noFocusTexture: str | None = None, textOffsetX: int = 10, textOffsetY: int = 2, _alignment: int = 4, font: str | None = None, textColor: str | None = None, disabledColor: str | None = None, angle: int = 0, shadowColor: str | None = None, focusedColor: str | None = None, disabledOnTexture: str | None = None, disabledOffTexture: str | None = None)[source]¶

Bases: Control

A radio button control (as used for on/off settings).

The radio button control is used for creating push button on/off settings in Kodi. You can choose the position, size, and look of the button, as well as the focused and unfocused radio textures. Used for settings controls.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control.
y – integer - y coordinate of control.
width – integer - width of control.
height – integer - height of control.
label – string or unicode - text string.
focusOnTexture – [opt] string - filename for radio ON focused texture.
noFocusOnTexture – [opt] string - filename for radio ON not focused texture.
focusOfTexture – [opt] string - filename for radio OFF focused texture.
noFocusOffTexture – [opt] string - filename for radio OFF not focused texture.
focusTexture – [opt] string - filename for focused button texture.
noFocusTexture – [opt] string - filename for not focused button texture.
textOffsetX – [opt] integer - horizontal text offset
textOffsetY – [opt] integer - vertical text offset
alignment – [opt] integer - alignment of label Flags for alignment used as bits to have several together:

Definition name	Bitflag	Description
XBFONT_LEFT	0x00000000	Align X left
XBFONT_RIGHT	0x00000001	Align X right
XBFONT_CENTER_X	0x00000002	Align X center
XBFONT_CENTER_Y	0x00000004	Align Y center
XBFONT_TRUNCATED	0x00000008	Truncated text
XBFONT_JUSTIFIED	0x00000010	Justify text

Parameters:

font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of label when control is enabled. radiobutton’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of label when control is disabled. (e.g. ‘0xFFFF3300’)

Note

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. After you create the control, you need to add it to the window with addControl().

@python_v13 New function added.

Example:

...
self.radiobutton = xbmcgui.ControlRadioButton(100, 250, 200, 50, 'Enable', font='font14')
...

setSelected(selected: bool) → None[source]¶

Sets the radio buttons’s selected status.

Parameters:: selected – bool - True=selected (on) / False=not selected (off)

Note

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:

...
self.radiobutton.setSelected(True)
...

isSelected() → bool[source]¶

Returns the radio buttons’s selected status.

Returns:: True if selected on

Example:

...
is = self.radiobutton.isSelected()
...

Sets the radio buttons text attributes.

Parameters:

label – string or unicode - text string.
font – [opt] string - font used for label text. (e.g. ‘font13’)
textColor – [opt] hexstring - color of enabled radio button’s label. (e.g. ‘0xFFFFFFFF’)
disabledColor – [opt] hexstring - color of disabled radio button’s label. (e.g. ‘0xFFFF3300’)
shadowColor – [opt] hexstring - color of radio button’s label’s shadow. (e.g. ‘0xFF000000’)
focusedColor – [opt] hexstring - color of focused radio button’s label. (e.g. ‘0xFFFFFF00’)

Note

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:

...
# setLabel(label[, font, textColor, disabledColor, shadowColor, focusedColor])
self.radiobutton.setLabel('Status', 'font14', '0xFFFFFFFF', '0xFFFF3300', '0xFF000000')
...

setRadioDimension(x: int, y: int, width: int, height: int) → None[source]¶

Sets the radio buttons’s radio texture’s position and size.

Parameters:

x – integer - x coordinate of radio texture.
y – integer - y coordinate of radio texture.
width – integer - width of radio texture.
height – integer - height of radio texture.

Note

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:

...
self.radiobutton.setRadioDimension(x=100, y=5, width=20, height=20)
...

class xbmcgui.ControlSlider(x: int, y: int, width: int, height: int, textureback: str | None = None, texture: str | None = None, texturefocus: str | None = None, orientation: int = 1, texturebackdisabled: str | None = None, texturedisabled: str | None = None)[source]¶

Bases: Control

Used for a volume slider.

The slider control is used for things where a sliding bar best represents the operation at hand (such as a volume control or seek control). You can choose the position, size, and look of the slider control.

Note

This class include also all calls from Control

Parameters:

x – integer - x coordinate of control
y – integer - y coordinate of control
width – integer - width of control
height – integer - height of control
textureback – [opt] string - image filename
texture – [opt] string - image filename
texturefocus – [opt] string - image filename
orientation – [opt] integer - orientation of slider (xbmcgui.HORIZONTAL / xbmcgui.VERTICAL (default))

Note

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. After you create the control, you need to add it to the window with addControl().

@python_v17 orientation option added.

Example:

...
self.slider = xbmcgui.ControlSlider(100, 250, 350, 40)
...

getPercent() → float[source]¶

Returns a float of the percent of the slider.

Returns:: float - Percent of slider

Example:

...
print(self.slider.getPercent())
...

setPercent(pct: float) → None[source]¶

Sets the percent of the slider.

Parameters:: pct – float - Percent value of slider

Example:

...
self.slider.setPercent(50)
...

getInt() → int[source]¶

Returns the value of the slider.

Returns:: int - value of slider

@python_v18 New function added.

Example:

...
print(self.slider.getInt())
...

setInt(value: int, min: int, delta: int, max: int) → None[source]¶

Sets the range, value and step size of the slider.

Parameters:

value – int - value of slider
min – int - min of slider
delta – int - step size of slider
max – int - max of slider

@python_v18 New function added.

Example:

...
self.slider.setInt(450, 200, 10, 900)
...

getFloat() → float[source]¶

Returns the value of the slider.

Returns:: float - value of slider

@python_v18 New function added.

Example:

...
print(self.slider.getFloat())
...

setFloat(value: float, min: float, delta: float, max: float) → None[source]¶

Sets the range, value and step size of the slider.

Parameters:

value – float - value of slider
min – float - min of slider
delta – float - step size of slider
max – float - max of slider

@python_v18 New function added.

Example:

...
self.slider.setFloat(15.0, 10.0, 1.0, 20.0)
...

class xbmcgui.Dialog[source]¶

Bases: object

Kodi’s dialog class

The graphical control element dialog box (also called dialogue box or just dialog) is a small window that communicates information to the user and prompts them for a response.

yesno(heading: str, message: str, nolabel: str = '', yeslabel: str = '', autoclose: int = 0, defaultbutton: int = 10) → bool[source]¶

Yes / no dialog

The Yes / No dialog can be used to inform the user about questions and get the answer.

Parameters:

heading – string or unicode - dialog heading.
message – string or unicode - message text.
nolabel – [opt] label to put on the no button.
yeslabel – [opt] label to put on the yes button.
autoclose – [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
defaultbutton – [opt] integer - specifies the default focused button.(default=DLG_YESNO_NO_BTN)

Value:	Description:
xbmcgui.DLG_YESNO_NO_BTN	Set the “No” button as default.
xbmcgui.DLG_YESNO_YES_BTN	Set the “Yes” button as default.
xbmcgui.DLG_YESNO_CUSTOM_BTN	Set the “Custom” button as default.

Returns:: Returns True if ‘Yes’ was pressed, else False.

@python_v13 Added new option autoclose.

@python_v19 Renamed option line1 to message.

@python_v19 Removed option line2.

@python_v19 Removed option line3.

@python_v20 Added new option defaultbutton.

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.yesno('Kodi', 'Do you want to exit this script?')
..

yesnocustom(heading: str, message: str, customlabel: str, nolabel: str = '', yeslabel: str = '', autoclose: int = 0, defaultbutton: int = 10) → int[source]¶

Yes / no / custom dialog

The YesNoCustom dialog can be used to inform the user about questions and get the answer. The dialog provides a third button appart from yes and no. Button labels are fully customizable.

Parameters:

heading – string or unicode - dialog heading.
message – string or unicode - message text.
customlabel – string or unicode - label to put on the custom button.
nolabel – [opt] label to put on the no button.
yeslabel – [opt] label to put on the yes button.
autoclose – [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
defaultbutton – [opt] integer - specifies the default focused button.(default=DLG_YESNO_NO_BTN)

Value:	Description:
xbmcgui.DLG_YESNO_NO_BTN	Set the “No” button as default.
xbmcgui.DLG_YESNO_YES_BTN	Set the “Yes” button as default.
xbmcgui.DLG_YESNO_CUSTOM_BTN	Set the “Custom” button as default.

Returns:: Returns the integer value for the selected button (-1:cancelled, 0:no, 1:yes, 2:custom)

@python_v19 New function added.

@python_v20 Added new option defaultbutton.

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.yesnocustom('Kodi', 'Question?', 'Maybe')
..

info(item: ListItem) → bool[source]¶

Info dialog

Show the corresponding info dialog for a given listitem

Parameters:: listitem – xbmcgui.ListItem -ListItem to show info for.
Returns:: Returns whether the dialog opened successfully.

@python_v17 New function added.

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.info(listitem)
..

select(heading: str, list: List[str | ListItem], autoclose: int = 0, preselect: int = -1, useDetails: bool = False) → int[source]¶

Select dialog

Show of a dialog to select of an entry as a key

Parameters:

heading – string or unicode - dialog heading.
list – list of strings / xbmcgui.ListItems - list of items shown in dialog.
autoclose – [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
preselect – [opt] integer - index of preselected item. (default=no preselected item)
useDetails – [opt] bool - use detailed list instead of a compact list. (default=false)

Returns:

Returns the position of the highlighted item as an integer.

@python_v17 preselect option added.

@python_v17 Added new option useDetails.

@python_v17 Allow listitems for parameter list

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.select('Choose a playlist', ['Playlist #1', 'Playlist #2, 'Playlist #3'])
..

contextmenu(list: List[str]) → int[source]¶

Show a context menu.

Parameters:: list – string list - list of items.
Returns:: the position of the highlighted item as an integer (-1 if cancelled).

@python_v17 New function addedExample:

..
dialog = xbmcgui.Dialog()
ret = dialog.contextmenu(['Option #1', 'Option #2', 'Option #3'])
..

multiselect(heading: str, options: List[str | ListItem], autoclose: int = 0, preselect: List[int] | None = None, useDetails: bool = False) → List[int][source]¶

Show a multi-select dialog.

Parameters:

heading – string or unicode - dialog heading.
options – list of strings / xbmcgui.ListItems - options to choose from.
autoclose – [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
preselect – [opt] list of int - indexes of items to preselect in list (default: do not preselect any item)
useDetails – [opt] bool - use detailed list instead of a compact list. (default=false)

Returns:

Returns the selected items as a list of indices, or None if cancelled.

@python_v16 New function added.

@python_v17 Added new option preselect.

@python_v17 Added new option useDetails.

@python_v17 Allow listitems for parameter options

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.multiselect("Choose something", ["Foo", "Bar", "Baz"], preselect=[1,2])
..

ok(heading: str, message: str) → bool[source]¶

OK dialog

The functions permit the call of a dialog of information, a confirmation of the user by press from OK required.

Parameters:

heading – string or unicode - dialog heading.
message – string or unicode - message text.

Returns:

Returns True if ‘Ok’ was pressed, else False.

@python_v19 Renamed option line1 to message.

@python_v19 Removed option line2.

@python_v19 Removed option line3.

Example:

..
dialog = xbmcgui.Dialog()
ok = dialog.ok('Kodi', 'There was an error.')
..

textviewer(heading: str, text: str, usemono: bool = False) → None[source]¶

TextViewer dialog

The text viewer dialog can be used to display descriptions, help texts or other larger texts.

Parameters:

heading – string or unicode - dialog heading.
text – string or unicode - text.
usemono – [opt] bool - use monospace font

@python_v16 New function added.

@python_v18 New optional param added usemono.

Example:

..
dialog = xbmcgui.Dialog()
dialog.textviewer('Plot', 'Some movie plot.')
..

browse(type: int, heading: str, shares: str, mask: str = '', useThumbs: bool = False, treatAsFolder: bool = False, defaultt: str = '', enableMultiple: bool = False) → str | List[str][source]¶

Browser dialog

The function offer the possibility to select a file by the user of the add-on.

It allows all the options that are possible in Kodi itself and offers all support file types.

Parameters:: type – integer - the type of browse dialog.

Param	Name
0	ShowAndGetDirectory
1	ShowAndGetFile
2	ShowAndGetImage
3	ShowAndGetWriteableDirectory

Parameters:

heading – string or unicode - dialog heading.
shares – string or unicode - fromsources.xml

Param	Name
“programs”	list program addons
“video”	list video sources
“music”	list music sources
“pictures”	list picture sources
“files”	list file sources (added through filemanager)
“games”	list game sources
“local”	list local drives
“”	list local drives and network shares

Parameters:

mask – [opt] string or unicode - ‘|’ separated file mask. (i.e. ‘.jpg|.png’)
useThumbs – [opt] boolean - if True autoswitch to Thumb view if files exist.
treatAsFolder – [opt] boolean - if True playlists and archives act as folders.
defaultt – [opt] string - default path or file.
enableMultiple – [opt] boolean - if True multiple file selection is enabled.

Returns:

If enableMultiple is False (default): returns filename and/or path as a string: to the location of the highlighted item, if user pressed ‘Ok’ or a masked item was selected. Returns the default value if dialog was canceled. If enableMultiple is True: returns tuple of marked filenames as a string if user pressed ‘Ok’ or a masked item was selected. Returns empty tuple if dialog was canceled.

If type is 0 or 3 the enableMultiple parameter is ignore

@python_v18 New option added to browse network and/or local drives.

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browse(3, 'Kodi', 'files', '', False, False, False, 'special://masterprofile/script_data/Kodi Lyrics')
..

browseSingle(type: int, heading: str, shares: str, mask: str = '', useThumbs: bool = False, treatAsFolder: bool = False, defaultt: str = '') → str[source]¶

Browse single dialog

The function offer the possibility to select a file by the user of the add-on.

It allows all the options that are possible in Kodi itself and offers all support file types.

Parameters:: type – integer - the type of browse dialog.

Param	Name
0	ShowAndGetDirectory
1	ShowAndGetFile
2	ShowAndGetImage
3	ShowAndGetWriteableDirectory

Parameters:

heading – string or unicode - dialog heading.
shares – string or unicode - fromsources.xml

Param	Name
“programs”	list program addons
“video”	list video sources
“music”	list music sources
“pictures”	list picture sources
“files”	list file sources (added through filemanager)
“games”	list game sources
“local”	list local drives
“”	list local drives and network shares

Parameters:

mask – [opt] string or unicode - ‘|’ separated file mask. (i.e. ‘.jpg|.png’)
useThumbs – [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).
treatAsFolder – [opt] boolean - if True playlists and archives act as folders (default=false).
defaultt – [opt] string - default path or file.

Returns:

Returns filename and/or path as a string to the location of the highlighted item, if user pressed ‘Ok’ or a masked item was selected. Returns the default value if dialog was canceled.

@python_v18 New option added to browse network and/or local drives.

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browseSingle(3, 'Kodi', 'files', '', False, False, 'special://masterprofile/script_data/Kodi Lyrics')
..

browseMultiple(type: int, heading: str, shares: str, mask: str = '', useThumbs: bool = False, treatAsFolder: bool = False, defaultt: str = '') → List[str][source]¶

Browser dialog

The function offer the possibility to select multiple files by the user of the add-on.

It allows all the options that are possible in Kodi itself and offers all support file types.

Parameters:: type – integer - the type of browse dialog.

Param	Name
1	ShowAndGetFile
2	ShowAndGetImage

Parameters:

heading – string or unicode - dialog heading.
shares – string or unicode - from sources.xml

Param	Name
“programs”	list program addons
“video”	list video sources
“music”	list music sources
“pictures”	list picture sources
“files”	list file sources (added through filemanager)
“games”	list game sources
“local”	list local drives
“”	list local drives and network shares

Parameters:

mask – [opt] string or unicode - ‘|’ separated file mask. (i.e. ‘.jpg|.png’)
useThumbs – [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).
treatAsFolder – [opt] boolean - if True playlists and archives act as folders (default=false).
defaultt – [opt] string - default path or file.

Returns:

Returns tuple of marked filenames as a string,” if user pressed ‘Ok’ or a masked item was selected. Returns empty tuple if dialog was canceled.

@python_v18 New option added to browse network and/or local drives.

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browseMultiple(2, 'Kodi', 'files', '', False, False, 'special://masterprofile/script_data/Kodi Lyrics')
..

numeric(type: int, heading: str, defaultt: str = '', bHiddenInput: bool = False) → str[source]¶

Numeric dialog

The function have to be permitted by the user for the representation of a numeric keyboard around an input.

Parameters:: type – integer - the type of numeric dialog.

Param	Name	Format
0	ShowAndGetNumber	(default format: `#`)
1	ShowAndGetDate	(default format: `DD/MM/YYYY`)
2	ShowAndGetTime	(default format: `HH:MM`)
3	ShowAndGetIPAddress	(default format: `#.#.#.#`)
4	ShowAndVerifyNewPassword	(default format: `*`)

Parameters:

heading – string or unicode - dialog heading (will be ignored for type 4).
defaultt – [opt] string - default value.
bHiddenInput – [opt] bool - mask input (available for type 0).

Returns:

Returns the entered data as a string. Returns the default value if dialog was canceled.

@python_v19 New option added ShowAndVerifyNewPassword.

@python_v19 Added new option bHiddenInput.

Example:

..
dialog = xbmcgui.Dialog()
d = dialog.numeric(1, 'Enter date of birth')
..

notification(heading: str, message: str, icon: str = '', time: int = 0, sound: bool = True) → None[source]¶

Show a Notification alert.

Parameters:

heading – string - dialog heading.
message – string - dialog message.
icon – [opt] string - icon to use. (default xbmcgui.NOTIFICATION_INFO)
time – [opt] integer - time in milliseconds (default 5000)
sound – [opt] bool - play notification sound (default True)

Builtin Icons:

xbmcgui.NOTIFICATION_INFO
xbmcgui.NOTIFICATION_WARNING
xbmcgui.NOTIFICATION_ERROR

@python_v13 New function added.

Example:

..
dialog = xbmcgui.Dialog()
dialog.notification('Movie Trailers', 'Finding Nemo download finished.', xbmcgui.NOTIFICATION_INFO, 5000)
..

input(heading: str, defaultt: str = '', type: int = 0, option: int = 0, autoclose: int = 0) → str[source]¶

Show an Input dialog.

Parameters:

heading – string - dialog heading.
defaultt – [opt] string - default value. (default=empty string)
type – [opt] integer - the type of keyboard dialog. (default=`xbmcgui.INPUT_ALPHANUM`)

Parameter	Format
`xbmcgui.INPUT_ALPHANUM`	(standard keyboard)
`xbmcgui.INPUT_NUMERIC`	(format: #)
`xbmcgui.INPUT_DATE`	(format: DD/MM/YYYY)
`xbmcgui.INPUT_TIME`	(format: HH:MM)
`xbmcgui.INPUT_IPADDRESS`	(format: #.#.#.#)
`xbmcgui.INPUT_PASSWORD`	(return md5 hash of input, input is masked)

Parameters:

option – [opt] integer - option for the dialog. (see Options below) Password dialog: xbmcgui.PASSWORD_VERIFY (verifies an existing (default) md5 hashed password), Alphanum dialog: xbmcgui.ALPHANUM_HIDE_INPUT (masks input)
autoclose – [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)

Returns:

Returns the entered data as a string. Returns an empty string if dialog was canceled.

@python_v13 New function added.

Example:

..
dialog = xbmcgui.Dialog()
d = dialog.input('Enter secret code', type=xbmcgui.INPUT_ALPHANUM, option=xbmcgui.ALPHANUM_HIDE_INPUT)
..

colorpicker(heading: str, selectedcolor: str = '', colorfile: str = '', colorlist: List[ListItem] = ()) → str[source]¶

Show a color selection dialog.

Parameters:

heading – string - dialog heading.
selectedcolor – [opt] string - hex value of the preselected color.
colorfile – [opt] string - xml file containing color definitions. XML content style: <colors> <color name=”white”>ffffffff</color> <color name=”grey”>7fffffff</color> <color name=”green”>ff00ff7f</color> </colors>
colorlist – [opt] xbmcgui.ListItems - where label defines the color name and label2 is set to the hex value.

Returns:

Returns the hex value of the selected color as a string.

@python_v20 New function added.

Example:

..
# colorfile example
dialog = xbmcgui.Dialog()
value = dialog.colorpicker('Select color', 'ff00ff00', 'os.path.join(xbmcaddon.Addon().getAddonInfo("path"), "colors.xml")')
..
# colorlist example
listitems = []
l1 = xbmcgui.ListItem("red", "FFFF0000")
l2 = xbmcgui.ListItem("green", "FF00FF00")
l3 = xbmcgui.ListItem("blue", "FF0000FF")
listitems.append(l1)
listitems.append(l2)
listitems.append(l3)
dialog = xbmcgui.Dialog()
value = dialog.colorpicker("Select color", "FF0000FF", colorlist=listitems)
..

class xbmcgui.DialogProgress[source]¶

Bases: object

Kodi’s progress dialog class (Duh!)

create(heading: str, message: str = '') → None[source]¶

Create and show a progress dialog.

Parameters:

heading – string or unicode - dialog heading.
message – [opt] string or unicode - message text.

Note

Use update() to update lines and progressbar.

@python_v19 Renamed option line1 to message.

@python_v19 Removed option line2.

@python_v19 Removed option line3.

Example:

..
pDialog = xbmcgui.DialogProgress()
pDialog.create('Kodi', 'Initializing script...')
..

update(percent: int, message: str = '') → None[source]¶

Updates the progress dialog.

Parameters:

percent – integer - percent complete. (0:100)
message – [opt] string or unicode - message text.

@python_v19 Renamed option line1 to message.

@python_v19 Removed option line2.

@python_v19 Removed option line3.

Example:

..
pDialog.update(25, 'Importing modules...')
..

close() → None[source]¶

Close the progress dialog.

Example:

..
pDialog.close()
..

iscanceled() → bool[source]¶

Checks progress is canceled.

Returns:: True if the user pressed cancel.

Example:

..
if (pDialog.iscanceled()): return
..

class xbmcgui.DialogProgressBG[source]¶

Bases: object

Kodi’s background progress dialog class

deallocating() → None[source]¶

This method is meant to be called from the destructor of the lowest level class.

It’s virtual because it’s a convenient place to receive messages that we’re about to go be deleted but prior to any real tear-down.

Any overloading classes need to remember to pass the call up the chain.

create(heading: str, message: str = '') → None[source]¶

Create and show a background progress dialog.

Parameters:

heading – string or unicode - dialog heading.
message – [opt] string or unicode - message text.

Note

‘heading’ is used for the dialog’s id. Use a unique heading. Use update() to update heading, message and progressbar.

Example:

..
pDialog = xbmcgui.DialogProgressBG()
pDialog.create('Movie Trailers', 'Downloading Monsters Inc... .')
..

update(percent: int = 0, heading: str = '', message: str = '') → None[source]¶

Updates the background progress dialog.

Parameters:

percent – [opt] integer - percent complete. (0:100)
heading – [opt] string or unicode - dialog heading.
message – [opt] string or unicode - message text.

Note

To clear heading or message, you must pass a blank character.

Example:

..
pDialog.update(25, message='Downloading Finding Nemo ...')
..

close() → None[source]¶

Close the background progress dialog

Example:

..
pDialog.close()
..

isFinished() → bool[source]¶

Checks progress is finished

Returns:: True if the background dialog is active.

Example:

..
if (pDialog.isFinished()): return
..

class xbmcgui.ListItem(label: str = '', label2: str = '', path: str = '', offscreen: bool = False)[source]¶

Bases: object

Selectable window list item.

getLabel() → str[source]¶

Returns the listitem label.

Returns:: Label of item

Example:

...
# getLabel()
label = listitem.getLabel()
...

getLabel2() → str[source]¶

Returns the second listitem label.

Returns:: Second label of item

Example:

...
# getLabel2()
label = listitem.getLabel2()
...

setLabel(label: str) → None[source]¶

Sets the listitem’s label.

Parameters:: label – string or unicode - text string.

Example:

...
# setLabel(label)
listitem.setLabel('Casino Royale')
...

setLabel2(label: str) → None[source]¶

Sets the listitem’s label2.

Parameters:: label – string or unicode - text string.

Example:

...
# setLabel2(label)
listitem.setLabel2('Casino Royale')
...

getDateTime() → str[source]¶

Returns the list item’s datetime in W3C format (YYYY-MM-DDThh:mm:ssTZD).

Returns:: string or unicode - datetime string (W3C).

@python_v20 New function added.

Example:

...
# getDateTime()
strDateTime = listitem.getDateTime()
...

setDateTime(dateTime: str) → None[source]¶

Sets the list item’s datetime in W3C format. The following formats are supported:

YYYY

YYYY-MM-DD

YYYY-MM-DDThh:mm[TZD]

YYYY-MM-DDThh:mm:ss[TZD] where the timezone (TZD) is always optional and can be in one of the following formats:

Z (for UTC)

+hh:mm

-hh:mm

Parameters:: label – string or unicode - datetime string (W3C).

@python_v20 New function added.

Example:

...
# setDate(dateTime)
listitem.setDateTime('2021-03-09T12:30:00Z')
...

setArt(dictionary: Dict[str, str]) → None[source]¶

Sets the listitem’s art

Parameters:: values – dictionary - pairs of { label: value }. Some default art values (any string possible):

Label	Type
thumb	string - image filename
poster	string - image filename
banner	string - image filename
fanart	string - image filename
clearart	string - image filename
clearlogo	string - image filename
landscape	string - image filename
icon	string - image filename

@python_v13 New function added.

@python_v16 Added new label icon.

Example:

...
# setArt(values)
listitem.setArt({ 'poster': 'poster.png', 'banner' : 'banner.png' })
...

setIsFolder(isFolder: bool) → None[source]¶

Sets if this listitem is a folder.

Parameters:: isFolder – bool - True=folder / False=not a folder (default).

@python_v18 New function added.

Example:

...
# setIsFolder(isFolder)
listitem.setIsFolder(True)
...

setUniqueIDs(dictionary: Dict[str, str], defaultrating: str = '') → None[source]¶

Sets the listitem’s uniqueID

Parameters:

values – dictionary - pairs of``{ label: value }``.
defaultrating – [opt] string - the name of default rating.

Some example values (any string possible):

Label	Type
imdb	string - uniqueid name
tvdb	string - uniqueid name
tmdb	string - uniqueid name
anidb	string - uniqueid name

@python_v20 Deprecated. Use InfoTagVideo.setUniqueIDs() instead.

Example:

...
# setUniqueIDs(values, defaultrating)
listitem.setUniqueIDs({ 'imdb': 'tt8938399', 'tmdb' : '9837493' }, "imdb")
...

setRating(type: str, rating: float, votes: int = 0, defaultt: bool = False) → None[source]¶

Sets a listitem’s rating. It needs at least type and rating param

Parameters:

type – string - the type of the rating. Any string.
rating – float - the value of the rating.
votes – int - the number of votes. Default 0.
defaultt – bool - is the default rating?. Default False. Some example type (any string possible):

Label	Type
imdb	string - rating type
tvdb	string - rating type
tmdb	string - rating type
anidb	string - rating type

@python_v20 Deprecated. Use InfoTagVideo.setRating() instead.

Example:

...
# setRating(type, rating, votes, defaultt))
listitem.setRating("imdb", 4.6, 8940, True)
...

addSeason(number: int, name: str = '') → None[source]¶

Add a season with name to a listitem. It needs at least the season number

Parameters:

number – int - the number of the season.
name – string - the name of the season. Default “”.

@python_v18 New function added.

@python_v20 Deprecated. Use InfoTagVideo.addSeason() or InfoTagVideo.addSeasons() instead.

Example:

...
# addSeason(number, name))
listitem.addSeason(1, "Murder House")
...

getArt(key: str) → str[source]¶

Returns a listitem art path as a string, similar to an infolabel.

Parameters:: key – string - art name. Some default art values (any string possible):

Label	Type
thumb	string - image path
poster	string - image path
banner	string - image path
fanart	string - image path
clearart	string - image path
clearlogo	string - image path
landscape	string - image path
icon	string - image path

@python_v17 New function added.

Example:

...
poster = listitem.getArt('poster')
...

isFolder() → bool[source]¶

Returns whether the item is a folder or not.

@python_v20 New function added.

Example:

...
isFolder = listitem.isFolder()
...

getUniqueID(key: str) → str[source]¶

Returns a listitem uniqueID as a string, similar to an infolabel.

Parameters:: key – string - uniqueID name. Some default uniqueID values (any string possible):

Label	Type
imdb	string - uniqueid name
tvdb	string - uniqueid name
tmdb	string - uniqueid name
anidb	string - uniqueid name

@python_v20 Deprecated. Use InfoTagVideo.getUniqueID() instead.

Example:

...
uniqueID = listitem.getUniqueID('imdb')
...

getRating(key: str) → float[source]¶

Returns a listitem rating as a float.

Parameters:: key – string - rating type. Some default key values (any string possible):

Label	Type
imdb	string - type name
tvdb	string - type name
tmdb	string - type name
anidb	string - type name

@python_v20 Deprecated. Use InfoTagVideo.getRating() instead.

Example:

...
rating = listitem.getRating('imdb')
...

getVotes(key: str) → int[source]¶

Returns a listitem votes as a integer.

Parameters:: key – string - rating type. Some default key values (any string possible):

Label	Type
imdb	string - type name
tvdb	string - type name
tmdb	string - type name
anidb	string - type name

@python_v20 Deprecated. Use InfoTagVideo.getVotesAsInt() instead.

Example:

...
votes = listitem.getVotes('imdb')
...

select(selected: bool) → None[source]¶

Sets the listitem’s selected status.

Parameters:: selected – bool - True=selected/False=not selected

Example:

...
# select(selected)
listitem.select(True)
...

isSelected() → bool[source]¶

Returns the listitem’s selected status.

Returns:: bool - true if selected, otherwise false

Example:

...
# isSelected()
selected = listitem.isSelected()
...

setInfo(type: str, infoLabels: Dict[str, str]) → None[source]¶

Sets the listitem’s infoLabels.

Parameters:

type – string - type of info labels
infoLabels – dictionary - pairs of { label: value }

Available types

Command name	Description
video	Video information
music	Music information
pictures	Pictures informanion
game	Game information

Note

To set pictures exif info, prepend exif: to the label. Exif values must be passed as strings, separate value pairs with a comma. (eg. {'exif:resolution': '720,480'}). See kodi_pictures_infotag for valid strings.

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.

General Values (that apply to all types):

Info label	Description
count	integer (12) - can be used to store an id for later, or for sorting purposes
size	long (1024) - size in bytes
date	string (d.m.Y / 01.01.2009) - file date

Video Values:

Info label	Description
genre	string (Comedy) or list of strings ([“Comedy”, “Animation”, “Drama”])
country	string (Germany) or list of strings ([“Germany”, “Italy”, “France”])
year	integer (2009)
episode	integer (4)
season	integer (1)
sortepisode	integer (4)
sortseason	integer (1)
episodeguide	string (Episode guide)
showlink	string (Battlestar Galactica) or list of strings ([“Battlestar Galactica”, “Caprica”])
top250	integer (192)
setid	integer (14)
tracknumber	integer (3)
rating	float (6.4) - range is 0..10
userrating	integer (9) - range is 1..10 (0 to reset)
watched	deprecated - use playcount instead
playcount	integer (2) - number of times this item has been played
overlay	integer (2) - range is `0..7`. See Overlay icon types for values
cast	list ([“Michal C. Hall”,”Jennifer Carpenter”]) - if provided a list of tuples cast will be interpreted as castandrole
castandrole	list of tuples ([(“Michael C. Hall”,”Dexter”),(“Jennifer Carpenter”,”Debra”)])
director	string (Dagur Kari) or list of strings ([“Dagur Kari”, “Quentin Tarantino”, “Chrstopher Nolan”])
mpaa	string (PG-13)
plot	string (Long Description)
plotoutline	string (Short Description)
title	string (Big Fan)
originaltitle	string (Big Fan)
sorttitle	string (Big Fan)
duration	integer (245) - duration in seconds
studio	string (Warner Bros.) or list of strings ([“Warner Bros.”, “Disney”, “Paramount”])
tagline	string (An awesome movie) - short description of movie
writer	string (Robert D. Siegel) or list of strings ([“Robert D. Siegel”, “Jonathan Nolan”, “J.K. Rowling”])
tvshowtitle	string (Heroes)
premiered	string (2005-03-04)
status	string (Continuing) - status of a TVshow
set	string (Batman Collection) - name of the collection
setoverview	string (All Batman movies) - overview of the collection
tag	string (cult) or list of strings ([“cult”, “documentary”, “best movies”]) - movie tag
imdbnumber	string (tt0110293) - IMDb code
code	string (101) - Production code
aired	string (2008-12-07)
credits	string (Andy Kaufman) or list of strings ([“Dagur Kari”, “Quentin Tarantino”, “Chrstopher Nolan”]) - writing credits
lastplayed	string (Y-m-d h:m:s = 2009-04-05 23:16:04)
album	string (The Joshua Tree)
artist	list ([‘U2’])
votes	string (12345 votes)
path	string (/home/user/movie.avi)
trailer	string (/home/user/trailer.avi)
dateadded	string (Y-m-d h:m:s = 2009-04-05 23:16:04)
mediatype	string - “video”, “movie”, “tvshow”, “season”, “episode” or “musicvideo”
dbid	integer (23) - Only add this for items which are part of the local db. You also need to set the correct ‘mediatype’!

Music Values:

Info label	Description
tracknumber	integer (8)
discnumber	integer (2)
duration	integer (245) - duration in seconds
year	integer (1998)
genre	string (Rock)
album	string (Pulse)
artist	string (Muse)
title	string (American Pie)
rating	float - range is between 0 and 10
userrating	integer - range is 1..10
lyrics	string (On a dark desert highway…)
playcount	integer (2) - number of times this item has been played
lastplayed	string (Y-m-d h:m:s = 2009-04-05 23:16:04)
mediatype	string - “music”, “song”, “album”, “artist”
dbid	integer (23) - Only add this for items which are part of the local db. You also need to set the correct ‘mediatype’!
listeners	integer (25614)
musicbrainztrackid	string (cd1de9af-0b71-4503-9f96-9f5efe27923c)
musicbrainzartistid	string (d87e52c5-bb8d-4da8-b941-9f4928627dc8)
musicbrainzalbumid	string (24944755-2f68-3778-974e-f572a9e30108)
musicbrainzalbumartistid	string (d87e52c5-bb8d-4da8-b941-9f4928627dc8)
comment	string (This is a great song)

Picture Values:

Info label	Description
title	string (In the last summer-1)
picturepath	string (`/home/username/pictures/img001.jpg`)
exif*	string (See kodi_pictures_infotag for valid strings)

Game Values:

Info label	Description
title	string (Super Mario Bros.)
platform	string (Atari 2600)
genres	list ([“Action”,”Strategy”])
publisher	string (Nintendo)
developer	string (Square)
overview	string (Long Description)
year	integer (1980)
gameclient	string (game.libretro.fceumm)

@python_v14 Added new label discnumber.

@python_v15 duration has to be set in seconds.

@python_v16 Added new label mediatype.

@python_v17 Added labels setid, set, imdbnumber, code, dbid (video), path and userrating. Expanded the possible infoLabels for the option mediatype.

@python_v18 Added new**game ** type and associated infolabels. Added labels dbid (music), setoverview, tag, sortepisode, sortseason **, **episodeguide, showlink. Extended labels genre, country, director, studio, writer, tag, credits to also use a list of strings.

@python_v20 Partially deprecated. Use explicit setters in InfoTagVideo, InfoTagMusic, InfoTagPicture or InfoTagGame instead.

Example:

...
listitem.setInfo('video', { 'genre': 'Comedy' })
...

setCast(actors: List[Dict[str, str]]) → None[source]¶

Set cast including thumbnails

Parameters:: actors – list of dictionaries (see below for relevant keys)

Keys:

Label	Description
name	string (Michael C. Hall)
role	string (Dexter)
thumbnail	string (http://www.someurl.com/someimage.png)
order	integer (1)

@python_v17 New function added.

@python_v20 Deprecated. Use InfoTagVideo.setCast() instead.

Example:

...
actors = [{"name": "Actor 1", "role": "role 1"}, {"name": "Actor 2", "role": "role 2"}]
listitem.setCast(actors)
...

setAvailableFanart(images: List[Dict[str, str]]) → None[source]¶

Set available images (needed for video scrapers)

Parameters:: images – list of dictionaries (see below for relevant keys)

Keys:

Label	Description
image	string (http://www.someurl.com/someimage.png)
preview	[opt] string (http://www.someurl.com/somepreviewimage.png)
colors	[opt] string (either comma separated Kodi hex values (”`FFFFFFFF,DDDDDDDD`”) or TVDB RGB Int Triplets (”`\|68,69,59\|69,70,58\|78,78,68\|`”))

@python_v18 New function added.

Example:

...
fanart = [{"image": path_to_image_1, "preview": path_to_preview_1},
          {"image": path_to_image_2, "preview": path_to_preview_2}]
listitem.setAvailableFanart(fanart)
...

addAvailableArtwork(url: str, art_type: str = '', preview: str = '', referrer: str = '', cache: str = '', post: bool = False, isgz: bool = False, season: int = -1) → None[source]¶

Add an image to available artworks (needed for video scrapers)

Parameters:

url – string (image path url)
art_type – string (image type)
preview – [opt] string (image preview path url)
referrer – [opt] string (referrer url)
cache – [opt] string (filename in cache)
post – [opt] bool (use post to retrieve the image, default false)
isgz – [opt] bool (use gzip to retrieve the image, default false)
season – [opt] integer (number of season in case of season thumb)

@python_v18 New function added. @python_v19 New param added (preview).

@python_v20 Deprecated. Use InfoTagVideo.addAvailableArtwork() instead.

Example:

...
listitem.addAvailableArtwork(path_to_image_1, "thumb")
...

addStreamInfo(cType: str, dictionary: Dict[str, str]) → None[source]¶

Add a stream with details.

Parameters:

type – string - type of stream(video/audio/subtitle).
values – dictionary - pairs of { label: value }.

Video Values:

Label	Description
codec	string (h264)
aspect	float (1.78)
width	integer (1280)
height	integer (720)
duration	integer (seconds)

Audio Values:

Label	Description
codec	string (dts)
language	string (en)
channels	integer (2)

Subtitle Values:

Label	Description
language	string (en)

@python_v20 Deprecated. Use InfoTagVideo.addVideoStream(), InfoTagVideo.addAudioStream() or InfoTagVideo.addSubtitleStream() instead.

Example:

...
listitem.addStreamInfo('video', { 'codec': 'h264', 'width' : 1280 })
...

addContextMenuItems(items: List[Tuple[str, str]], replaceItems: bool = False) → None[source]¶

Adds item(s) to the context menu for media lists.

Parameters:: items – list - [(label, action),*] A list of tuples consisting of label and action pairs. label (string or unicode) - item’s label, action (string or unicode) - any available built-in function.

Note

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.

@python_v17 Completely removed previously available argument replaceItems.

Example:

...
listitem.addContextMenuItems([('Theater Showtimes', 'RunScript(script.myaddon,title=Iron Man)')])
...

setProperty(key: str, value: str) → None[source]¶

Sets a listitem property, similar to an infolabel.

Parameters:

key – string - property name.
value – string or unicode - value of property.

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. Some of these are treated internally by Kodi, such as the ‘StartOffset’ property, which is the offset in seconds at which to start playback of an item. Others may be used in the skin to add extra information, such as ‘WatchedCount’ for tvshow items

Internal Properties

Key	Description
inputstream	string (inputstream.adaptive) - Set the inputstream add-on that will be used to play the item
IsPlayable	string - “true”, “false” - Mark the item as playable,mandatory for playable items
MimeType	string (application/x-mpegURL) - Set the MimeType of the item before playback
ResumeTime	float (1962.0) - Set the resume point of the item in seconds
SpecialSort	string - “top”, “bottom” - The item will remain at the top or bottom of the current list
StartOffset	float (60.0) - Set the offset in seconds at which to start playback of the item
StartPercent	float (15.0) - Set the percentage at which to start playback of the item
StationName	string (“My Station Name”) - Used to enforce/override MusicPlayer.StationName infolabel from addons (e.g. in radio addons)
TotalTime	float (7848.0) - Set the total time of the item in seconds
OverrideInfotag	string - “true”, “false” - When true will override all info from previous listitem
ForceResolvePlugin	string - “true”, “false” - When true ensures that a plugin will always receive callbacks to resolve paths (useful for playlist cases)

@python_v20 OverrideInfotag property added

@python_v20 ResumeTime and TotalTime deprecated. Use InfoTagVideo.setResumePoint() instead.

@python_v20 ForceResolvePlugin property added

Example:

...
listitem.setProperty('AspectRatio', '1.85 : 1')
listitem.setProperty('StartOffset', '256.4')
...

setProperties(dictionary: Dict[str, str]) → None[source]¶

Sets multiple properties for listitem’s

Parameters:: values – dictionary - pairs of { label: value }.

@python_v18 New function added.

Example:

...
# setProperties(values)
listitem.setProperties({ 'AspectRatio': '1.85', 'StartOffset' : '256.4' })
...

getProperty(key: str) → str[source]¶

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

Parameters:: key – string - 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.

@python_v20 ResumeTime and TotalTime deprecated. Use InfoTagVideo.getResumeTime() and InfoTagVideo.getResumeTimeTotal() instead.

Example:

...
AspectRatio = listitem.getProperty('AspectRatio')
...

setPath(path: str) → None[source]¶

Sets the listitem’s path.

Parameters:: path – string or unicode - path, activated when item is clicked.

Note

You can use the above as keywords for arguments.

Example:

...
listitem.setPath(path='/path/to/some/file.ext')
...

setMimeType(mimetype: str) → None[source]¶

Sets the listitem’s mimetype if known.

Parameters:: mimetype – string or unicode - mimetype

If known prehand, this can (but does not have to) avoid HEAD requests being sent to HTTP servers to figure out file type.

setContentLookup(enable: bool) → None[source]¶

Enable or disable content lookup for item.

If disabled, HEAD requests to e.g determine mime type will not be sent.

Parameters:: enable – bool to enable content lookup

@python_v16 New function added.

setSubtitles(subtitleFiles: List[str]) → None[source]¶

Sets subtitles for this listitem.

Parameters:: subtitleFiles – list with path to subtitle files

Example:

...
listitem.setSubtitles(['special://temp/example.srt', 'http://example.com/example.srt'])
...

@python_v14 New function added.

getPath() → str[source]¶

Returns the path of this listitem.

Returns:: [string] filename

@python_v17 New function added.

getVideoInfoTag() → xbmc.InfoTagVideo[source]¶

Returns the VideoInfoTag for this item.

Returns:: video info tag

@python_v15 New function added.

getMusicInfoTag() → xbmc.InfoTagMusic[source]¶

Returns the MusicInfoTag for this item.

Returns:: music info tag

@python_v15 New function added.

getPictureInfoTag() → xbmc.InfoTagPicture[source]¶

Returns the InfoTagPicture for this item.

Returns:: picture info tag

@python_v20 New function added.

getGameInfoTag() → xbmc.InfoTagGame[source]¶

Returns the InfoTagGame for this item.

Returns:: game info tag

@python_v20 New function added.

class xbmcgui.Action[source]¶

Bases: object

`Action` class.

This class serves in addition to identify carried out kodi_key_action_ids of Kodi and to be able to carry out thereby own necessary steps.

The data of this class are always transmitted by callback Window::onAction at a window.

getId() → int[source]¶

To get kodi_key_action_ids

This function returns the identification code used by the explained order, it is necessary to determine the type of command from kodi_key_action_ids.

Returns:: The action’s current id as a long or 0 if no action is mapped in the xml’s.

Example:

..
def onAction(self, action):
if action.getId() == ACTION_PREVIOUS_MENU:
print('action received: previous')
..

getButtonCode() → int[source]¶

Returns the button code for this action.

Returns:: [integer] button code

getAmount1() → float[source]¶

Returns the first amount of force applied to the thumbstick.

Returns:: [float] first amount

getAmount2() → float[source]¶

Returns the second amount of force applied to the thumbstick.

Returns:: [float] second amount

class xbmcgui.Window(existingWindowId: int = -1)[source]¶

Bases: object

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

Raises:

ValueError – if supplied window Id does not exist.
Exception – if 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()
..

show() → None[source]¶

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.

setFocus(pControl: Control) → None[source]¶

Give the supplied control focus.

Parameters:

Control – Control class to focus

Raises:

TypeError – If supplied argument is not a Control type
SystemError – On Internal error
RuntimeError – If control is not added to a window

setFocusId(iControlId: int) → None[source]¶

Gives the control with the supplied focus.

Parameters:

ControlId – [integer] On skin defined id of control

Raises:

SystemError – On Internal error
RuntimeError – If control is not added to a window

getFocus() → Control[source]¶

Returns the control which is focused.

Returns:

Focused control class

Raises:

SystemError – On Internal error
RuntimeError – If no control has focus

getFocusId() → int[source]¶

Returns the id of the control which is focused.

Returns:

Focused control id

Raises:

SystemError – On Internal error
RuntimeError – If no control has focus

removeControl(pControl: Control) → None[source]¶

Removes the control from this window.

Parameters:

Control – Control class to remove

Raises:

TypeError – If supplied argument is not a Control type
RuntimeError – If control is not added to this window

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

removeControls(pControls: List[Control]) → None[source]¶

Removes a list of controls from this window.

Parameters:

List – List with controls to remove

Raises:

TypeError – If supplied argument is not a Control type
RuntimeError – If control is not added to this window

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

getHeight() → int[source]¶

Returns the height of this Window instance.

Returns:: Window height in pixels

@python_v18 Function changed

getWidth() → int[source]¶

Returns the width of this Window instance.

Returns:: Window width in pixels

@python_v18 Function changed

setProperty(key: str, value: str) → None[source]¶

Sets a window property, similar to an infolabel.

Parameters:

key – string - property name.
value – string 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')
..

getProperty(key: str) → str[source]¶

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

Parameters:: key – string - 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')
..

clearProperty(key: str) → None[source]¶

Clears the specific window property.

Parameters:: key – string - 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')
..

clearProperties() → None[source]¶

Clears all window properties.

Example:

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

close() → None[source]¶

Closes this window.

Closes this window by activating the old window.

Note

The window is not deleted with this method.

doModal() → None[source]¶: Display this window until close() is called.

addControl(pControl: Control) → None[source]¶

Add a Control to this window.

Parameters:

Control – Control to add

Raises:

TypeError – If supplied argument is not a Control type
ReferenceError – If control is already used in another window
RuntimeError – Should 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(pControls: List[Control]) → None[source]¶

Add a list of Controls to this window.

Parameters:

List – List with controls to add

Raises:

TypeError – If supplied argument is not of List type, or a control is not of Control type
ReferenceError – If control is already used in another window
RuntimeError – Should not happen :-)

getControl(iControlId: int) → Control[source]¶

Gets the control from this window.

Parameters:: controlId – Control id to get
Raises:: Exception – If Control doesn’t exist

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

onAction(action: Action) → None[source]¶

onAction method.

This method will receive all actions that the main program will send to this window.

Parameters:

self – Own base class pointer
action – The action id to perform, see Action to get use of them

Note

By default, only the PREVIOUS_MENU and NAV_BACK actions are handled. Overwrite this method to let your script handle all actions.Don’t forget to capture ACTION_PREVIOUS_MENU or ACTION_NAV_BACK, else the user can’t close this window.

Example:

..
# Define own function where becomes called from Kodi
def onAction(self, action):
if action.getId() == ACTION_PREVIOUS_MENU:
print('action received: previous')
self.close()
if action.getId() == ACTION_SHOW_INFO:
print('action received: show info')
if action.getId() == ACTION_STOP:
print('action received: stop')
if action.getId() == ACTION_PAUSE:
print('action received: pause')
..

onControl(control: Control) → None[source]¶

onControl method.

This method will receive all click events on owned and selected controls when the control itself doesn’t handle the message.

Parameters:

self – Own base class pointer
control – The Control class

Example:

..
# Define own function where becomes called from Kodi
def onControl(self, control):
print("Window.onControl(control=[%s])"%control)
..

onClick(controlId: int) → None[source]¶

onClick method.

This method will receive all click events that the main program will send to this window.

Parameters:

self – Own base class pointer
controlId – The one time clicked GUI control identifier

Example:

..
# Define own function where becomes called from Kodi
def onClick(self,controlId):
if controlId == 10:
print("The control with Id 10 is clicked")
..

onDoubleClick(controlId: int) → None[source]¶

onDoubleClick method.

This method will receive all double click events that the main program will send to this window.

Parameters:

self – Own base class pointer
controlId – The double clicked GUI control identifier

Example:

..
# Define own function where becomes called from Kodi
def onDoubleClick(self,controlId):
if controlId == 10:
print("The control with Id 10 is double clicked")
..

onFocus(controlId: int) → None[source]¶

onFocus method.

This method will receive all focus events that the main program will send to this window.

Parameters:

self – Own base class pointer
controlId – The focused GUI control identifier

Example:

..
# Define own function where becomes called from Kodi
def onDoubleClick(self,controlId):
if controlId == 10:
print("The control with Id 10 is focused")
..

onInit() → None[source]¶

onInit method.

This method will be called to initialize the window

Parameters:: self – Own base class pointer

Example:

..
# Define own function where becomes called from Kodi
def onInit(self):
print("Window.onInit method called from Kodi")
..

class xbmcgui.WindowDialog[source]¶

Bases: Window

GUI window dialog class for Add-Ons.

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

Parameters:

windowId – [opt] Specify an id to use an existing window.

Raises:

ValueError – if supplied window Id does not exist.
Exception – if 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:

..
dialog = xbmcgui.WindowDialog()
width = dialog.getWidth()
..

class xbmcgui.WindowXML(xmlFilename: str, scriptPath: str, defaultSkin: str = 'Default', defaultRes: str = '720p', isMedia: bool = False)[source]¶

Bases: Window

GUI xml window class.

Creates a new xml file based window class.

Note

This class include also all calls from `Window`.

Parameters:

xmlFilename – string - the name of the xml file to look for.
scriptPath – string - path to script. used to fallback to if the xml doesn’t exist in the current skin. (eg xbmcaddon.Addon().getAddonInfo(‘path’))
defaultSkin – [opt] string - name of the folder in the skins path to look in for the xml. (default=’Default’)
defaultRes – [opt] string - default skins resolution. (1080i, 720p, ntsc16x9, ntsc, pal16x9 or pal. default=’720p’)
isMedia – [opt] bool - if False, create a regular window. if True, create a mediawindow. (default=False)

Raises:

Exception – if more then 200 windows are created.

Skin folder structure is e.g. resources/skins/Default/720p

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

@python_v18 New param added isMedia.

Example:

..
win = xbmcgui.WindowXML('script-Lyrics-main.xml', xbmcaddon.Addon().getAddonInfo('path'), 'default', '1080i', False)
win.doModal()
del win
..

On functions defined input variable controlId (GUI control identifier)** is the on window.xml defined value behind type added with id="..." and used to identify for changes there and on callbacks.

<control type="label" id="31">
<description>Title Label</description>
...
</control>
<control type="progress" id="32">
<description>progress control</description>
...
</control>

addItem(item: str | ListItem, position: int = 2147483647) → None[source]¶

Add a new item to this Window ``List.

Parameters:

item – string, unicode or ListItem - item to add.
position – [opt] integer - position of item to add. (NO Int = Adds to bottom,0 adds to top, 1 adds to one below from top, -1 adds to one above from bottom etc etc) If integer positions are greater than list size, negative positions will add to top of list, positive positions will add to bottom of list

Example:

..
self.addItem('Reboot Kodi', 0)
..

addItems(items: List[str | ListItem]) → None[source]¶

Add a list of items to to the window list.

Parameters:: items – List - list of strings, unicode objects or ListItems to add.

Example:

..
self.addItems(['Reboot Kodi', 'Restart Kodi'])
..

removeItem(position: int) → None[source]¶

Removes a specified item based on position, from the Window ``List.

Parameters:: position – integer - position of item to remove.

Example:

..
self.removeItem(5)
..

getCurrentListPosition() → int[source]¶

Gets the current position in the Window ``List.

Example:

..
pos = self.getCurrentListPosition()
..

setCurrentListPosition(position: int) → None[source]¶

Set the current position in the Window ``List.

Parameters:: position – integer - position of item to set.

Example:

..
self.setCurrentListPosition(5)
..

getListItem(position: int) → ListItem[source]¶

Returns a given ListItem in this Window ``List.

Parameters:: position – integer - position of item to return.

Example:

..
listitem = self.getListItem(6)
..

getListSize() → int[source]¶

Returns the number of items in this Window ``List.

Example:

..
listSize = self.getListSize()
..

clearList() → None[source]¶

Clear the Window List.

Example:

..
self.clearList()
..

setContainerProperty(strProperty: str, strValue: str) → None[source]¶

Sets a container property, similar to an infolabel.

Parameters:

key – string - property name.
value – string or unicode - value of property.

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.

@python_v17 Changed function from setProperty to setContainerProperty.

Example:

..
self.setContainerProperty('Category', 'Newest')
..

setContent(strValue: str) → None[source]¶

Sets the content type of the container.

Parameters:: value – string or unicode - content value.

Available content types

Name	Media
actors	Videos
addons	Addons, Music, Pictures, Programs, Videos
albums	Music, Videos
artists	Music, Videos
countries	Music, Videos
directors	Videos
files	Music, Videos
games	Games
genres	Music, Videos
images	Pictures
mixed	Music, Videos
movies	Videos
Musicvideos	Music, Videos
playlists	Music, Videos
seasons	Videos
sets	Videos
songs	Music
studios	Music, Videos
tags	Music, Videos
tvshows	Videos
videos	Videos
years	Music, Videos

@python_v18 Added new function.

Example:

..
self.setContent('movies')
..

getCurrentContainerId() → int[source]¶

Get the id of the currently visible container.

@python_v17 Added new function.

Example:

..
container_id = self.getCurrentContainerId()
..

class xbmcgui.WindowXMLDialog(xmlFilename: str, scriptPath: str, defaultSkin: str = 'Default', defaultRes: str = '720p')[source]¶

Bases: WindowXML

GUI xml window dialog

Creates a new xml file based window dialog class.

Parameters:

xmlFilename – string - the name of the xml file to look for.
scriptPath – string - path to script. used to fallback to if the xml doesn’t exist in the current skin. (eg xbmcaddon.Addon().getAddonInfo('path'))
defaultSkin – [opt] string - name of the folder in the skins path to look in for the xml. (default=’Default’)
defaultRes – [opt] string - default skins resolution. (1080i, 720p, ntsc16x9, ntsc, pal16x9 or pal. default=’720p’)

Raises:

Exception – if more then 200 windows are created.

Note

Skin folder structure is e.g. resources/skins/Default/720p

Example:

..
dialog = xbmcgui.WindowXMLDialog('script-Lyrics-main.xml', xbmcaddon.Addon().getAddonInfo('path'), 'default', '1080i')
dialog.doModal()
del dialog
..

On functions defined input variable controlId (GUI control identifier)** is the on window.xml defined value behind type added with id="..." and used to identify for changes there and on callbacks.

<control type="label" id="31">
<description>Title Label</description>
...
</control>
<control type="progress" id="32">
<description>progress control</description>
...
</control>

xbmcgui.getCurrentWindowId() → int[source]¶

Returns the id for the current ‘active’ window as an integer.

Returns:: The currently active window Id

Example:

..
wid = xbmcgui.getCurrentWindowId()
..

xbmcgui.getCurrentWindowDialogId() → int[source]¶

Returns the id for the current ‘active’ dialog as an integer.

Returns:: The currently active dialog Id

Example:

..
wid = xbmcgui.getCurrentWindowDialogId()
..

xbmcgui.getScreenHeight() → int[source]¶

Returns the height of this screen.

Returns:: Screen height

@python_v18 New function added.

xbmcgui.getScreenWidth() → int[source]¶

Returns the width of this screen.

Returns:: Screen width

@python_v18 New function added.

xbmcgui¶

Kodistubs

Navigation

Related Topics