Kodi Development 22.0
for Binary and Script based Add-Ons
 
Loading...
Searching...
No Matches

Detailed Description

Selectable window list item.

Function Documentation

◆ ListItem()

ListItem ( )

Selectable window list item.

The list item control is used for creating item lists in Kodi

Class: ListItem([label, label2, path, offscreen])

Parameters
label[opt] string (default "") - the label to display on the item
label2[opt] string (default "") - the label2 of the item
path[opt] string (default "") - the path for the item
offscreen[opt] bool (default False) - if GUI based locks should be avoided. Most of the times listitems are created offscreen and added later to a container for display (e.g. plugins) or they are not even displayed (e.g. python scrapers). In such cases, there is no need to lock the GUI when creating the items (increasing your addon performance). Note however, that if you are creating listitems and managing the container itself (e.g using WindowXML or WindowXMLDialog classes) subsquent modifications to the item will require locking. Thus, in such cases, use the default value (False).

v16 Python API changes
iconImage and thumbnailImage are deprecated. Use setArt().
v18 Python API changes
Added offscreen argument.
v19 Python API changes
Removed iconImage and thumbnailImage. Use setArt().

Example:

...
listitem = xbmcgui.ListItem('Casino Royale')
...

◆ getLabel()

getLabel ( )

Function: getLabel()


Returns the listitem label.

Returns
Label of item

Example:

...
# getLabel()
label = listitem.getLabel()
...

◆ getLabel2()

getLabel2 ( )

Function: getLabel2()


Returns the second listitem label.

Returns
Second label of item

Example:

...
# getLabel2()
label = listitem.getLabel2()
...

◆ setLabel()

setLabel ( ...)

Function: setLabel(label)


Sets the listitem's label.

Parameters
labelstring or unicode - text string.

Example:

...
# setLabel(label)
listitem.setLabel('Casino Royale')
...

◆ setLabel2()

setLabel2 ( ...)

Function: setLabel2(label)


Sets the listitem's label2.

Parameters
labelstring or unicode - text string.

Example:

...
# setLabel2(label)
listitem.setLabel2('Casino Royale')
...

◆ getDateTime()

getDateTime ( )

Function: getDateTime()


Returns the list item's datetime in W3C format (YYYY-MM-DDThh:mm:ssTZD).

Returns
string or unicode - datetime string (W3C).

v20 Python API changes
New function added.

Example:

...
# getDateTime()
strDateTime = listitem.getDateTime()
...

◆ setDateTime()

setDateTime ( ...)

Function: setDateTime(dateTime)


Sets the list item's datetime in W3C format. The following formats are supported:

  • YYYY
  • YYYY-MM-DD
  • YYYY-MM-DDThh:mm[TZD]
  • YYYY-MM-DDThh:mm:ss[TZD] where the timezone (TZD) is always optional and can be in one of the following formats:
  • Z (for UTC)
  • +hh:mm
  • -hh:mm
Parameters
labelstring or unicode - datetime string (W3C).

v20 Python API changes
New function added.

Example:

...
# setDate(dateTime)
listitem.setDateTime('2021-03-09T12:30:00Z')
...

◆ setArt()

setArt ( ...)

Function: setArt(values)


Sets the listitem's art

Parameters
valuesdictionary - pairs of { label: value }.
  • Some default art values (any string possible):
    Label Type
    thumb string - image filename
    poster string - image filename
    banner string - image filename
    fanart string - image filename
    clearart string - image filename
    clearlogo string - image filename
    landscape string - image filename
    icon string - image filename

v13 Python API changes
New function added.
v16 Python API changes
Added new label icon.

Example:

...
# setArt(values)
listitem.setArt({ 'poster': 'poster.png', 'banner' : 'banner.png' })
...

◆ setIsFolder()

setIsFolder ( ...)

Function: setIsFolder(isFolder)


Sets if this listitem is a folder.

Parameters
isFolderbool - True=folder / False=not a folder (default).

v18 Python API changes
New function added.

Example:

...
# setIsFolder(isFolder)
listitem.setIsFolder(True)
...

◆ setUniqueIDs()

setUniqueIDs ( ...)

Function: setUniqueIDs(values, defaultrating)


Sets the listitem's uniqueID

Parameters
valuesdictionary - pairs of { label: value }.
defaultrating[opt] string - the name of default rating.
  • Some example values (any string possible):
    Label Type
    imdb string - uniqueid name
    tvdb string - uniqueid name
    tmdb string - uniqueid name
    anidb string - uniqueid name

