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.

Topics
	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

heading string or unicode - dialog heading.

message string or unicode - message text.

nolabel [opt] label to put on the no button.

yeslabel [opt] label to put on the yes button.

autoclose [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)

defaultbutton

[opt] integer - specifies the default focused button. (default=DLG_YESNO_NO_BTN)

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

Returns: Returns True if 'Yes' was pressed, else False.

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

heading string or unicode - dialog heading.

message string or unicode - message text.

customlabel string or unicode - label to put on the custom button.

nolabel [opt] label to put on the no button.

yeslabel [opt] label to put on the yes button.

autoclose [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)

defaultbutton

[opt] integer - specifies the default focused button. (default=DLG_YESNO_NO_BTN)

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

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

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

listitem xbmcgui.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

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.

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

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

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.

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

heading	string or unicode - dialog heading.
message	string 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

heading	string or unicode - dialog heading.
text	string 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

type

integer - the type of browse dialog.

Param	Name
0	ShowAndGetDirectory
1	ShowAndGetFile
2	ShowAndGetImage
3	ShowAndGetWriteableDirectory

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

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

type

integer - the type of browse dialog.

Param	Name
0	ShowAndGetDirectory
1	ShowAndGetFile
2	ShowAndGetImage
3	ShowAndGetWriteableDirectory

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

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

type

integer - the type of browse dialog.

Param	Name
1	ShowAndGetFile
2	ShowAndGetImage

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

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

type

integer - the type of numeric dialog.

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

heading string or unicode - dialog heading (will be ignored for type 4).

defaultt [opt] string - default value.

bHiddenInput [opt] bool - mask input (available for type 0).

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

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

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

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

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)

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

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

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

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

Detailed Description

Topics

Function Documentation

◆ yesno()

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

◆ yesnocustom()

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

◆ info()

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

◆ select()

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

◆ contextmenu()

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

◆ multiselect()

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

◆ ok()

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

◆ textviewer()

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

◆ browse()

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

◆ browseSingle()

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

◆ browseMultiple()

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

◆ numeric()

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

◆ notification()

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

◆ input()

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

◆ colorpicker()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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