xbmcgui

GUI functions on Kodi.

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

Classes

Control() Base Control class
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 (Duh!)
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.
getScreenHeight() Returns the height of this screen.
getScreenWidth() Returns the width of this screen.
class xbmcgui.Control[source]

Bases: object

Base Control class

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

Get the control’s visible/hidden state.

New function added.

Example:

if self.button.isVisible():
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: <https://kodi.wiki/view/List_of_boolean_conditions>

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

Example:

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

Set’s the control’s enabled condition.

Allows Kodi to control the enabled status of the control.

List of Conditions: <https://kodi.wiki/view/List_of_boolean_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 **** (deprecated, use setType()).

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

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()
setType(type, heading)[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)
Parameters:heading – string or unicode - heading that will be used for to numeric or keyboard dialog when the edit control is clicked.

New function added.

Example:

self.edit.setType(xbmcgui.INPUT_TYPE_TIME, 'Please enter the time')
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

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

Note

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

Returns the value of the slider.

Returns:int - value of slider

New function added.

Example:

print(self.slider.getInt())
setInt(value, min, delta, max)[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

New function added.

Example:

self.slider.setInt(450, 200, 10, 900)
getFloat()[source]

Returns the value of the slider.

Returns:float - value of slider

New function added.

Example:

print(self.slider.getFloat())
setFloat(value, min, delta, max)[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

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, 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, usemono=False)[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

New function added. New optional param added usemono.

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

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

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

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, 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 (Duh!)

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

Warning

removed, usage results in nop!

create()[source]

Create and show a busy dialog.

Use update() to update the progressbar.

removed, usage results in nop!

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.

Warning

removed, usage results in nop!

close()[source]

Close the progress dialog.

Warning

removed, usage results in nop!

iscanceled()[source]

Checks if busy dialog is canceled.

Returns:True if the user pressed cancel.

Warning

removed, usage results in nop!

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='', offscreen=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
  • iconImageDeprecated. Use setArt
  • thumbnailImageDeprecated. Use setArt
  • path – [opt] string

Warning

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]

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' })
setIsFolder(isFolder)[source]

Sets if this listitem is a folder.

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

New function added.

Example:

# setIsFolder(isFolder)
listitem.setIsFolder(True)
setUniqueIDs(dictionary, defaultrating='')[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, 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)
addSeason(number, name='')[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 “”.

New function added.

Example:

# addSeason(number, name))
listitem.addSeason(1, "Murder House")
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 informanion
game Game information

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)
  • 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.
  • Added new game type and associated infolabels.
  • Added labels 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)[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)
setAvailableFanart(images)[source]

Set available images (needed for 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|"))

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, art_type='', referrer='', cache='', post=False, isgz=False, season=-1)[source]

Add an image to available artworks (needed for scrapers)

Parameters:
  • url – string (image path url)
  • art_type – string (image type)
  • 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)

New function added.

Example:

listitem.addAvailableArtwork(path_to_image_1, "thumb")
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 available built-in function .

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.

Note

Completely removed previously available argument 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')
setProperties(dictionary)[source]

Sets multiple properties for listitem’s

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

New function added. Example:

# setProperties(values)
listitem.setProperties({ 'AspectRatio': '1.85', '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.

Parameters: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.

Returns:[string] filename

New function added.

getVideoInfoTag()[source]

Returns the VideoInfoTag for this item.

Returns:video info tag

New function added.

getMusicInfoTag()[source]

Returns the MusicInfoTag for this item.

Returns:music info tag

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

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 will 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 Window instance.

Returns:Window height in pixels Function changed
getWidth()[source]

Returns the width of this Window instance.

Returns:Window width in pixels Function changed
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)

Note

Deprecated.

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)

Note

Deprecated.

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

onAction(action)[source]

onAction method

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

Parameters:action – The action id to perform, see Action to get use of them

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

onClick method

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

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

onDoubleClick method

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

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

onFocus method

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

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

onInit method

This method will be called to initialize the window

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, scriptPath, defaultSkin='Default', defaultRes='720p', isMedia=False)[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’)
  • 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.

New param added isMedia.

Example:

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

Added new function.

Example:

self.setContent('movies')
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()
xbmcgui.getScreenHeight()[source]

Returns the height of this screen.

Returns:Screen height New function added.
xbmcgui.getScreenWidth()[source]

Returns the width of this screen.

Returns:Screen width New function added.