initial commit, 4.5 stable

doc/classes/Shortcut.xml

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="Shortcut" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A shortcut for binding input.
+	</brief_description>
+	<description>
+		Shortcuts (also known as hotkeys) are containers of [InputEvent] resources. They are commonly used to interact with a [Control] element from an [InputEvent].
+		One shortcut can contain multiple [InputEvent] resources, making it possible to trigger one action with multiple different inputs.
+		[b]Example:[/b] Capture the [kbd]Ctrl + S[/kbd] shortcut using a [Shortcut] resource:
+		[codeblocks]
+		[gdscript]
+		extends Node
+
+		var save_shortcut = Shortcut.new()
+		func _ready():
+			var key_event = InputEventKey.new()
+			key_event.keycode = KEY_S
+			key_event.ctrl_pressed = true
+			key_event.command_or_control_autoremap = true # Swaps Ctrl for Command on Mac.
+			save_shortcut.events = [key_event]
+
+		func _input(event):
+			if save_shortcut.matches_event(event) and event.is_pressed() and not event.is_echo():
+				print("Save shortcut pressed!")
+				get_viewport().set_input_as_handled()
+		[/gdscript]
+		[csharp]
+		using Godot;
+
+		public partial class MyNode : Node
+		{
+			private readonly Shortcut _saveShortcut = new Shortcut();
+
+			public override void _Ready()
+			{
+				InputEventKey keyEvent = new InputEventKey
+				{
+					Keycode = Key.S,
+					CtrlPressed = true,
+					CommandOrControlAutoremap = true, // Swaps Ctrl for Command on Mac.
+				};
+
+				_saveShortcut.Events = [keyEvent];
+			}
+
+			public override void _Input(InputEvent @event)
+			{
+				if (@event is InputEventKey keyEvent &amp;&amp;
+					_saveShortcut.MatchesEvent(@event) &amp;&amp;
+					keyEvent.Pressed &amp;&amp; !keyEvent.Echo)
+				{
+					GD.Print("Save shortcut pressed!");
+					GetViewport().SetInputAsHandled();
+				}
+			}
+		}
+		[/csharp]
+		[/codeblocks]
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_as_text" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns the shortcut's first valid [InputEvent] as a [String].
+			</description>
+		</method>
+		<method name="has_valid_event" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns whether [member events] contains an [InputEvent] which is valid.
+			</description>
+		</method>
+		<method name="matches_event" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="event" type="InputEvent" />
+			<description>
+				Returns whether any [InputEvent] in [member events] equals [param event]. This uses [method InputEvent.is_match] to compare events.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="events" type="Array" setter="set_events" getter="get_events" default="[]">
+			The shortcut's [InputEvent] array.
+			Generally the [InputEvent] used is an [InputEventKey], though it can be any [InputEvent], including an [InputEventAction].
+		</member>
+	</members>
+</class>