Context Item Add-ons: Difference between revisions
No edit summary |
(update to jarvis api) |
||
Line 1: | Line 1: | ||
Context item add-ons allows the [[context menu]] in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a < | Context item add-ons allows the [[context menu]] in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a <menu> definition. | ||
Example: | |||
<syntaxhighlight lang="xml"> | <syntaxhighlight lang="xml"> | ||
<extension point="kodi.context.item" | <extension point="kodi.context.item"> | ||
<menu id="kodi.core.main"> | |||
<item library="contextitem.py"> | |||
<label>30000</label> | |||
<visible>true</visible> | |||
</ | </item> | ||
</menu> | |||
</extension> | </extension> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
The first <menu> element defines which top level menu to attach to. In core, there are two available: <code>kodi.core.main</code> and <code>kodi.core.manage</code>. Add-on may attach to menu defined by other add-ons as well. Next, the <item> element defines the action to add to the menu. <code>library</code> is the file to execute, <label> a string or an ID from the language file to show in the context menu. | |||
<visible> (required) should contain a [[Conditional visibility|visibility expression]] and will determine when the item is be visible in the [[context menu]]. | |||
< | This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the [[Addon.xml#<requires>]] element: | ||
<syntaxhighlight lang="xml"> | |||
<import addon="xbmc.python" version="2.23.0"/> | |||
</syntaxhighlight> | |||
{{Note|Keep in mind that there is limited space in the [[context menu]]. Attaching context menu to an add-on will force the user to have all of them enabled at the same time. Consider using [[#submenus]] or a creating a separate add-on.}} | |||
== Submenus == | |||
<menu> and <item> elements may be mixed and nested to created submenus. Example: | |||
<syntaxhighlight lang="xml"> | <syntaxhighlight lang="xml"> | ||
< | <menu id="kodi.core.main"> | ||
<menu> | |||
<label>My submenu</label> | |||
<item library="contextitem1.py"> | |||
<label>Item 1</label> | |||
<visible>true</visible> | |||
</item> | |||
<item library="contextitem2.py"> | |||
<label>Item 2</label> | |||
<visible>true</visible> | |||
</item> | |||
<menu> | |||
<label>Subsubmenu</label> | |||
<item library="contextitem3.py"> | |||
<label>Item 3</label> | |||
<visible>true</visible> | |||
</item> | |||
</menu> | |||
</menu> | |||
</syntaxhighlight> | </syntaxhighlight> | ||
== | == Accessing information about selected item == | ||
The <code>sys.listitem</code> attribute contains a copy of the item the context menu was opened on. It is an instance of <code>xbmcgui.ListItem</code>. See http://mirrors.xbmc.org/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem for available properties. | |||
Example script: | |||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
Line 44: | Line 71: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== v15 Isengard (deprecated) == | |||
Isengard, API version 2.20.0, does not support <menu> definition and can only define a single item as follows: | |||
<syntaxhighlight lang="xml"> | |||
<extension point="kodi.context.item" library="addon.py"> | |||
<item> | |||
<label>Hello World</label> | |||
<visible>!IsEmpty(ListItem.Genre)</visible> | |||
<parent>kodi.core.manage</parent> | |||
</item> | |||
</extension> | |||
</syntaxhighlight> | |||
This syntax is considered deprecated and will be removed in future versions. | |||
Note: Both syntaxes are '''backwards''' and '''forward''' compatible. Add-ons may use both the old <item> and the new <menu> at the same time for comparability with v15 Isengard and v16 Jarvis. | |||
[[Category:Add-on development]] | [[Category:Add-on development]] |
Revision as of 10:58, 12 March 2016
Context item add-ons allows the context menu in Kodi to be extended. Add-ons must provide the kodi.context.item
extension point and a <menu> definition.
Example:
<extension point="kodi.context.item"> <menu id="kodi.core.main"> <item library="contextitem.py"> <label>30000</label> <visible>true</visible> </item> </menu> </extension>
The first <menu> element defines which top level menu to attach to. In core, there are two available: kodi.core.main
and kodi.core.manage
. Add-on may attach to menu defined by other add-ons as well. Next, the <item> element defines the action to add to the menu. library
is the file to execute, <label> a string or an ID from the language file to show in the context menu.
<visible> (required) should contain a visibility expression and will determine when the item is be visible in the context menu.
This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the Addon.xml#<requires> element:
<import addon="xbmc.python" version="2.23.0"/>
Note: Keep in mind that there is limited space in the context menu. Attaching context menu to an add-on will force the user to have all of them enabled at the same time. Consider using #submenus or a creating a separate add-on.
<menu> and <item> elements may be mixed and nested to created submenus. Example:
<menu id="kodi.core.main"> <menu> <label>My submenu</label> <item library="contextitem1.py"> <label>Item 1</label> <visible>true</visible> </item> <item library="contextitem2.py"> <label>Item 2</label> <visible>true</visible> </item> <menu> <label>Subsubmenu</label> <item library="contextitem3.py"> <label>Item 3</label> <visible>true</visible> </item> </menu> </menu>
Accessing information about selected item
The sys.listitem
attribute contains a copy of the item the context menu was opened on. It is an instance of xbmcgui.ListItem
. See http://mirrors.xbmc.org/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem for available properties.
Example script:
import sys import xbmc if __name__ == '__main__': message = "Clicked on '%s'" % sys.listitem.getLabel() xbmc.executebuiltin("Notification(\"Hello context items!\", \"%s\")" % message)
v15 Isengard (deprecated)
Isengard, API version 2.20.0, does not support <menu> definition and can only define a single item as follows:
<extension point="kodi.context.item" library="addon.py"> <item> <label>Hello World</label> <visible>!IsEmpty(ListItem.Genre)</visible> <parent>kodi.core.manage</parent> </item> </extension>
This syntax is considered deprecated and will be removed in future versions.
Note: Both syntaxes are backwards and forward compatible. Add-ons may use both the old <item> and the new <menu> at the same time for comparability with v15 Isengard and v16 Jarvis.