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, font, …)

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, …)

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.

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

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: xbmcgui.Control, down: xbmcgui.Control, left: xbmcgui.Control, right: xbmcgui.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: xbmcgui.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: xbmcgui.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: xbmcgui.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: xbmcgui.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: xbmcgui.Control

Used for cycling up/down controls.

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

Warning

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: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, alignment: int = 0, hasPath: bool = False, angle: int = 0)[source]

Bases: xbmcgui.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:

Defination 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()
...
setLabel(label: str = '', font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None, label2: str = '')None[source]

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: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, _alignment: int = 0, focusTexture: Optional[str] = None, noFocusTexture: Optional[str] = None)[source]

Bases: xbmcgui.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:

Defination 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')
...
setLabel(label: str = '', font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None, label2: str = '')None[source]

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: Optional[str] = None, textColor: Optional[str] = None, buttonTexture: Optional[str] = None, buttonFocusTexture: Optional[str] = None, selectedColor: Optional[str] = None, _imageWidth: int = 10, _imageHeight: int = 10, _itemTextXOffset: int = 10, _itemTextYOffset: int = 2, _itemHeight: int = 27, _space: int = 2, _alignmentY: int = 4)[source]

Bases: xbmcgui.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:

Defination 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: Union[str, xbmcgui.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[Union[str, xbmcgui.ListItem]])None[source]

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

Parameters

itemsList - 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).

Example:

...
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()xbmcgui.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()xbmcgui.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)xbmcgui.ListItem[source]

Returns a given ListItem in this List.

Parameters

index – integer - index number of item to return.

Returns

ListItem

Raises

ValueError – if index is out of range.

Example:

...
listitem = cList.getListItem(6)
...
setStaticContent(items: List[xbmcgui.ListItem])None[source]

Fills a static list with a list of listitems.

Parameters

items

  • 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: Optional[str] = None, textColor: Optional[str] = None, _alignment: int = 0)[source]

Bases: xbmcgui.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:

Defination 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: Optional[str] = None, textColor: Optional[str] = None)[source]

Bases: xbmcgui.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: Optional[str] = None)[source]

Bases: xbmcgui.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: Optional[str] = None, textureleft: Optional[str] = None, texturemid: Optional[str] = None, textureright: Optional[str] = None, textureoverlay: Optional[str] = None)[source]

Bases: xbmcgui.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: Optional[str] = None, noFocusTexture: Optional[str] = None, textOffsetX: int = 10, textOffsetY: int = 2, alignment: int = 4, font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, angle: int = 0, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None)[source]

Bases: xbmcgui.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:

Defination 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')
...
setLabel(label: str = '', font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None, label2: str = '')None[source]

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: xbmcgui.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: Optional[str] = None, noFocusOnTexture: Optional[str] = None, focusOffTexture: Optional[str] = None, noFocusOffTexture: Optional[str] = None, focusTexture: Optional[str] = None, noFocusTexture: Optional[str] = None, textOffsetX: int = 10, textOffsetY: int = 2, _alignment: int = 4, font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, angle: int = 0, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None, disabledOnTexture: Optional[str] = None, disabledOffTexture: Optional[str] = None)[source]

Bases: xbmcgui.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:

Defination 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()
...
setLabel(label: str = '', font: Optional[str] = None, textColor: Optional[str] = None, disabledColor: Optional[str] = None, shadowColor: Optional[str] = None, focusedColor: Optional[str] = None, label2: str = '')None[source]

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: Optional[str] = None, texture: Optional[str] = None, texturefocus: Optional[str] = None, orientation: int = 1)[source]

Bases: xbmcgui.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)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)

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.

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)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 – [opt] 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)

Returns

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

@python_v19 New function added.

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.yesnocustom('Kodi', 'Question?', 'Maybe')
..
info(item: xbmcgui.ListItem)bool[source]

Info dialog

Show the corresponding info dialog for a given listitem

Parameters

listitemListItem 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[Union[str, xbmcgui.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 added

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.contextmenu(['Option #1', 'Option #2', 'Option #3'])
..
multiselect(heading: str, options: List[Union[str, xbmcgui.ListItem]], autoclose: int = 0, preselect: Optional[List[int]] = 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)Union[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 - 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 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)
..
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.

The list item control is used for creating item lists in Kodi

Parameters
  • label – [opt] string

  • label2 – [opt] string

  • path – [opt] string

@python_v16 iconImage and thumbnailImage are deprecated. Use setArt().

@python_v19 Removed iconImage and thumbnailImage. Use setArt().

Example:

...
listitem = xbmcgui.ListItem('Casino Royale')
...
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')
...
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

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

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.

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')
...
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

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

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

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

  • 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

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

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.

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

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)

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

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.

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.

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: xbmcgui.Control)None[source]

Give the supplied control focus.

Parameters

ControlControl class to focus

Raises
setFocusId(iControlId: int)None[source]

Gives the control with the supplied focus.

Parameters

ControlId – [integer] On skin defined id of control

Raises
getFocus()xbmcgui.Control[source]

Returns the control which is focused.

Returns

Focused control class

Raises
getFocusId()int[source]

Returns the id of the control which is focused.

Returns

Focused control id

Raises
removeControl(pControl: xbmcgui.Control)None[source]

Removes the control from this window.

Parameters

ControlControl 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[xbmcgui.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: xbmcgui.Control)None[source]

Add a Control to this window.

Parameters

ControlControl to add

Raises

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[xbmcgui.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)xbmcgui.Control[source]

Gets the control from this window.

Parameters

controlIdControl 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: xbmcgui.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: xbmcgui.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: xbmcgui.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: xbmcgui.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: Union[str, xbmcgui.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[Union[str, xbmcgui.ListItem]])None[source]

Add a list of items to to the window list.

Parameters

itemsList - 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)xbmcgui.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: xbmcgui.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.