Kodi's dialog class More...

Classes
class	XBMCAddon::xbmcgui::Dialog

Functions
	XBMCAddon::xbmcgui::Dialog::yesno (...)

	XBMCAddon::xbmcgui::Dialog::info (...)

	XBMCAddon::xbmcgui::Dialog::select (...)

	XBMCAddon::xbmcgui::Dialog::contextmenu (...)

	XBMCAddon::xbmcgui::Dialog::multiselect (...)

	XBMCAddon::xbmcgui::Dialog::ok (...)

	XBMCAddon::xbmcgui::Dialog::textviewer (...)

	XBMCAddon::xbmcgui::Dialog::browse (...)

	XBMCAddon::xbmcgui::Dialog::browseSingle (...)

	XBMCAddon::xbmcgui::Dialog::browseMultiple (...)

	XBMCAddon::xbmcgui::Dialog::numeric (...)

	XBMCAddon::xbmcgui::Dialog::notification (...)

	XBMCAddon::xbmcgui::Dialog::input (...)

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.

Function Documentation

§ browse()

Alternative< String, std::vector< String > > XBMCAddon::xbmcgui::Dialog::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')
..

§ browseMultiple()

std::vector< String > XBMCAddon::xbmcgui::Dialog::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')
..

§ browseSingle()

String XBMCAddon::xbmcgui::Dialog::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')
..

§ contextmenu()

int XBMCAddon::xbmcgui::Dialog::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'])
..

§ info()

bool XBMCAddon::xbmcgui::Dialog::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)
..

§ input()

String XBMCAddon::xbmcgui::Dialog::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)
..

§ multiselect()

std::unique_ptr< std::vector< int > > XBMCAddon::xbmcgui::Dialog::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])
..

§ notification()

void XBMCAddon::xbmcgui::Dialog::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)
..

§ numeric()

String XBMCAddon::xbmcgui::Dialog::numeric ( ... )

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

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

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

§ ok()

bool XBMCAddon::xbmcgui::Dialog::ok ( ... )

`Function: xbmcgui.Dialog().ok(heading, line1[, line2, line3])`

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.

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

§ select()

int XBMCAddon::xbmcgui::Dialog::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'])
..

§ textviewer()

void XBMCAddon::xbmcgui::Dialog::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.')
..

§ yesno()

bool XBMCAddon::xbmcgui::Dialog::yesno ( ... )

`Function: xbmcgui.Dialog().yesno(heading, line1[, line2, line3, 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.
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.

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

v13 Python API changes:: Added new option autoclose.

Example:

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

Classes

Functions

Detailed Description

Function Documentation

§ browse()

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

§ browseMultiple()

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

§ browseSingle()

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

§ contextmenu()

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

§ info()

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

§ input()

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

§ multiselect()

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

§ notification()

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

§ numeric()

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

§ ok()

Function: xbmcgui.Dialog().ok(heading, line1[, line2, line3])

§ select()

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

§ textviewer()

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

§ yesno()

Function: xbmcgui.Dialog().yesno(heading, line1[, line2, line3, nolabel, yeslabel, autoclose])

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

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

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

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

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

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

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

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

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

`Function: xbmcgui.Dialog().ok(heading, line1[, line2, line3])`

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

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

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