v20 Python API changes
Deprecated. Use InfoTagVideo.setUniqueIDs() instead.

Example:

...
# setUniqueIDs(values, defaultrating)
listitem.setUniqueIDs({ 'imdb': 'tt8938399', 'tmdb' : '9837493' }, "imdb")
...

◆ setRating()

setRating ( ...)

Function: setRating(type, rating, votes = 0, defaultt = False)


Sets a listitem's rating. It needs at least type and rating param

Parameters
typestring - the type of the rating. Any string.
ratingfloat - the value of the rating.
votesint - the number of votes. Default 0.
defaulttbool - is the default rating?. Default False.
  • Some example type (any string possible):
    Label Type
    imdb string - rating type
    tvdb string - rating type
    tmdb string - rating type
    anidb string - rating type

v20 Python API changes
Deprecated. Use InfoTagVideo.setRating() instead.

Example:

...
# setRating(type, rating, votes, defaultt))
listitem.setRating("imdb", 4.6, 8940, True)
...

◆ addSeason()

addSeason ( ...)

Function: addSeason(number, name = "")


Add a season with name to a listitem. It needs at least the season number

Parameters
numberint - the number of the season.
namestring - the name of the season. Default "".

v18 Python API changes
New function added.
v20 Python API changes
Deprecated. Use InfoTagVideo.addSeason() or InfoTagVideo.addSeasons() instead.

Example:

...
# addSeason(number, name))
listitem.addSeason(1, "Murder House")
...

◆ getArt()

getArt ( key )

Function: getArt(key)


Returns a listitem art path as a string, similar to an infolabel.

Parameters
keystring - art name.
  • Some default art values (any string possible):
    Label Type
    thumb string - image path
    poster string - image path
    banner string - image path
    fanart string - image path
    clearart string - image path
    clearlogo string - image path
    landscape string - image path
    icon string - image path

v17 Python API changes
New function added.

Example:

...
poster = listitem.getArt('poster')
...

◆ isFolder()

isFolder ( )

Function: isFolder()


Returns whether the item is a folder or not.


v20 Python API changes
New function added.

Example:

...
isFolder = listitem.isFolder()
...

◆ getUniqueID()

getUniqueID ( key )

Function: getUniqueID(key)


Returns a listitem uniqueID as a string, similar to an infolabel.

Parameters
keystring - uniqueID name.
  • Some default uniqueID values (any string possible):
    Label Type
    imdb string - uniqueid name
    tvdb string - uniqueid name
    tmdb string - uniqueid name
    anidb string - uniqueid name

v20 Python API changes
Deprecated. Use InfoTagVideo.getUniqueID() instead.

Example:

...
uniqueID = listitem.getUniqueID('imdb')
...

◆ getRating()

getRating ( key )

Function: getRating(key)


Returns a listitem rating as a float.

Parameters
keystring - rating type.
  • Some default key values (any string possible):
    Label Type
    imdb string - type name
    tvdb string - type name
    tmdb string - type name
    anidb string - type name

v20 Python API changes
Deprecated. Use InfoTagVideo.getRating() instead.

Example:

...
rating = listitem.getRating('imdb')
...

◆ getVotes()

getVotes ( key )

Function: getVotes(key)


Returns a listitem votes as a integer.

Parameters
keystring - rating type.
  • Some default key values (any string possible):
    Label Type
    imdb string - type name
    tvdb string - type name
    tmdb string - type name
    anidb string - type name

v20 Python API changes
Deprecated. Use InfoTagVideo.getVotesAsInt() instead.

Example:

...
votes = listitem.getVotes('imdb')
...

◆ select()

select ( ...)

Function: select(selected)


Sets the listitem's selected status.

Parameters
selectedbool - True=selected/False=not selected

Example:

...
# select(selected)
listitem.select(True)
...

◆ isSelected()

isSelected ( )

Function: isSelected()


Returns the listitem's selected status.

Returns
bool - true if selected, otherwise false

Example:

...
# isSelected()
selected = listitem.isSelected()
...

◆ setInfo()

setInfo ( ...)

Function: setInfo(type, infoLabels)


Sets the listitem's infoLabels.

Parameters
typestring - type of info labels
infoLabelsdictionary - pairs of { label: value }

Available types

