xbmcgui

GUI functions on Kodi

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

Classes

Control() Code based skin access
ControlSpin() Used for cycling up/down controls
ControlLabel(x, y, width, height, label[, …]) Used to show some lines of text
ControlEdit(x, y, width, height, label[, …]) Used as an input control for the osd keyboard and other input fields
ControlList(x, y, width, height[, font, …]) Used for a scrolling lists of items.
ControlFadeLabel(x, y, width, height[, …]) Used to show multiple pieces of text in the same position, by fading from one to the other
ControlTextBox(x, y, width, height[, font, …]) Used to show a multi-page piece of text
ControlImage(x, y, width, height, filename) Used to show an image
ControlProgress(x, y, width, height[, …]) Used to show the progress of a particular operation
ControlButton(x, y, width, height, label[, …]) A standard push button control
ControlGroup(x, y, width, height) Used to group controls together
ControlRadioButton(x, y, width, height, label) For control a radio button (as used for on/off settings)
ControlSlider(x, y, width, height[, …]) Used for a volume slider
Dialog() Kodi’s dialog class
DialogProgress() Kodi’s progress dialog class
DialogBusy() Kodi’s busy dialog class
DialogProgressBG() Kodi’s background progress dialog class
ListItem([label, label2, iconImage, …]) Selectable window list item
Action() Action class
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

Functions

getCurrentWindowId() Returns the id for the current ‘active’ window as an integer.
getCurrentWindowDialogId() Returns the id for the current ‘active’ dialog as an integer.
class xbmcgui.Control[source]

Bases: object

Code based skin access

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

Code based skin access.

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

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

getId()[source]

Returns the control’s current id as an integer.

Returns:int - Current id

Example:

...
id = self.button.getId()
...
getX()[source]

Returns the control’s current X position.

Returns:int - Current X position

Example:

...
posX = self.button.getX()
...
getY()[source]

Returns the control’s current Y position.

Returns:int - Current Y position

Example:

...
posY = self.button.getY()
...
getHeight()[source]

Returns the control’s current height as an integer.

Returns:int - Current height

Example:

...
height = self.button.getHeight()
...
getWidth()[source]

Returns the control’s current width as an integer.

Returns:int - Current width

Example:

...
width = self.button.getWidth()
...
setEnabled(enabled)[source]

Set’s the control’s enabled/disabled state.

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

Example:

...
self.button.setEnabled(False)
...
setVisible(visible)[source]

Set’s the control’s visible/hidden state.

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

Example:

...
self.button.setVisible(False)
...
setVisibleCondition(visible, allowHiddenFocus=False)[source]

Set’s 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)[source]

Set’s 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)[source]

Set’s 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, y)[source]

Set’s the controls position.

Parameters:
  • x – integer - x coordinate of control.
  • y – integer - y coordinate of control.

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

Example:

...
self.button.setPosition(100, 250)
...
setWidth(width)[source]

Set’s the controls width.

Parameters:width – integer - width of control.

Example:

...
self.image.setWidth(100)
...
setHeight(height)[source]

Set’s the controls height.

Parameters:height – integer - height of control.

Example:

...
self.image.setHeight(100)
...
setNavigation(up, down, left, right)[source]

Set’s 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.

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

Set’s 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.

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

Example:

...
self.button.controlUp(self.button1)
...
controlDown(control)[source]

Set’s 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.

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

Example:

...
self.button.controlDown(self.button1)
...
controlLeft(control)[source]

Set’s 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.

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

Example:

...
self.button.controlLeft(self.button1)
...
controlRight(control)[source]

Set’s 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.

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

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

Code based skin access.

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

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, down, upFocus, downFocus, upDisabled, downDisabled)[source]

Set’s textures for this control.

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

Warning

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, y, width, height, label, font=None, textColor=None, disabledColor=None, alignment=0, hasPath=False, angle=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.

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 labelFlags 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 CW)

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

Returns the text value for this label.

Returns:This label

Example:

...
label = self.label.getLabel()
...
setLabel(label='', font=None, textColor=None, disabledColor=None, shadowColor=None, focusedColor=None, label2='')[source]

