Kodi Documentation  19.0
Kodi is an open source media player and entertainment hub.

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

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

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

§ contextmenu()

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

§ info()

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

§ input()

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

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

§ notification()

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

§ 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
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: #.#.#.#)
headingstring 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
headingstring or unicode - dialog heading.
line1string 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
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'])
..

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

§ 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
headingstring or unicode - dialog heading.
line1string 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?')
..