<?xml version="1.0" encoding="UTF-8" ?>
<class name="EditorContextMenuPlugin" inherits="RefCounted" api_type="editor" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		Plugin for adding custom context menus in the editor.
	</brief_description>
	<description>
		[EditorContextMenuPlugin] allows for the addition of custom options in the editor's context menu.
		Currently, context menus are supported for three commonly used areas: the file system, scene tree, and editor script list panel.
	</description>
	<tutorials>
	</tutorials>
	<methods>
		<method name="_popup_menu" qualifiers="virtual">
			<return type="void" />
			<param index="0" name="paths" type="PackedStringArray" />
			<description>
				Called when creating a context menu, custom options can be added by using the [method add_context_menu_item] or [method add_context_menu_item_from_shortcut] functions. [param paths] contains currently selected paths (depending on menu), which can be used to conditionally add options.
			</description>
		</method>
		<method name="add_context_menu_item">
			<return type="void" />
			<param index="0" name="name" type="String" />
			<param index="1" name="callback" type="Callable" />
			<param index="2" name="icon" type="Texture2D" default="null" />
			<description>
				Add custom option to the context menu of the plugin's specified slot. When the option is activated, [param callback] will be called. Callback should take single [Array] argument; array contents depend on context menu slot.
				[codeblock]
				func _popup_menu(paths):
					add_context_menu_item("File Custom options", handle, ICON)
				[/codeblock]
				If you want to assign shortcut to the menu item, use [method add_context_menu_item_from_shortcut] instead.
			</description>
		</method>
		<method name="add_context_menu_item_from_shortcut">
			<return type="void" />
			<param index="0" name="name" type="String" />
			<param index="1" name="shortcut" type="Shortcut" />
			<param index="2" name="icon" type="Texture2D" default="null" />
			<description>
				Add custom option to the context menu of the plugin's specified slot. The option will have the [param shortcut] assigned and reuse its callback. The shortcut has to be registered beforehand with [method add_menu_shortcut].
				[codeblock]
				func _init():
					add_menu_shortcut(SHORTCUT, handle)

				func _popup_menu(paths):
					add_context_menu_item_from_shortcut("File Custom options", SHORTCUT, ICON)
				[/codeblock]
			</description>
		</method>
		<method name="add_context_submenu_item">
			<return type="void" />
			<param index="0" name="name" type="String" />
			<param index="1" name="menu" type="PopupMenu" />
			<param index="2" name="icon" type="Texture2D" default="null" />
			<description>
				Add a submenu to the context menu of the plugin's specified slot. The submenu is not automatically handled, you need to connect to its signals yourself. Also the submenu is freed on every popup, so provide a new [PopupMenu] every time.
				[codeblock]
				func _popup_menu(paths):
					var popup_menu = PopupMenu.new()
					popup_menu.add_item("Blue")
					popup_menu.add_item("White")
					popup_menu.id_pressed.connect(_on_color_submenu_option)

					add_context_submenu_item("Set Node Color", popup_menu)
				[/codeblock]
			</description>
		</method>
		<method name="add_menu_shortcut">
			<return type="void" />
			<param index="0" name="shortcut" type="Shortcut" />
			<param index="1" name="callback" type="Callable" />
			<description>
				Registers a shortcut associated with the plugin's context menu. This method should be called once (e.g. in plugin's [method Object._init]). [param callback] will be called when user presses the specified [param shortcut] while the menu's context is in effect (e.g. FileSystem dock is focused). Callback should take single [Array] argument; array contents depend on context menu slot.
				[codeblock]
				func _init():
					add_menu_shortcut(SHORTCUT, handle)
				[/codeblock]
			</description>
		</method>
	</methods>
	<constants>
		<constant name="CONTEXT_SLOT_SCENE_TREE" value="0" enum="ContextMenuSlot">
			Context menu of Scene dock. [method _popup_menu] will be called with a list of paths to currently selected nodes, while option callback will receive the list of currently selected nodes.
		</constant>
		<constant name="CONTEXT_SLOT_FILESYSTEM" value="1" enum="ContextMenuSlot">
			Context menu of FileSystem dock. [method _popup_menu] and option callback will be called with list of paths of the currently selected files.
		</constant>
		<constant name="CONTEXT_SLOT_SCRIPT_EDITOR" value="2" enum="ContextMenuSlot">
			Context menu of Script editor's script tabs. [method _popup_menu] will be called with the path to the currently edited script, while option callback will receive reference to that script.
		</constant>
		<constant name="CONTEXT_SLOT_FILESYSTEM_CREATE" value="3" enum="ContextMenuSlot">
			The "Create..." submenu of FileSystem dock's context menu, or the "New" section of the main context menu when empty space is clicked. [method _popup_menu] and option callback will be called with the path of the currently selected folder. When clicking the empty space, the list of paths for popup method will be empty.
			[codeblock]
			func _popup_menu(paths):
			    if paths.is_empty():
			        add_context_menu_item("New Image File...", create_image)
			    else:
			        add_context_menu_item("Image File...", create_image)
			[/codeblock]
		</constant>
		<constant name="CONTEXT_SLOT_SCRIPT_EDITOR_CODE" value="4" enum="ContextMenuSlot">
			Context menu of Script editor's code editor. [method _popup_menu] will be called with the path to the [CodeEdit] node. You can fetch it using this code:
			[codeblock]
			func _popup_menu(paths):
				var code_edit = Engine.get_main_loop().root.get_node(paths[0]);
			[/codeblock]
			The option callback will receive reference to that node. You can use [CodeEdit] methods to perform symbol lookups etc.
		</constant>
		<constant name="CONTEXT_SLOT_SCENE_TABS" value="5" enum="ContextMenuSlot">
			Context menu of scene tabs. [method _popup_menu] will be called with the path of the clicked scene, or empty [PackedStringArray] if the menu was opened on empty space. The option callback will receive the path of the clicked scene, or empty [String] if none was clicked.
		</constant>
		<constant name="CONTEXT_SLOT_2D_EDITOR" value="6" enum="ContextMenuSlot">
			Context menu of 2D editor's basic right-click menu. [method _popup_menu] will be called with paths to all [CanvasItem] nodes under the cursor. You can fetch them using this code:
			[codeblock]
			func _popup_menu(paths):
				var canvas_item = Engine.get_main_loop().root.get_node(paths[0]); # Replace 0 with the desired index.
			[/codeblock]
			The paths array is empty if there weren't any nodes under cursor. The option callback will receive a typed array of [CanvasItem] nodes.
		</constant>
		<constant name="CONTEXT_SLOT_INSPECTOR_PROPERTY" value="7" enum="ContextMenuSlot">
			Context menu of the inspectors right-click menu. [method _popup_menu] will be called with an array of two items: The first will be the object's ID, the second will be the property name. An object can be retrieved from it's ID via [method @GlobalScope.instance_from_id] after converting it to an int. The option callback will receive the EditorProperty directly.
		</constant>
	</constants>
</class>