Set’s 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, y, width, height, label, font=None, textColor=None, disabledColor=None, _alignment=0, focusTexture=None, noFocusTexture=None, isPassword=False)[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.

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 labelFlags 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.
  • isPassword – [opt] bool - True=mask text value with ****.

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.edit = xbmcgui.ControlEdit(100, 250, 125, 75, 'Status')
...
setLabel(label='', font=None, textColor=None, disabledColor=None, shadowColor=None, focusedColor=None, label2='')[source]

Set’s 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()[source]

Returns the text heading for this edit control.

Returns:Heading text

Example:

...
label = self.edit.getLabel()
...
setText(text)[source]

Set’s text value for this edit control.

Parameters:value – string or unicode - text string.

Example:

...
self.edit.setText('online')
...
getText()[source]

Returns the text value for this edit control.

Returns:Text value of control

New function added.

Example:

...
value = self.edit.getText()
...
class xbmcgui.ControlList(x, y, width, height, font=None, textColor=None, buttonTexture=None, buttonFocusTexture=None, selectedColor=None, _imageWidth=10, _imageHeight=10, _itemTextXOffset=10, _itemTextYOffset=2, _itemHeight=27, _space=2, _alignmentY=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.

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 labelFlags 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’)

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, sendMessage=True)[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)[source]

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

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

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

Select an item by index number.

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

Example:

...
cList.selectItem(12)
...
removeItem(index)[source]

Remove an item by index number.

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

New function added.

Example:

...
cList.removeItem(12)
...
reset()[source]

Clear all ListItems in this control list.

Example:

...
cList.reset()
...
getSpinControl()[source]

Returns the associated ControlSpin object.

Warning

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

Returns the position of the selected item as an integer.

Returns -1 for empty lists.

Example:

...
pos = cList.getSelectedPosition()
...
getSelectedItem()[source]

Returns the selected item as a ListItem object.

Returns:The selected item

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, imageHeight)[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)[source]

Set’s the space between items.

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

Example:

...
cList.setSpace(5)
...
setPageControlVisible(visible)[source]

Sets the spin control’s visible/hidden state.

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

Example:

...
cList.setPageControlVisible(True)
...
size()[source]

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

Returns:Total number of items

Example:

...
cnt = cList.size()
...
getItemHeight()[source]

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

Returns:Current item heigh

Example:

..
item_height = self.cList.getItemHeight()
...
getSpace()[source]

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

Returns:Space between items

Example:

...
gap = self.cList.getSpace()
...
getListItem(index)[source]

Returns a given ListItem in this List.

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

Example:

...
listitem = cList.getListItem(6)
...
setStaticContent(items)[source]

Fills a static list with a list of listitems.

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

You can use the above as keywords for arguments.

Example:

