# This file is generated from Kodi source code and post-edited
# to correct code style and docstrings formatting.
# License: GPL v.3 <https://www.gnu.org/licenses/gpl-3.0.en.html>
"""
**Plugin functions on Kodi.**
Offers classes and functions that allow a developer to present information
through Kodi's standard menu structure. While plugins don't have the same
flexibility as scripts, they boast significantly quicker development time and a
more consistent user experience.
"""
from typing import List, Tuple, Optional
__kodistubs__ = True
SORT_METHOD_ALBUM = 14
SORT_METHOD_ALBUM_IGNORE_THE = 15
SORT_METHOD_ARTIST = 11
SORT_METHOD_ARTIST_IGNORE_THE = 13
SORT_METHOD_BITRATE = 43
SORT_METHOD_CHANNEL = 41
SORT_METHOD_COUNTRY = 17
SORT_METHOD_DATE = 3
SORT_METHOD_DATEADDED = 21
SORT_METHOD_DATE_TAKEN = 44
SORT_METHOD_DRIVE_TYPE = 6
SORT_METHOD_DURATION = 8
SORT_METHOD_EPISODE = 24
SORT_METHOD_FILE = 5
SORT_METHOD_FULLPATH = 35
SORT_METHOD_GENRE = 16
SORT_METHOD_LABEL = 1
SORT_METHOD_LABEL_IGNORE_FOLDERS = 36
SORT_METHOD_LABEL_IGNORE_THE = 2
SORT_METHOD_LASTPLAYED = 37
SORT_METHOD_LISTENERS = 39
SORT_METHOD_MPAA_RATING = 31
SORT_METHOD_NONE = 0
SORT_METHOD_PLAYCOUNT = 38
SORT_METHOD_PLAYLIST_ORDER = 23
SORT_METHOD_PRODUCTIONCODE = 28
SORT_METHOD_PROGRAM_COUNT = 22
SORT_METHOD_SIZE = 4
SORT_METHOD_SONG_RATING = 29
SORT_METHOD_SONG_USER_RATING = 30
SORT_METHOD_STUDIO = 33
SORT_METHOD_STUDIO_IGNORE_THE = 34
SORT_METHOD_TITLE = 9
SORT_METHOD_TITLE_IGNORE_THE = 10
SORT_METHOD_TRACKNUM = 7
SORT_METHOD_UNSORTED = 40
SORT_METHOD_VIDEO_ORIGINAL_TITLE = 49
SORT_METHOD_VIDEO_ORIGINAL_TITLE_IGNORE_THE = 50
SORT_METHOD_VIDEO_RATING = 19
SORT_METHOD_VIDEO_RUNTIME = 32
SORT_METHOD_VIDEO_SORT_TITLE = 26
SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE = 27
SORT_METHOD_VIDEO_TITLE = 25
SORT_METHOD_VIDEO_USER_RATING = 20
SORT_METHOD_VIDEO_YEAR = 18
[docs]
def addDirectoryItem(handle: int,
url: str,
listitem: 'xbmcgui.ListItem',
isFolder: bool = False,
totalItems: int = 0) -> bool:
"""
Callback function to pass directory contents back to Kodi.
:param handle: integer - handle the plugin was started with.
:param url: string - url of the entry. would be ``plugin://`` for another virtual
directory
:param listitem: ListItem - item to add.
:param isFolder: [opt] bool - True=folder / False=not a folder(default).
:param totalItems: [opt] integer - total number of items that will be passed.(used for
progressbar)
:return: Returns a bool for successful completion.
.. note::
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::
..
if not xbmcplugin.addDirectoryItem(int(sys.argv[1]), 'F:\\Trailers\\300.mov', listitem, totalItems=50): break
..
"""
return True
[docs]
def addDirectoryItems(handle: int,
items: List[Tuple[str, 'xbmcgui.ListItem', bool]],
totalItems: int = 0) -> bool:
"""
Callback function to pass directory contents back to Kodi as a list.
:param handle: integer - handle the plugin was started with.
:param items: List - list of (url, listitem[, isFolder]) as a tuple to add.
:param totalItems: [opt] integer - total number of items that will be passed.(used for
progressbar)
:return: Returns a bool for successful completion.
Large lists benefit over using the standard `addDirectoryItem()`. You may call
this more than once to add items in chunks.
Example::
..
if not xbmcplugin.addDirectoryItems(int(sys.argv[1]), [(url, listitem, False,)]: raise
..
"""
return True
[docs]
def endOfDirectory(handle: int,
succeeded: bool = True,
updateListing: bool = False,
cacheToDisc: bool = True) -> None:
"""
Callback function to tell Kodi that the end of the directory listing in a
virtualPythonFolder module is reached.
:param handle: integer - handle the plugin was started with.
:param succeeded: [opt] bool - True=script completed successfully(Default)/False=Script
did not.
:param updateListing: [opt] bool - True=this folder should update the current
listing/False=Folder is a subfolder(Default).
:param cacheToDisc: [opt] bool - True=Folder will cache if extended
time(default)/False=this folder will never cache to disc.
Example::
..
xbmcplugin.endOfDirectory(int(sys.argv[1]), cacheToDisc=False)
..
"""
pass
[docs]
def setResolvedUrl(handle: int,
succeeded: bool,
listitem: 'xbmcgui.ListItem') -> None:
"""
Callback function to tell Kodi that the file plugin has been resolved to a url
:param handle: integer - handle the plugin was started with.
:param succeeded: bool - True=script completed successfully/False=Script did not.
:param listitem: ListItem - item the file plugin resolved to for playback.
Example::
..
xbmcplugin.setResolvedUrl(int(sys.argv[1]), True, listitem)
..
"""
pass
[docs]
def addSortMethod(handle: int,
sortMethod: int,
labelMask: str = "",
label2Mask: str = "") -> None:
"""
@brief \python_func{ xbmcplugin.addSortMethod(handle, sortMethod
[,labelMask, label2Mask]) }Adds a sorting method for the media list.
:param handle: integer - handle the plugin was started with.
:param sortMethod: integer - see available sort methods at the bottom (or see SortUtils).
=================================================================== ================================================
Value Description
=================================================================== ================================================
xbmcplugin.SORT_METHOD_NONE Do not sort
xbmcplugin.SORT_METHOD_LABEL Sort by label
xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE Sort by the label and ignore "The" before
xbmcplugin.SORT_METHOD_DATE Sort by the date
xbmcplugin.SORT_METHOD_SIZE Sort by the size
xbmcplugin.SORT_METHOD_FILE Sort by the file
xbmcplugin.SORT_METHOD_DRIVE_TYPE Sort by the drive type
xbmcplugin.SORT_METHOD_TRACKNUM Sort by the track number
xbmcplugin.SORT_METHOD_DURATION Sort by the duration
xbmcplugin.SORT_METHOD_TITLE Sort by the title
xbmcplugin.SORT_METHOD_TITLE_IGNORE_THE Sort by the title and ignore "The" before
xbmcplugin.SORT_METHOD_ARTIST Sort by the artist
xbmcplugin.SORT_METHOD_ARTIST_IGNORE_THE Sort by the artist and ignore "The" before
xbmcplugin.SORT_METHOD_ALBUM Sort by the album
xbmcplugin.SORT_METHOD_ALBUM_IGNORE_THE Sort by the album and ignore "The" before
xbmcplugin.SORT_METHOD_GENRE Sort by the genre
xbmcplugin.SORT_SORT_METHOD_VIDEO_YEAR, xbmcplugin.SORT_METHOD_YEAR Sort by the year
xbmcplugin.SORT_METHOD_VIDEO_RATING Sort by the video rating
xbmcplugin.SORT_METHOD_PROGRAM_COUNT Sort by the program count
xbmcplugin.SORT_METHOD_PLAYLIST_ORDER Sort by the playlist order
xbmcplugin.SORT_METHOD_EPISODE Sort by the episode
xbmcplugin.SORT_METHOD_VIDEO_TITLE Sort by the video title
xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE Sort by the video sort title
xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE Sort by the video sort title and ignore
"The" before
xbmcplugin.SORT_METHOD_PRODUCTIONCODE Sort by the production code
xbmcplugin.SORT_METHOD_SONG_RATING Sort by the song rating
xbmcplugin.SORT_METHOD_MPAA_RATING Sort by the mpaa rating
xbmcplugin.SORT_METHOD_VIDEO_RUNTIME Sort by video runtime
xbmcplugin.SORT_METHOD_STUDIO Sort by the studio
xbmcplugin.SORT_METHOD_STUDIO_IGNORE_THE Sort by the studio and ignore "The" before
xbmcplugin.SORT_METHOD_UNSORTED Use list not sorted
xbmcplugin.SORT_METHOD_BITRATE Sort by the bitrate
xbmcplugin.SORT_METHOD_LISTENERS Sort by the listeners
xbmcplugin.SORT_METHOD_COUNTRY Sort by the country
xbmcplugin.SORT_METHOD_DATEADDED Sort by the added date
xbmcplugin.SORT_METHOD_FULLPATH Sort by the full path name
xbmcplugin.SORT_METHOD_LABEL_IGNORE_FOLDERS Sort by the label names and ignore related
folder names
xbmcplugin.SORT_METHOD_LASTPLAYED Sort by last played date
xbmcplugin.SORT_METHOD_PLAYCOUNT Sort by the play count
xbmcplugin.SORT_METHOD_CHANNEL Sort by the channel
xbmcplugin.SORT_METHOD_DATE_TAKEN Sort by the taken date
xbmcplugin.SORT_METHOD_VIDEO_USER_RATING Sort by the rating of the user of video
xbmcplugin.SORT_METHOD_SONG_USER_RATING Sort by the rating of the user of song
=================================================================== ================================================
:param labelMask: [opt] string - the label mask to use for the first label. applies to:
========================== =======================
sortMethod labelMask
========================== =======================
SORT_METHOD_TRACKNUM Defaults to``[%N. ]%T``
SORT_METHOD_EPISODE Defaults to``%H. %T``
SORT_METHOD_PRODUCTIONCODE Defaults to``%H. %T``
All other sort methods Defaults to``%T``
========================== =======================
:param label2Mask: [opt] string - the label mask to use for the second label. Defaults
to``%D`` applies to:
================================ ==================== =======================================
SORT_METHOD_NONE SORT_METHOD_UNSORTED SORT_METHOD_VIDEO_TITLE
SORT_METHOD_TRACKNUM SORT_METHOD_FILE SORT_METHOD_TITLE
SORT_METHOD_TITLE_IGNORE_THE SORT_METHOD_LABEL SORT_METHOD_LABEL_IGNORE_THE
SORT_METHOD_VIDEO_SORT_TITLE SORT_METHOD_FULLPATH SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE
SORT_METHOD_LABEL_IGNORE_FOLDERS SORT_METHOD_CHANNEL
================================ ==================== =======================================
.. note::
to add multiple sort methods just call the method multiple times.
@python_v13 Added new sort **SORT_METHOD_DATE_TAKEN**, **SORT_METHOD_COU
NTRY**, **SORT_METHOD_DATEADDED**, **SORT_METHOD_FULLPATH**, **SORT_METHO
D_LABEL_IGNORE_FOLDERS**, **SORT_METHOD_LASTPLAYED**, **SORT_METHOD_PLAY
COUNT**, **SORT_METHOD_CHANNEL**.
@python_v17 Added new sort **SORT_METHOD_VIDEO_USER_RATING**.
@python_v19 Added new option **labelMask**.
Example::
..
xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED)
..
"""
pass
[docs]
def getSetting(handle: int, id: str) -> str:
"""
Returns the value of a setting as a string.
:param handle: integer - handle the plugin was started with.
:param id: string - id of the setting that the module needs to access.
:return: Setting value as string
.. note::
You can use the above as a keyword.
Example::
..
apikey = xbmcplugin.getSetting(int(sys.argv[1]), 'apikey')
..
"""
return ""
[docs]
def setSetting(handle: int, id: str, value: str) -> None:
"""
Sets a plugin setting for the current running plugin.
:param handle: integer - handle the plugin was started with.
:param id: string - id of the setting that the module needs to access.
:param value: string or unicode - value of the setting.
Example::
..
xbmcplugin.setSetting(int(sys.argv[1]), id='username', value='teamxbmc')
..
"""
pass
[docs]
def setContent(handle: int, content: str) -> None:
"""
Sets the plugins content.
:param handle: integer - handle the plugin was started with.
:param content: string - content type (eg. movies)
Available content strings
====== ======= ======== ===========
files songs artists albums
movies tvshows episodes musicvideos
videos images games
====== ======= ======== ===========
Use **videos** for all videos which do not apply to the more specific mentioned
ones like "movies", "episodes" etc. A good example is youtube.
@python_v18 Added new **games** contentExample::
..
xbmcplugin.setContent(int(sys.argv[1]), 'movies')
..
"""
pass
[docs]
def setPluginCategory(handle: int, category: str) -> None:
"""
Sets the plugins name for skins to display.
:param handle: integer - handle the plugin was started with.
:param category: string or unicode - plugins sub category.
Example::
..
xbmcplugin.setPluginCategory(int(sys.argv[1]), 'Comedy')
..
"""
pass
[docs]
def setPluginFanart(handle: int,
image: Optional[str] = None,
color1: Optional[str] = None,
color2: Optional[str] = None,
color3: Optional[str] = None) -> None:
"""
Sets the plugins fanart and color for skins to display.
:param handle: integer - handle the plugin was started with.
:param image: [opt] string - path to fanart image.
:param color1: [opt] hexstring - color1. (e.g. '0xFFFFFFFF')
:param color2: [opt] hexstring - color2. (e.g. '0xFFFF3300')
:param color3: [opt] hexstring - color3. (e.g. '0xFF000000')
Example::
..
xbmcplugin.setPluginFanart(int(sys.argv[1]), 'special://home/addons/plugins/video/Apple movie trailers II/fanart.png',
color2='0xFFFF3300')
..
"""
pass
[docs]
def setProperty(handle: int, key: str, value: str) -> None:
"""
Sets a container property for this plugin.
:param handle: integer - handle the plugin was started with.
:param key: string - property name.
:param value: string or unicode - value of property.
.. note::
Key is NOT case sensitive.
Example::
..
xbmcplugin.setProperty(int(sys.argv[1]), 'Emulator', 'M.A.M.E.')
..
"""
pass
