Kodi Development  20.0
for Binary and Script based Add-Ons

Detailed Description

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.

Modules

 DialogProgress
 Kodi's progress dialog class (Duh!)
 

Function Documentation

◆ yesno()

yesno (   ...)

Function: xbmcgui.Dialog().yesno(heading, message, [nolabel, yeslabel, autoclose])


Yes / no dialog

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

Parameters
headingstring or unicode - dialog heading.
messagestring or unicode - message text.
nolabel[opt] label to put on the no button.
yeslabel[opt] label to put on the yes button.
autoclose[opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
defaultbutton[opt] integer - specifies the default focused button. (default=DLG_YESNO_NO_BTN)
Value: Description:
xbmcgui.DLG_YESNO_NO_BTN Set the "No" button as default.
xbmcgui.DLG_YESNO_YES_BTN Set the "Yes" button as default.
xbmcgui.DLG_YESNO_CUSTOM_BTN Set the "Custom" button as default.
Returns
Returns True if 'Yes' was pressed, else False.

v13 Python API changes:
Added new option autoclose.
v19 Python API changes:

Renamed option line1 to message.

Removed option line2.

Removed option line3.

v20 Python API changes:
Added new option defaultbutton.

Example:

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

◆ yesnocustom()

yesnocustom (   ...)

Function: xbmcgui.Dialog().yesnocustom(heading, message, customlabel, [nolabel, yeslabel, autoclose])


Yes / no / custom dialog

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

Parameters
headingstring or unicode - dialog heading.
messagestring or unicode - message text.
customlabelstring or unicode - label to put on the custom button.
nolabel[opt] label to put on the no button.
yeslabel[opt] label to put on the yes button.
autoclose[opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)
defaultbutton[opt] integer - specifies the default focused button. (default=DLG_YESNO_NO_BTN)
Value: Description:
xbmcgui.DLG_YESNO_NO_BTN Set the "No" button as default.
xbmcgui.DLG_YESNO_YES_BTN Set the "Yes" button as default.
xbmcgui.DLG_YESNO_CUSTOM_BTN Set the "Custom" button as default.
Returns
Returns the integer value for the selected button (-1:cancelled, 0:no, 1:yes, 2:custom)

v19 Python API changes:
New function added.
v20 Python API changes:
Added new option defaultbutton.

Example:

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

◆ info()

info (   ...)

Function: xbmcgui.Dialog().info(listitem)


Info dialog

Show the corresponding info dialog for a given listitem

Parameters
listitemxbmcgui.ListItem - ListItem to show info for.
Returns
Returns whether the dialog opened successfully.

v17 Python API changes:
New function added.

Example:

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

◆ select()

select (   ...)

Function: xbmcgui.Dialog().select(heading, list[, autoclose, preselect, useDetails])


Select dialog

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

Parameters
headingstring or unicode - dialog heading.
listlist 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.

v17 Python API changes:

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

contextmenu (   ...)

Function: xbmcgui.Dialog().contextmenu(list)


Show a context menu.

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

v17 Python API changes:
New function added

Example:

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

◆ multiselect()

multiselect (   ...)

Function: xbmcgui.Dialog().multiselect(heading, options[, autoclose, preselect, useDetails])


Show a multi-select dialog.

Parameters
headingstring or unicode - dialog heading.
optionslist 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.

v16 Python API changes:
New function added.
v17 Python API changes:

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

ok (   ...)

Function: xbmcgui.Dialog().ok(heading, message)


OK dialog

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

Parameters
headingstring or unicode - dialog heading.
messagestring or unicode - message text.
Returns
Returns True if 'Ok' was pressed, else False.

v19 Python API changes:

Renamed option line1 to message.

Removed option line2.

Removed option line3.

Example:

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

◆ textviewer()

textviewer (   ...)

Function: xbmcgui.Dialog().textviewer(heading, text, usemono)


TextViewer dialog

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

Parameters
headingstring or unicode - dialog heading.
textstring or unicode - text.
usemono[opt] bool - use monospace font

v16 Python API changes:
New function added.
v18 Python API changes:
New optional param added usemono.

Example:

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

◆ browse()

browse (   ...)

Function: xbmcgui.Dialog().browse(type, heading, shares[, mask, useThumbs, treatAsFolder, defaultt, enableMultiple])


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
typeinteger - the type of browse dialog.
Param Name
0 ShowAndGetDirectory
1 ShowAndGetFile
2 ShowAndGetImage
3 ShowAndGetWriteableDirectory
headingstring or unicode - dialog heading.
sharesstring 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
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

v18 Python API changes:
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()

browseSingle (   ...)

Function: xbmcgui.Dialog().browseSingle(type, heading, shares[, mask, useThumbs, treatAsFolder, defaultt])


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
typeinteger - the type of browse dialog.
Param Name
0 ShowAndGetDirectory
1 ShowAndGetFile
2 ShowAndGetImage
3 ShowAndGetWriteableDirectory
headingstring or unicode - dialog heading.
sharesstring 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
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.

v18 Python API changes:
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()

browseMultiple (   ...)

Function: xbmcgui.Dialog().browseMultiple(type, heading, shares[, mask, useThumbs, treatAsFolder, defaultt])


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
typeinteger - the type of browse dialog.
Param Name
1 ShowAndGetFile
2 ShowAndGetImage
headingstring or unicode - dialog heading.
sharesstring 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
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.

v18 Python API changes:
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()

numeric (   ...)

Function: xbmcgui.Dialog().numeric(type, heading[, defaultt, bHiddenInput])


Numeric dialog

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

Parameters
typeinteger - the type of numeric dialog.
Param Name Format
0 ShowAndGetNumber (default format: #)
1 ShowAndGetDate (default format: DD/MM/YYYY)
2 ShowAndGetTime (default format: HH:MM)
3 ShowAndGetIPAddress (default format: #.#.#.#)
4 ShowAndVerifyNewPassword (default format: *)
headingstring or unicode - dialog heading (will be ignored for type 4).
defaultt[opt] string - default value.
bHiddenInput[opt] bool - mask input (available for type 0).
Returns
Returns the entered data as a string. Returns the default value if dialog was canceled.

v19 Python API changes:

New option added ShowAndVerifyNewPassword.

Added new option bHiddenInput.

Example:

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

◆ notification()

notification (   ...)

Function: xbmcgui.Dialog().notification(heading, message[, icon, time, sound])


Show a Notification alert.

Parameters
headingstring - dialog heading.
messagestring - 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

v13 Python API changes:
New function added.

Example:

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

◆ input()

input (   ...)

Function: xbmcgui.Dialog().input(heading[, defaultt, type, option, autoclose])


Show an Input dialog.

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

v13 Python API changes:
New function added.

Example:

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

◆ colorpicker()

colorpicker (   ...)

Function: xbmcgui.Dialog().colorpicker(heading[, colorfile, colorlist, selectedcolor])


Show a color selection dialog.

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

v20 Python API changes:
New function added.

Example:

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