...
cList.setStaticContent(items=listitems)
...
class xbmcgui.ControlFadeLabel(x, y, width, height, font=None, textColor=None, _alignment=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.

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 labelFlags 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

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

Add a label to this control for scrolling.

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

To remove added text use reset() for them.

Example:

...
self.fadelabel.addLabel('This is a line of text that can scroll.')
...
setScrolling(scroll)[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, y, width, height, font=None, textColor=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.

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

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')
...
setText(text)[source]

Set’s the text for this textbox.

Parameters:text – string or unicode - text string.

Example:

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

Returns the text value for this textbox.

Returns:To get text from box

Example:

...
# getText()
text = self.text.getText()
...
reset()[source]

Clear’s this textbox.

Example:

...
# reset()
self.textbox.reset()
...
scroll(id)[source]

Scrolls to the given position.

Parameters:id – integer - position to scroll to.

Example:

...
# scroll(position)
self.textbox.scroll(10)
...
autoScroll(delay, time, repeat)[source]

Set autoscrolling times.

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

New function added.

Example:

...
self.textbox.autoScroll(1, 2, 1)
...
class xbmcgui.ControlImage(x, y, width, height, filename, aspectRatio=0, colorDiffuse=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.

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

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, useCache=True)[source]

Changes the image.

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

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

Changes the images color.

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

Example:

...
# setColorDiffuse(colorDiffuse)
self.image.setColorDiffuse('0xC0FF0000')
...
class xbmcgui.ControlProgress(x, y, width, height, texturebg=None, textureleft=None, texturemid=None, textureright=None, textureoverlay=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.

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.

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

Sets the percentage of the progressbar to show.

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

valid range for percent is 0-100

Example:

...
# setPercent(percent)
self.progress.setPercent(60)
...
getPercent()[source]

Returns a float of the percent of the progress.

Returns:Percent position

Example:

...
# getPercent()
print self.progress.getPercent()
...
class xbmcgui.ControlButton(x, y, width, height, label, focusTexture=None, noFocusTexture=None, textOffsetX=10, textOffsetY=2, alignment=4, font=None, textColor=None, disabledColor=None, angle=0, shadowColor=None, focusedColor=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.

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 labelFlags 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’)

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='', font=None, textColor=None, disabledColor=None, shadowColor=None, focusedColor=None, label2='')[source]

Set’s 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.

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

Set’s this buttons disabled color.

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

Example:

...
# setDisabledColor(disabledColor)
self.button.setDisabledColor('0xFFFF3300')
...
getLabel()[source]

Returns the buttons label as a unicode string.

Returns:Unicode string

Example:

...
# getLabel()
label = self.button.getLabel()
...
getLabel2()[source]

Returns the buttons label2 as a unicode string.

Returns:Unicode string of label 2

Example:

...
# getLabel2()
label = self.button.getLabel2()
...
class xbmcgui.ControlGroup(x, y, width, height)[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.

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, y, width, height, label, focusOnTexture=None, noFocusOnTexture=None, focusOffTexture=None, noFocusOffTexture=None, focusTexture=None, noFocusTexture=None, textOffsetX=10, textOffsetY=2, _alignment=4, font=None, textColor=None, disabledColor=None, angle=0, shadowColor=None, focusedColor=None, disabledOnTexture=None, disabledOffTexture=None)[source]

Bases: xbmcgui.Control

For control a radio button (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. When the user clicks on the radio button, the state will change, toggling the extra textures (textureradioon and textureradiooff). Used for settings controls.

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 radio ON texture (deprecated, use focusOnTexture and noFocusOnTexture).
  • noFocusTexture – [opt] string - filename for radio OFF texture (deprecated, use focusOffTexture and noFocusOffTexture).
  • textOffsetX – [opt] integer - horizontal text offset
  • textOffsetY – [opt] integer - vertical text offset
  • alignment – [opt] integer - alignment of labelFlags 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’)

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

New function added. Deprecated focusTexture and noFocusTexture. Use focusOnTexture and noFocusOnTexture.

Example:

...
self.radiobutton = xbmcgui.ControlRadioButton(100, 250, 200, 50, 'Enable', font='font14')
...
setSelected(selected)[source]

Sets the radio buttons’s selected status

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

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

Returns the radio buttons’s selected status.

Returns:True if selected on

Example:

...
is = self.radiobutton.isSelected()
...
setLabel(label='', font=None, textColor=None, disabledColor=None, shadowColor=None, focusedColor=None, label2='')[source]

Set’s 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’)

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, y, width, height)[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.

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, y, width, height, textureback=None, texture=None, texturefocus=None, orientation=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.

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

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

orientation option added.

Example:

...
self.slider = xbmcgui.ControlSlider(100, 250, 350, 40)
...
getPercent()[source]

Returns a float of the percent of the slider.

Returns:float - Percent of slider

Example:

...
print self.slider.getPercent()
...
setPercent(pct)[source]

Sets the percent of the slider.

Parameters:pct – float - Percent value of slider

Example:

...
self.slider.setPercent(50)
...
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, line1, line2='', line3='', nolabel='', yeslabel='', autoclose=0)[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.
  • line1 – string or unicode - line #1 multi-line text.
  • line2 – [opt] string or unicode - line #2 text.
  • line3 – [opt] string or unicode - line #3 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.

It is preferred to only use line1 as it is actually a multi-line text. In this case line2 and line3 must be omitted.

Added new option autoclose.

Example:

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

Info dialog

Show the corresponding info dialog for a given listitem

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

New function added.

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.info(listitem)
..
select(heading, list, autoclose=0, preselect=-1, useDetails=False)[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.

preselect option added. Added new option useDetails. Allow listitems for parameter list

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.select('Choose a playlist', ['Playlist #1', 'Playlist #2, 'Playlist #3'])
..
contextmenu(list)[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).

New function added

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.contextmenu(['Option #1', 'Option #2', 'Option #3'])
..
multiselect(heading, options, autoclose=0, preselect=None, useDetails=False)[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.

New function added. Added new option preselect. Added new option useDetails. Allow listitems for parameter options

Example:

..
dialog = xbmcgui.Dialog()
ret = dialog.multiselect("Choose something", ["Foo", "Bar", "Baz"], preselect=[1,2])
..
ok(heading, line1, line2='', line3='')[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.
  • line1 – string or unicode - line #1 multi-line text.
  • line2 – [opt] string or unicode - line #2 text.
  • line3 – [opt] string or unicode - line #3 text.
Returns:

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

It is preferred to only use line1 as it is actually a multi-line text. In this case line2 and line3 must be omitted.

Example:

..
dialog = xbmcgui.Dialog()
ok = dialog.ok('Kodi', 'There was an error.')
..
textviewer(heading, text)[source]

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

New function added.

Example:

..
dialog = xbmcgui.Dialog()
dialog.textviewer('Plot', 'Some movie plot.')
..
browse(type, heading, shares, mask='', useThumbs=False, treatAsFolder=False, defaultt='', enableMultiple=False)[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 - from sources.xml . (i.e. ‘myprograms’)
  • 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 strin 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

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browse(3, 'Kodi', 'files', '', False, False, False,
                'special://masterprofile/script_data/Kodi Lyrics')
..
browseSingle(type, heading, shares, mask='', useThumbs=False, treatAsFolder=False, defaultt='')[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 - from sources.xml . (i.e. ‘myprograms’)
  • 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.

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browseSingle(3, 'Kodi', 'files', '', False, False,
                'special://masterprofile/script_data/Kodi Lyrics')
..
browseMultiple(type, heading, shares, mask='', useThumbs=False, treatAsFolder=False, defaultt='')[source]

Browser dialog

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

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

Parameters:type – integer - the type of browse dialog.
Param Name
1 ShowAndGetFile
2 ShowAndGetImage
Parameters:
  • heading – string or unicode - dialog heading.
  • shares – string or unicode - from sources.xml . (i.e. ‘myprograms’)
  • 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.

Example:

..
dialog = xbmcgui.Dialog()
fn = dialog.browseMultiple(2, 'Kodi', 'files', '', False, False,
                'special://masterprofile/script_data/Kodi Lyrics')
..
numeric(type, heading, defaultt='')[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: #.#.#.#)
Parameters:
  • heading – string or unicode - dialog heading.
  • defaultt – [opt] string - default value.
Returns:

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

Example:

..
dialog = xbmcgui.Dialog()
d = dialog.numeric(1, 'Enter date of birth')
..
notification(heading, message, icon='', time=0, sound=True)[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

New function added.

Example:

..
dialog = xbmcgui.Dialog()
dialog.notification('Movie Trailers', 'Finding Nemo download finished.',
                    xbmcgui.NOTIFICATION_INFO, 5000)
..
input(heading, defaultt='', type=0, option=0, autoclose=0)[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.

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

create(heading, line1='', line2='', line3='')[source]

Create and show a progress dialog.

Parameters:
  • heading – string or unicode - dialog heading.
  • line1 – [opt] string or unicode - line #1 multi-line text.
  • line2 – [opt] string or unicode - line #2 text.
  • line3 – [opt] string or unicode - line #3 text.

It is preferred to only use line1 as it is actually a multi-line text. In this case line2 and line3 must be omitted.

Use update() to update lines and progressbar.

Example:

..
pDialog = xbmcgui.DialogProgress()
pDialog.create('Kodi', 'Initializing script...')
..
update(percent, line1='', line2='', line3='')[source]

Updates the progress dialog.

Parameters:
  • percent – integer - percent complete. (0:100)
  • line1 – [opt] string or unicode - line #1 multi-line text.
  • line2 – [opt] string or unicode - line #2 text.
  • line3 – [opt] string or unicode - line #3 text.

It is preferred to only use line1 as it is actually a multi-line text. In this case line2 and line3 must be omitted.

Example:

..
pDialog.update(25, 'Importing modules...')
..
close()[source]

Close the progress dialog.

Example:

..
pDialog.close()
..
iscanceled()[source]

Checks progress is canceled.

Returns:True if the user pressed cancel.

Example:

..
if (pDialog.iscanceled()): return
..
class xbmcgui.DialogBusy[source]

Bases: object

Kodi’s busy dialog class

New class added.
create()[source]

Create and show a busy dialog.

Use update() to update the progressbar.

New method added

Example:

..
dialog = xbmcgui.DialogBusy()
dialog.create()
..
update(percent)[source]

Updates the busy dialog.

Parameters:percent – integer - percent complete. (-1:100)

If percent == -1 (default), the progressbar will be hidden.

New method added

close()[source]

Close the progress dialog.

New method added

iscanceled()[source]

Checks if busy dialog is canceled.

Returns:True if the user pressed cancel.

New method added

class xbmcgui.DialogProgressBG[source]

Bases: object

Kodi’s background progress dialog class

create(heading, message='')[source]

Create and show a background progress dialog.

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

‘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=0, heading='', message='')[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.

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

Example:

..
pDialog.update(25, message='Downloading Finding Nemo ...')
..
close()[source]

Close the background progress dialog

Example:

..
pDialog.close()
..
isFinished()[source]

Checks progress is finished

Returns:True if the background dialog is active.

Example:

..
if (pDialog.isFinished()): return
..
class xbmcgui.ListItem(label='', label2='', iconImage='', thumbnailImage='', path='')[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
  • iconImageDeprecated. Use setArt
  • thumbnailImageDeprecated. Use setArt
  • path – [opt] string

Note

iconImage and thumbnailImage are deprecated. Use setArt().

Example:

...
listitem = xbmcgui.ListItem('Casino Royale')
...
getLabel()[source]

Returns the listitem label.

Returns:Label of item

Example:

...
# getLabel()
label = listitem.getLabel()
...
getLabel2()[source]

Returns the second listitem label.

Returns:Second label of item

Example:

...
# getLabel2()
label = listitem.getLabel2()
...
setLabel(label)[source]

Sets the listitem’s label.

Parameters:label – string or unicode - text string.

Example:

...
# setLabel(label)
listitem.setLabel('Casino Royale')
...
setLabel2(label)[source]

Sets the listitem’s label2.

Parameters:label – string or unicode - text string.

Example:

...
# setLabel2(label)
listitem.setLabel2('Casino Royale')
...
setIconImage(iconImage)[source]

Deprecated. Use setArt().

setThumbnailImage(thumbFilename)[source]

Warning

Deprecated. Use setArt().

setArt(dictionary)[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

New function added. Added new label icon.

Example:

...
# setArt(values)
listitem.setArt(``'poster': 'poster.png', 'banner' : 'banner.png'``)
...
setUniqueIDs(dictionary)[source]

Sets the listitem’s uniqueID

Parameters:values – dictionary - pairs of label: value. 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)
listitem.setUniqueIDs(``'imdb': 'tt8938399', 'tmdb' : '9837493'``)
...
setRating(type, rating, votes=0, defaultt=False)[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)
...
getArt(key)[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

New function added.

Example:

...
poster = listitem.getArt('poster')
...
getUniqueID(key)[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)[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)[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)[source]

Sets the listitem’s selected status.

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

Example:

...
# select(selected)
listitem.select(True)
...
isSelected()[source]

Returns the listitem’s selected status.

Returns:bool - true if selected, otherwise false

Example:

...
# isSelected()
selected = listitem.isSelected()
...
setInfo(type, infoLabels)[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 informantion

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)
country string (Germany)
year integer (2009)
episode integer (4)
season integer (1)
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)
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.)
tagline string (An awesome movie) - short description of movie
writer string (Robert D. Siegel)
tvshowtitle string (Heroes)
premiered string (2005-03-04)
status string (Continuing) - status of a TVshow
set string (Batman Collection) - name of the collection
imdbnumber string (tt0110293) - IMDb code
code string (101) - Production code
aired string (2008-12-07)
credits string (Andy Kaufman) - 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”
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)

Added new label discnumber. duration has to be set in seconds. Added new label mediatype. Added labels setid, set, imdbnumber, code, dbid, path and userrating. Expanded the possible infoLabels for the option mediatype.

Example:

...
listitem.setInfo('video', ``'genre': 'Comedy'``)
...
setCast(actors)[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)

New function added.

Example:

...
actors = [{"name": "Actor 1", "role": "role 1"},
          {"name": "Actor 2", "role": "role 2"}]
listitem.setCast(actors)
...
addStreamInfo(cType, dictionary)[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, replaceItems=False)[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 built-in function to perform.

List of functions - http://kodi.wiki/view/List_of_Built_In_Functions

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.

Completely removed option replaceItems.

Example:

...
listitem.addContextMenuItems(
    [('Theater Showtimes',
    'RunScript(special://home/scripts/showtimes/default.py,Iron Man)',)]
    )
...
setProperty(key, value)[source]

Sets a listitem property, similar to an infolabel.

Parameters:
  • key – string - property name.
  • value – string or unicode - value of property.

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

Example:

...
listitem.setProperty('AspectRatio', '1.85 : 1')
listitem.setProperty('StartOffset', '256.4')
...
getProperty(key)[source]

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

Parameters:key – string - property name.

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

Sets the listitem’s path.

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

You can use the above as keywords for arguments.

Example:

...
listitem.setPath(path='/path/to/some/file.ext')
...
setMimeType(mimetype)[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)[source]

Enable or disable content lookup for item.

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

enable bool to enable content lookup

New function added.

setSubtitles(subtitleFiles)[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'])
  ...
New function added. 
getdescription()[source]

Warning

Deprecated.

getduration()[source]

Warning

Deprecated. Use InfoTagMusic.

getfilename()[source]

Warning

Deprecated.

getPath()[source]

Returns the path of this listitem.

[string] filename

New function added.

getVideoInfoTag()[source]

Returns the VideoInfoTag for this item.

video info tag

New function added.

getMusicInfoTag()[source]

Returns the MusicInfoTag for this item.

music info tag

New function added.

class xbmcgui.Action[source]

Bases: object

Action class

xbmcgui.Action():

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()[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 recieved: previous')
..
getButtonCode()[source]

Returns the button code for this action.

Returns:[integer] button code
getAmount1()[source]

Returns the first amount of force applied to the thumbstick.

Returns:[float] first amount
getAmount2()[source]

Returns the second amount of force applied to the thumbstick.

Returns:[float] second amount
class xbmcgui.Window(existingWindowId=-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 window

xbmcgui.Window([existingWindowId]):

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

Parameters:

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

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

Show this window.

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

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

Give the supplied control focus.

Parameters:

Control – Control class to focus

Raises:
  • TypeError – If supplied argument is not a Control type
  • SystemError – On Internal error
  • RuntimeError – If control is not added to a window
setFocusId(iControlId)[source]

Gives the control with the supplied focus.

Parameters:

ControlId – [integer] On skin defined id of control

Raises:
  • SystemError – On Internal error
  • RuntimeError – If control is not added to a window
getFocus()[source]

Returns the control which is focused.

Returns:

Focused control class

Raises:
  • SystemError – On Internal error
  • RuntimeError – If no control has focus
getFocusId()[source]

Returns the id of the control which is focused.

Returns:

Focused control id

Raises:
  • SystemError – On Internal error
  • RuntimeError – If no control has focus
removeControl(pControl)[source]

Removes the control from this window.

Parameters:

Control – Control class to remove

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

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

removeControls(pControls)[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()[source]

Returns the height of this screen.

Returns:Screen height
getWidth()[source]

Returns the width of this screen.

Returns:Screen width
getResolution()[source]

Returns The resolution of the screen

Returns:Used Resolution The returned value is one of the following:
value Resolution
0 1080i (1920x1080)
1 720p (1280x720)
2 480p 4:3 (720x480)
3 480p 16:9 (720x480)
4 NTSC 4:3 (720x480)
5 NTSC 16:9 (720x480)
6 PAL 4:3 (720x576)
7 PAL 16:9 (720x576)
8 PAL60 4:3 (720x480)
9 PAL60 16:9 (720x480)
setCoordinateResolution(res)[source]

Sets the resolution

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

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

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
win.setCoordinateResolution(0)
..
setProperty(key, value)[source]

Sets a window property, similar to an infolabel.

Parameters:
  • key – string - property name.
  • value – string or unicode - value of property.

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

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

Parameters:key – string - property name.

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

Clears the specific window property.

Parameters:key – string - property name.

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

Clears all window properties.

Example:

..
win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
win.clearProperties()
..
close()[source]

Closes this window.

Closes this window by activating the old window.

The window is not deleted with this method.

doModal()[source]

Display this window until close() is called.

addControl(pControl)[source]

Add a Control to this window.

Parameters:

Control – Control to add

Raises:
  • TypeError – If supplied argument is not a Control type
  • ReferenceError – If control is already used in another window
  • RuntimeError – Should not happen :-)

The next controls can be added to a window atm

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

Gets the control from this window.

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

controlId doesn’t have to be a python control, it can be a control id from a Kodi window too (you can find id’s in the xml files.

Not python controls are not completely usable yet You can only use the Control functions

class xbmcgui.WindowDialog[source]

Bases: xbmcgui.Window

GUI window dialog class for Add-Ons

xbmcgui.WindowDialog(int windowId):

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, scriptPath, defaultSkin='Default', defaultRes='720p')[source]

Bases: xbmcgui.Window

GUI xml window class

Creates a new xml file based window class.

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’).decode(‘utf-8’))
  • 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. (default=‘720p’)
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.

Example:

..
win = xbmcgui.WindowXML('script-Lyrics-main.xml',
        xbmcaddon.Addon().getAddonInfo('path').decode('utf-8'),
        'default', '1080p')
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, position=9223372036854775807)[source]

Add a new item to this WindowList.

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

Add a list of items to to the window list.

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

Example:

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

Removes a specified item based on position, from the WindowList.

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

Example:

..
self.removeItem(5)
..
getCurrentListPosition()[source]

Gets the current position in the WindowList.

Example:

..
pos = self.getCurrentListPosition()
..
setCurrentListPosition(position)[source]

Set the current position in the WindowList.

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

Example:

..
self.setCurrentListPosition(5)
..
getListItem(position)[source]

Returns a given ListItem in this WindowList.

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

Example:

..
listitem = self.getListItem(6)
..
getListSize()[source]

Returns the number of items in this WindowList.

Example:

..
listSize = self.getListSize()
..
clearList()[source]

Clear the WindowList.

Example:

..
self.clearList()
..
setContainerProperty(strProperty, strValue)[source]

Sets a container property, similar to an infolabel.

Parameters:
  • key – string - property name.
  • value – string or unicode - value of property.

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.

Changed function from setProperty to setContainerProperty.

Example:

..
self.setContainerProperty('Category', 'Newest')
..
getCurrentContainerId()[source]

Get the id of the currently visible container.

Added new function.

Example:

..
container_id = self.getCurrentContainerId()
..
class xbmcgui.WindowXMLDialog(xmlFilename, scriptPath, defaultSkin='Default', defaultRes='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’).decode(‘utf-8’))
  • 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. (default=‘720p’)
Raises:

Exception – if more then 200 windows are created.

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

Example:

..
dialog = xbmcgui.WindowXMLDialog('script-Lyrics-main.xml',
    xbmcaddon.Addon().getAddonInfo('path').decode('utf-8'),
    'default', '1080p')
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()[source]

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

Returns:The currently active window Id

Example:

..
wid = xbmcgui.getCurrentWindowId()
..
xbmcgui.getCurrentWindowDialogId()[source]

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

Returns:The currently active dialog Id

Example:

..
wid = xbmcgui.getCurrentWindowDialogId()
..