Command name Description
video Video information
music Music information
pictures Pictures informanion
game Game information
Note
To set pictures exif info, prepend exif: to the label. Exif values must be passed as strings, separate value pairs with a comma. (eg. {'exif:resolution': '720,480'} See kodi_pictures_infotag for valid strings.

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.

General Values (that apply to all types):

Info label Description
count integer (12) - can be used to store an id for later, or for sorting purposes
size long (1024) - size in bytes
date string (d.m.Y / 01.01.2009) - file date

Video Values:

Info label Description
genre string (Comedy) or list of strings (["Comedy", "Animation", "Drama"])
country string (Germany) or list of strings (["Germany", "Italy", "France"])
year integer (2009)
episode integer (4)
season integer (1)
sortepisode integer (4)
sortseason integer (1)
episodeguide string (Episode guide)
showlink string (Battlestar Galactica) or list of strings (["Battlestar Galactica", "Caprica"])
top250 integer (192)
setid integer (14)
tracknumber integer (3)
rating float (6.4) - range is 0..10
userrating integer (9) - range is 1..10 (0 to reset)
watched deprecated - use playcount instead
playcount integer (2) - number of times this item has been played
overlay integer (2) - range is 0..7. See Overlay icon types for values
cast list (["Michal C. Hall","Jennifer Carpenter"]) - if provided a list of tuples cast will be interpreted as castandrole
castandrole list of tuples ([("Michael C. Hall","Dexter"),("Jennifer Carpenter","Debra")])
director string (Dagur Kari) or list of strings (["Dagur Kari", "Quentin Tarantino", "Chrstopher Nolan"])
mpaa string (PG-13)
plot string (Long Description)
plotoutline string (Short Description)
title string (Big Fan)
originaltitle string (Big Fan)
sorttitle string (Big Fan)
duration integer (245) - duration in seconds
studio string (Warner Bros.) or list of strings (["Warner Bros.", "Disney", "Paramount"])
tagline string (An awesome movie) - short description of movie
writer string (Robert D. Siegel) or list of strings (["Robert D. Siegel", "Jonathan Nolan", "J.K. Rowling"])
tvshowtitle string (Heroes)
premiered string (2005-03-04)
status string (Continuing) - status of a TVshow
set string (Batman Collection) - name of the collection
setoverview string (All Batman movies) - overview of the collection
tag string (cult) or list of strings (["cult", "documentary", "best movies"]) - movie tag
videoversion string (Video version)
imdbnumber string (tt0110293) - IMDb code
code string (101) - Production code
aired string (2008-12-07)
credits string (Andy Kaufman) or list of strings (["Dagur Kari", "Quentin Tarantino", "Chrstopher Nolan"]) - writing credits
lastplayed string (Y-m-d h:m:s = 2009-04-05 23:16:04)
album string (The Joshua Tree)
artist list (['U2'])
votes string (12345 votes)
path string (/home/user/movie.avi)
trailer string (/home/user/trailer.avi)
dateadded string (Y-m-d h:m:s = 2009-04-05 23:16:04)
mediatype string - "video", "movie", "tvshow", "season", "episode" or "musicvideo"
dbid integer (23) - Only add this for items which are part of the local db. You also need to set the correct 'mediatype'!

Music Values:

Info label Description
tracknumber integer (8)
discnumber integer (2)
duration integer (245) - duration in seconds
year integer (1998)
genre string (Rock)
album string (Pulse)
artist string (Muse)
title string (American Pie)
rating float - range is between 0 and 10
userrating integer - range is 1..10
lyrics string (On a dark desert highway...)
playcount integer (2) - number of times this item has been played
lastplayed string (Y-m-d h:m:s = 2009-04-05 23:16:04)
mediatype string - "music", "song", "album", "artist"
dbid integer (23) - Only add this for items which are part of the local db. You also need to set the correct 'mediatype'!
listeners integer (25614)
musicbrainztrackid string (cd1de9af-0b71-4503-9f96-9f5efe27923c)
musicbrainzartistid string (d87e52c5-bb8d-4da8-b941-9f4928627dc8)
musicbrainzalbumid string (24944755-2f68-3778-974e-f572a9e30108)
musicbrainzalbumartistid string (d87e52c5-bb8d-4da8-b941-9f4928627dc8)
comment string (This is a great song)

Picture Values:

Info label Description
title string (In the last summer-1)
picturepath string (/home/username/pictures/img001.jpg)
exif* string (See kodi_pictures_infotag for valid strings)

Game Values:

Info label Description
title string (Super Mario Bros.)
platform string (Atari 2600)
genres list (["Action","Strategy"])
publisher string (Nintendo)
developer string (Square)
overview string (Long Description)
year integer (1980)
gameclient string (game.libretro.fceumm)

v14 Python API changes
Added new label discnumber.
v15 Python API changes
duration has to be set in seconds.
v16 Python API changes
Added new label mediatype.
v17 Python API changes
Added labels setid, set, imdbnumber, code, dbid (video), path and userrating. Expanded the possible infoLabels for the option mediatype.
v18 Python API changes
Added new game type and associated infolabels. Added labels dbid (music), setoverview, tag, sortepisode, sortseason, episodeguide, showlink. Extended labels genre, country, director, studio, writer, tag, credits to also use a list of strings.
v20 Python API changes
Partially deprecated. Use explicit setters in InfoTagVideo, InfoTagMusic, InfoTagPicture or InfoTagGame instead.
v21 Python API changes
Added videoversion infolabel for movies

Example:

...
listitem.setInfo('video', { 'genre': 'Comedy' })
...

◆ setCast()

setCast ( ...)

Function: setCast(actors)


Set cast including thumbnails

Parameters
actorslist of dictionaries (see below for relevant keys)

v17 Python API changes
New function added.
v20 Python API changes
Deprecated. Use InfoTagVideo.setCast() instead.

Example:

...
actors = [{"name": "Actor 1", "role": "role 1"}, {"name": "Actor 2", "role": "role 2"}]
listitem.setCast(actors)
...

◆ setAvailableFanart()

setAvailableFanart ( ...)

Function: setAvailableFanart(images)


Set available images (needed for video scrapers)

Parameters
imageslist of dictionaries (see below for relevant keys)

v18 Python API changes
New function added.

Example:

...
fanart = [{"image": path_to_image_1, "preview": path_to_preview_1}, {"image": path_to_image_2, "preview": path_to_preview_2}]
listitem.setAvailableFanart(fanart)
...

◆ addAvailableArtwork()

addAvailableArtwork ( ...)

Function: addAvailableArtwork(images)


Add an image to available artworks (needed for video scrapers)

Parameters
urlstring (image path url)
art_typestring (image type)
preview[opt] string (image preview path url)
referrer[opt] string (referrer url)
cache[opt] string (filename in cache)
post[opt] bool (use post to retrieve the image, default false)
isgz[opt] bool (use gzip to retrieve the image, default false)
season[opt] integer (number of season in case of season thumb)

v18 Python API changes
New function added.
v19 Python API changes
New param added (preview).
v20 Python API changes
Deprecated. Use InfoTagVideo.addAvailableArtwork() instead.

Example:

...
listitem.addAvailableArtwork(path_to_image_1, "thumb")
...

◆ addStreamInfo()

addStreamInfo ( ...)

Function: addStreamInfo(type, values)


Add a stream with details.

Parameters
typestring - type of stream(video/audio/subtitle).
valuesdictionary - pairs of { label: value }.
  • Video Values:
    Label Description
    codec string (h264)
    aspect float (1.78)
    width integer (1280)
    height integer (720)
    duration integer (seconds)
  • Audio Values:
    Label Description
    codec string (dts)
    language string (en)
    channels integer (2)
  • Subtitle Values:
    Label Description
    language string (en)

v20 Python API changes
Deprecated. Use InfoTagVideo.addVideoStream(), InfoTagVideo.addAudioStream() or InfoTagVideo.addSubtitleStream() instead.

Example:

...
listitem.addStreamInfo('video', { 'codec': 'h264', 'width' : 1280 })
...

◆ addContextMenuItems()

addContextMenuItems ( ...)

Function: addContextMenuItems([(label, action),*])


Adds item(s) to the context menu for media lists.

Parameters
itemslist - [(label, action),*] A list of tuples consisting of label and action pairs.
  • label string or unicode - item's label.
  • action string or unicode - any available built-in function .
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.

v17 Python API changes
Completely removed previously available argument replaceItems.

Example:

...
listitem.addContextMenuItems([('Theater Showtimes', 'RunScript(script.myaddon,title=Iron Man)')])
...

◆ setProperty()

setProperty ( ...)

Function: setProperty(key, value)


Sets a listitem property, similar to an infolabel.

Parameters
keystring - property name.
valuestring or unicode - value of property.
Note
Key is NOT case sensitive.
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.

Some of these are treated internally by Kodi, such as the 'StartOffset' property, which is the offset in seconds at which to start playback of an item. Others may be used in the skin to add extra information, such as 'WatchedCount' for tvshow items
  • Internal Properties
    Key Description
    inputstream string (inputstream.adaptive) - Set the inputstream add-on that will be used to play the item
    IsPlayable string - "true", "false" - Mark the item as playable, mandatory for playable items
    MimeType string (application/x-mpegURL) - Set the MimeType of the item before playback
    ResumeTime float (1962.0) - Set the resume point of the item in seconds
    SpecialSort string - "top", "bottom" - The item will remain at the top or bottom of the current list
    StartOffset float (60.0) - Set the offset in seconds at which to start playback of the item
    StartPercent float (15.0) - Set the percentage at which to start playback of the item
    StationName string ("My Station Name") - Used to enforce/override MusicPlayer.StationName infolabel from addons (e.g. in radio addons)
    TotalTime float (7848.0) - Set the total time of the item in seconds
    OverrideInfotag string - "true", "false" - When true will override all info from previous listitem
    ForceResolvePlugin string - "true", "false" - When true ensures that a plugin will always receive callbacks to resolve paths (useful for playlist cases)
    rtsp_transport string - "udp", "udp_multicast" or "tcp" - Allow to force the rtsp transport mode for rtsp streams

v20 Python API changes

OverrideInfotag property added

ResumeTime and TotalTime deprecated. Use InfoTagVideo.setResumePoint() instead.

ForceResolvePlugin property added

rtsp_transport property added

Example:

...
listitem.setProperty('AspectRatio', '1.85 : 1')
listitem.setProperty('StartOffset', '256.4')
...

◆ setProperties()

setProperties ( ...)

Function: setProperties(values)


Sets multiple properties for listitem's

Parameters
valuesdictionary - pairs of { label: value }.
v18 Python API changes
New function added.

Example:

...
# setProperties(values)
listitem.setProperties({ 'AspectRatio': '1.85', 'StartOffset' : '256.4' })
...

◆ getProperty()

getProperty ( ...)

Function: getProperty(key)


Returns a listitem property as a string, similar to an infolabel.

Parameters
keystring - property name.
Note
Key is NOT case sensitive.
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.

v20 Python API changes
ResumeTime and TotalTime deprecated. Use InfoTagVideo.getResumeTime() and InfoTagVideo.getResumeTimeTotal() instead.

Example:

...
AspectRatio = listitem.getProperty('AspectRatio')
...

◆ setPath()

setPath ( ...)

Function: setPath(path)


Sets the listitem's path.

Parameters
pathstring or unicode - path, activated when item is clicked.
Note
You can use the above as keywords for arguments.

Example:

...
listitem.setPath(path='/path/to/some/file.ext')
...

◆ setMimeType()

setMimeType ( ...)

Function: setMimeType(mimetype)


Sets the listitem's mimetype if known.

Parameters
mimetypestring or unicode - mimetype

If known prehand, this can (but does not have to) avoid HEAD requests being sent to HTTP servers to figure out file type.

◆ setContentLookup()

setContentLookup ( ...)

Function: setContentLookup(enable)


Enable or disable content lookup for item.

If disabled, HEAD requests to e.g determine mime type will not be sent.

Parameters
enablebool to enable content lookup

v16 Python API changes
New function added.

◆ setSubtitles()

setSubtitles ( ...)

Function: setSubtitles(subtitleFiles)


Sets subtitles for this listitem.

Parameters
subtitleFileslist with path to subtitle files

Example:

...
listitem.setSubtitles(['special://temp/example.srt', 'http://example.com/example.srt'])
...

v14 Python API changes
New function added.

◆ getPath()

getPath ( )

Function: getPath()


Returns the path of this listitem.

Returns
[string] filename

v17 Python API changes
New function added.

◆ getVideoInfoTag()

getVideoInfoTag ( )

Function: getVideoInfoTag()


Returns the VideoInfoTag for this item.

Returns
video info tag

v15 Python API changes
New function added.

◆ getMusicInfoTag()

getMusicInfoTag ( )

Function: getMusicInfoTag()


Returns the MusicInfoTag for this item.

Returns
music info tag

v15 Python API changes
New function added.

◆ getPictureInfoTag()

getPictureInfoTag ( )

Function: getPictureInfoTag()


Returns the InfoTagPicture for this item.

Returns
picture info tag

v20 Python API changes
New function added.

◆ getGameInfoTag()

getGameInfoTag ( )

Function: getGameInfoTag()


Returns the InfoTagGame for this item.

Returns
game info tag

v20 Python API changes
New function added.