Context Item Add-ons: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
No edit summary
(4 intermediate revisions by 2 users not shown)
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 item definition as follows:
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">
<item>
<extension point="kodi.context.item">
   <label></label>
   <menu id="kodi.core.main">
  <visible></visible>
    <item library="contextitem.py">
  <parent></parent>
      <label>30000</label>
</item>
      <visible>true</visible>
    </item>
  </menu>
</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. Each menu need to have unique <code>library</code> specified. Duplicate items are ignored.
<visible> (required) should contain a [[Conditional visibility|visibility expression]] and will determine when the item is be visible in the [[context menu]].


<label>: Required. The label to show in the context menu. String or an ID from the language file.
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>


<visible>: Required. A [[Conditional visibility|visibility expression]] that determines when the item will be visible in the [[context menu]].  
{{note|Kodi v19 Matrix and later.}}


<parent>: Optional. The parent group for the context item. If "kodi.core.manage" the item will be added under the "Manage" sub-menu. If not specified, it will be added to the top level.
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.


It is currently only possible to provide one item per add-on.
<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|Before adding a context menu extension to existing add-on, keep in mind that there is limited space in the [[context menu]] and that having multiple extension in and add-on will force the user to have all of them enabled at the same time.}}
{{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.}}




== Example <code>addon.xml</code> definition: ==
== Submenus ==
 
<menu> and <item> elements may be mixed and nested to created submenus. Example:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<menu id="kodi.core.main">
<addon id="context.item.hello.world" name="Hello World" version="1.0.0" provider-name="your-name">
  <menu>
  <requires>
    <label>My submenu</label>
    <import addon="xbmc.python" version="2.20.0"/>
    <item library="contextitem1.py">
  </requires>
      <label>30001</label>
  <extension point="kodi.context.item" library="addon.py">
      <visible>true</visible>
    <item>
    </item>
       <label>Hello World</label>
    <item library="contextitem2.py">
       <visible>!IsEmpty(ListItem.Genre)</visible>
       <label>30002</label>
       <visible>true</visible>
     </item>
     </item>
  </extension>
    <menu>
  <extension point="kodi.addon.metadata">
      <label>Subsubmenu</label>
    <platform>all</platform>
      <item library="contextitem3.py">
    <summary></summary>
        <label>30003</label>
    <description></description>
        <visible>true</visible>
  </extension>
      </item>
</addon>
    </menu>
</menu>
</syntaxhighlight>
</syntaxhighlight>




== Example python script: ==
== 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.


The item the context menu was opened on can be accessed in python via the <code>sys.listitem<code/> attribute. The attribute is an instance of <code>xbmcgui.ListItem</code>. The following example script will display a notification message showing the name of item:
Example script:


<syntaxhighlight lang="python">
<syntaxhighlight lang="python">
Line 54: Line 80:


if __name__ == '__main__':
if __name__ == '__main__':
     message = "Clicked on '%s'" % sys.listitem.getLabel()
     message = "Clicked on '{}'".format(sys.listitem.getLabel())
     xbmc.executebuiltin("Notification(\"Hello context items!\", \"%s\")" % message)
     xbmcgui.Dialog().notification("Hello context items!", message)
</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 17:56, 25 April 2020

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. Each menu need to have unique library specified. Duplicate items are ignored.

<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: Kodi v19 Matrix and later.

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

<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>

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:

<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>


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 https://codedocs.xyz/xbmc/xbmc/group__python__xbmcgui__listitem.html for available properties.

Example script:

import sys
import xbmc

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