Context Item Add-ons - Revision history

SistemaRayoXP: Added mininav

2021-10-03T19:36:29Z

Added mininav

← Older revision		Revision as of 19:36, 3 October 2021
Line 1:		Line 1:
			{{mininav\|[[Development]]\|[[Add-on development]]}}

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

SistemaRayoXP: Fixed headers

2021-10-03T19:33:53Z

Fixed headers

← Older revision		Revision as of 19:33, 3 October 2021
Line 1:		Line 1:
			Context item add-ons extend the Kodi [[context menu]] with useful actions not present in Kodi by default.

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

			Context item add-ons must provide the <code>kodi.context.item</code> extension point and a <menu> definition.

	Example:		Example:
Line 43:		Line 46:
	</syntaxhighlight>		</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.}}		{{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 76:


	== 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 91:
	</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">

Pete (Wgtn,NZ): Grammar corrections.

2021-09-15T04:59:00Z

Grammar corrections.

← Older revision		Revision as of 04:59, 15 September 2021
Line 43:		Line 43:
	</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.}}

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

2021-09-15T04:57:21Z

Further improvements to specificity.

← Older revision		Revision as of 04:57, 15 September 2021
Line 17:		Line 17:
	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]].

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

2021-09-15T04:49:30Z

Paragraph sentences re-arranged in more logical order, and separated.

← Older revision		Revision as of 04:49, 15 September 2021
Line 15:		Line 15:
	</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-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.		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.

	<visible> (required) should contain a [[Conditional visibility\|visibility expression]], which will determine when the item is visible in the [[context menu]].		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:		This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the [[Addon.xml#<requires>]] element:

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

2021-09-15T04:42:25Z

Additions of conjoining words, and punctuation.... to aid readability.

← Older revision		Revision as of 04:42, 15 September 2021
Line 15:		Line 15:
	</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.		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]] ~~and~~ will determine when the item is be visible in the [[context menu]].		<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:		This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the [[Addon.xml#<requires>]] element:

Basje: /* Accessing information about selected item */

2020-04-25T17:56:33Z

Accessing information about selected item

← Older revision		Revision as of 17:56, 25 April 2020
Line 71:		Line 71:
	== 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 ~~http~~://~~mirrors~~.xbmc~~.org~~/~~docs/python-docs/16.x-jarvis~~/~~xbmcgui~~.html~~#ListItem~~ 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.

	Example script:		Example script:

Basje: /* Accessing information about selected item */

2020-04-25T17:55:43Z

Accessing information about selected item

← Older revision		Revision as of 17:55, 25 April 2020
Line 80:		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) ==		== v15 Isengard (deprecated) ==

Basje at 17:51, 25 April 2020

2020-04-25T17:51:24Z

← Older revision		Revision as of 17:51, 25 April 2020
Line 15:		Line 15:
	</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.		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]].		<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:		This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the [[Addon.xml#<requires>]] element:
Line 25:		Line 24:
	</syntaxhighlight>		</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.}}		{{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.}}
Line 38:		Line 51:
	<label>My submenu</label>		<label>My submenu</label>
	<item library="contextitem1.py">		<item library="contextitem1.py">
	<label>~~Item 1~~</label>		<label>30001</label>
	<visible>true</visible>		<visible>true</visible>
	</item>		</item>
	<item library="contextitem2.py">		<item library="contextitem2.py">
	<label>~~Item 2~~</label>		<label>30002</label>
	<visible>true</visible>		<visible>true</visible>
	</item>		</item>
Line 48:		Line 61:
	<label>Subsubmenu</label>		<label>Subsubmenu</label>
	<item library="contextitem3.py">		<item library="contextitem3.py">
	<label>~~Item 3~~</label>		<label>30003</label>
	<visible>true</visible>		<visible>true</visible>
	</item>		</item>

Takoi: update to jarvis api

2016-03-12T10:58:36Z

update to jarvis api

← Older revision		Revision as of 10:58, 12 March 2016
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. Example:		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" ~~library~~="~~addon~~.py">		<extension point="kodi.context.item">
	<item>		<menu id="kodi.core.main">
	<label>~~Hello World~~</label>		<item library="contextitem.py">
	<visible>~~!IsEmpty(ListItem.Genre)~~</visible>		<label>30000</label>
	~~<parent>kodi.core.manage~~</~~parent~~>		<visible>true</visible>
	</~~item~~>		</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]].


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

	~~<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~~.		{{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.}}

	~~It is currently only possible to provide one item per add-on.~~

	{{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.}}		== Submenus ==

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

	~~This feature requires at least version 2.20.0 of the Python API, which should be specified in the [[Addon.xml#<requires>]] element:~~
	<syntaxhighlight lang="xml">		<syntaxhighlight lang="xml">
	<~~import addon~~="~~xbmc~~.~~python~~" ~~version~~="2.~~20.0~~"/>		<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>

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

	== ~~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 http://mirrors.xbmc.org/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem for available properties.

	~~This example~~ script ~~will display a notification message showing the name of item the context menu was opened on~~:		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]]