Official Kodi Wiki - User contributions [en]

Context Item Add-ons

2021-09-15T04:59:00Z

Pete (Wgtn,NZ): Grammar corrections.

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">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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-ons may attach to a menu defined by other add-ons as well.

Next, the '''<item>''' element defines the action to add to perform when the user selects the item. It is specified my assigning the name of a Python script file to the <code>library</code> attribute. Each menu item needs to have a unique <code>library</code> value (Duplicate items are ignored).

'''<label>''' is a string, or an ID from the language file, that specifies the text that is shown in the context menu item, on the screen.

'''<visible>''' is required, and should contain a [[Conditional visibility|visibility expression]], which will determine if (or when) the item is 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|Kodi v19 Matrix and later.}}

In Kodi v19 Matrix and later, it is possible to specify an optional <code>args</code> attribute to a context item. The contents of this attribute will be passed as an argument to the script specified in the <code>library</code> attribute. It can be accessed via <code>sys.argv</code>. The combination of <code>args</code> and <code>library</code> need to be unique. Duplicate combinations are ignored.

<syntaxhighlight lang="xml">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py" args="command_arg">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</syntaxhighlight>

{{Note|Keep in mind that there is limited space in the [[context menu]]. Attaching a context menu to an add-on will force the user to have all of them enabled at the same time. Consider using [[#submenus]], or creating a separate add-on.}}

== Submenus ==

<menu> and <item> elements may be mixed and nested to created submenus. Example:

<syntaxhighlight lang="xml">
<menu id="kodi.core.main">
<menu>
<label>My submenu</label>
<item library="contextitem1.py">
<label>30001</label>
<visible>true</visible>
</item>
<item library="contextitem2.py">
<label>30002</label>
<visible>true</visible>
</item>
<menu>
<label>Subsubmenu</label>
<item library="contextitem3.py">
<label>30003</label>
<visible>true</visible>
</item>
</menu>
</menu>
</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 https://codedocs.xyz/xbmc/xbmc/group__python__xbmcgui__listitem.html for available properties.

Example script:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '{}'".format(sys.listitem.getLabel())
xbmcgui.Dialog().notification("Hello context items!", message)
</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]]

Context Item Add-ons

2021-09-15T04:57:21Z

Pete (Wgtn,NZ): Further improvements to specificity.

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">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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-ons may attach to a menu defined by other add-ons as well.

Next, the '''<item>''' element defines the action to add to perform when the user selects the item. It is specified my assigning the name of a Python script file to the <code>library</code> attribute. Each menu item needs to have a unique <code>library</code> value (Duplicate items are ignored).

'''<label>''' is a string, or an ID from the language file, that specifies the text that is shown in the context menu item, on the screen.

'''<visible>''' is required, and should contain a [[Conditional visibility|visibility expression]], which will determine if (or when) the item is 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|Kodi v19 Matrix and later.}}

In Kodi v19 Matrix and later, it is possible to specify an optional <code>args</code> attribute to a context item. The contents of this attribute will be passed as an argument to the script specified in the <code>library</code> attribute. It can be accessed via <code>sys.argv</code>. The combination of <code>args</code> and <code>library</code> need to be unique. Duplicate combinations are ignored.

<syntaxhighlight lang="xml">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py" args="command_arg">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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">
<menu id="kodi.core.main">
<menu>
<label>My submenu</label>
<item library="contextitem1.py">
<label>30001</label>
<visible>true</visible>
</item>
<item library="contextitem2.py">
<label>30002</label>
<visible>true</visible>
</item>
<menu>
<label>Subsubmenu</label>
<item library="contextitem3.py">
<label>30003</label>
<visible>true</visible>
</item>
</menu>
</menu>
</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 https://codedocs.xyz/xbmc/xbmc/group__python__xbmcgui__listitem.html for available properties.

Example script:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '{}'".format(sys.listitem.getLabel())
xbmcgui.Dialog().notification("Hello context items!", message)
</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]]

Context Item Add-ons

2021-09-15T04:49:30Z

Pete (Wgtn,NZ): Paragraph sentences re-arranged in more logical order, and separated.

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">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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-ons may attach to a 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. Each menu item needs to have a unique <code>library</code> specified. Duplicate items are ignored.

'''<label>''' is a string, or an ID from the language file, to show in the context menu.

'''<visible>''' is required, and should contain a [[Conditional visibility|visibility expression]], which will determine if (or when) the item is 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|Kodi v19 Matrix and later.}}

In Kodi v19 Matrix and later, it is possible to specify an optional <code>args</code> attribute to a context item. The contents of this attribute will be passed as an argument to the script specified in the <code>library</code> attribute. It can be accessed via <code>sys.argv</code>. The combination of <code>args</code> and <code>library</code> need to be unique. Duplicate combinations are ignored.

<syntaxhighlight lang="xml">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py" args="command_arg">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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">
<menu id="kodi.core.main">
<menu>
<label>My submenu</label>
<item library="contextitem1.py">
<label>30001</label>
<visible>true</visible>
</item>
<item library="contextitem2.py">
<label>30002</label>
<visible>true</visible>
</item>
<menu>
<label>Subsubmenu</label>
<item library="contextitem3.py">
<label>30003</label>
<visible>true</visible>
</item>
</menu>
</menu>
</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 https://codedocs.xyz/xbmc/xbmc/group__python__xbmcgui__listitem.html for available properties.

Example script:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '{}'".format(sys.listitem.getLabel())
xbmcgui.Dialog().notification("Hello context items!", message)
</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]]

Context Item Add-ons

2021-09-15T04:42:25Z

Pete (Wgtn,NZ): Additions of conjoining words, and punctuation.... to aid readability.

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">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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-ons may attach to a 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> is a string, or an ID from the language file, to show in the context menu. Each menu item needs to have a unique <code>library</code> specified. Duplicate items are ignored.

<visible> (required) should contain a [[Conditional visibility|visibility expression]], which will determine when the item is 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|Kodi v19 Matrix and later.}}

In Kodi v19 Matrix and later, it is possible to specify an optional <code>args</code> attribute to a context item. The contents of this attribute will be passed as an argument to the script specified in the <code>library</code> attribute. It can be accessed via <code>sys.argv</code>. The combination of <code>args</code> and <code>library</code> need to be unique. Duplicate combinations are ignored.

<syntaxhighlight lang="xml">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py" args="command_arg">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</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">
<menu id="kodi.core.main">
<menu>
<label>My submenu</label>
<item library="contextitem1.py">
<label>30001</label>
<visible>true</visible>
</item>
<item library="contextitem2.py">
<label>30002</label>
<visible>true</visible>
</item>
<menu>
<label>Subsubmenu</label>
<item library="contextitem3.py">
<label>30003</label>
<visible>true</visible>
</item>
</menu>
</menu>
</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 https://codedocs.xyz/xbmc/xbmc/group__python__xbmcgui__listitem.html for available properties.

Example script:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '{}'".format(sys.listitem.getLabel())
xbmcgui.Dialog().notification("Hello context items!", message)
</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]]