Difference between revisions of "Context Item Add-ons"

From Official Kodi Wiki
Jump to navigation Jump to search
(Paragraph sentences re-arranged in more logical order, and separated.)
m (Added mininav)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{mininav|[[Development]]|[[Add-on development]]}}


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.  
Context item add-ons extend the Kodi [[context menu]] with useful actions not present in Kodi by default.
 
= Introduction =
 
Context item add-ons must provide the <code>kodi.context.item</code> extension point and a <menu> definition.  


Example:
Example:
Line 17: Line 22:
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.
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.
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, to show in the context menu.
'''<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]].  
'''<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]].  
Line 43: Line 48:
</syntaxhighlight>
</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.}}
{{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 ==
= Submenus =


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




== Accessing information about selected item ==
= 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 <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.
Line 88: Line 93:
</syntaxhighlight>
</syntaxhighlight>


== v15 Isengard (deprecated) ==
= v15 Isengard (deprecated) =
Isengard, API version 2.20.0, does not support <menu> definition and can only define a single item as follows:
Isengard, API version 2.20.0, does not support <menu> definition and can only define a single item as follows:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">

Latest revision as of 19:36, 3 October 2021

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Context Item Add-ons

Context item add-ons extend the Kodi context menu with useful actions not present in Kodi by default.

1 Introduction

Context item 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-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 library attribute. Each menu item needs to have a unique library 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 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:

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


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


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

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