Document when to use Input singleton compared to InputEvent in Node
This commit is contained in:
parent
eabeafd8c3
commit
f3cb774273
|
@ -6,6 +6,7 @@
|
|||
<description>
|
||||
The [Input] singleton handles key presses, mouse buttons and movement, gamepads, and input actions. Actions and their events can be set in the [b]Input Map[/b] tab in [b]Project > Project Settings[/b], or with the [InputMap] class.
|
||||
[b]Note:[/b] [Input]'s methods reflect the global input state and are not affected by [method Control.accept_event] or [method Viewport.set_input_as_handled], as those methods only deal with the way input is propagated in the [SceneTree].
|
||||
[b]Note:[/b] Several methods are available in both the [InputEvent] instances and the [Input] singleton. In this case, calling methods on [InputEvent] should be preferred as it has greater context about the input state compared to the [Input] singleton. For example, [method InputEvent.is_action_pressed] checks for echo events and ignores them automatically, while [method Input.is_action_pressed] treats echo events like non-echo events.
|
||||
</description>
|
||||
<tutorials>
|
||||
<link title="Inputs documentation index">$DOCS_URL/tutorials/inputs/index.html</link>
|
||||
|
|
|
@ -65,6 +65,7 @@
|
|||
To consume the input event and stop it propagating further to other nodes, [method Viewport.set_input_as_handled] can be called.
|
||||
For gameplay input, [method _unhandled_input] and [method _unhandled_key_input] are usually a better fit as they allow the GUI to intercept the events first.
|
||||
[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not an orphan).
|
||||
[b]Note:[/b] Several methods are available in both the [InputEvent] instance that is the [param event] parameter and the [Input] singleton. In this case, calling methods on [InputEvent] should be preferred as it has greater context about the input state compared to the [Input] singleton. For example, [method InputEvent.is_action_pressed] checks for echo events and ignores them automatically, while [method Input.is_action_pressed] treats echo events like non-echo events.
|
||||
</description>
|
||||
</method>
|
||||
<method name="_physics_process" qualifiers="virtual">
|
||||
|
@ -105,6 +106,7 @@
|
|||
To consume the input event and stop it propagating further to other nodes, [method Viewport.set_input_as_handled] can be called.
|
||||
This method can be used to handle shortcuts. For generic GUI events, use [method _input] instead. Gameplay events should usually be handled with either [method _unhandled_input] or [method _unhandled_key_input].
|
||||
[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not orphan).
|
||||
[b]Note:[/b] Several methods are available in both the [InputEvent] instance that is the [param event] parameter and the [Input] singleton. In this case, calling methods on [InputEvent] should be preferred as it has greater context about the input state compared to the [Input] singleton. For example, [method InputEvent.is_action_pressed] checks for echo events and ignores them automatically, while [method Input.is_action_pressed] treats echo events like non-echo events.
|
||||
</description>
|
||||
</method>
|
||||
<method name="_unhandled_input" qualifiers="virtual">
|
||||
|
@ -116,6 +118,7 @@
|
|||
To consume the input event and stop it propagating further to other nodes, [method Viewport.set_input_as_handled] can be called.
|
||||
For gameplay input, this method is usually a better fit than [method _input], as GUI events need a higher priority. For keyboard shortcuts, consider using [method _shortcut_input] instead, as it is called before this method. Finally, to handle keyboard events, consider using [method _unhandled_key_input] for performance reasons.
|
||||
[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not an orphan).
|
||||
[b]Note:[/b] Several methods are available in both the [InputEvent] instance that is the [param event] parameter and the [Input] singleton. In this case, calling methods on [InputEvent] should be preferred as it has greater context about the input state compared to the [Input] singleton. For example, [method InputEvent.is_action_pressed] checks for echo events and ignores them automatically, while [method Input.is_action_pressed] treats echo events like non-echo events.
|
||||
</description>
|
||||
</method>
|
||||
<method name="_unhandled_key_input" qualifiers="virtual">
|
||||
|
@ -128,6 +131,7 @@
|
|||
This method can be used to handle Unicode character input with [kbd]Alt[/kbd], [kbd]Alt + Ctrl[/kbd], and [kbd]Alt + Shift[/kbd] modifiers, after shortcuts were handled.
|
||||
For gameplay input, this and [method _unhandled_input] are usually a better fit than [method _input], as GUI events should be handled first. This method also performs better than [method _unhandled_input], since unrelated events such as [InputEventMouseMotion] are automatically filtered. For shortcuts, consider using [method _shortcut_input] instead.
|
||||
[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not an orphan).
|
||||
[b]Note:[/b] Several methods are available in both the [InputEvent] instance that is the [param event] parameter and the [Input] singleton. In this case, calling methods on [InputEvent] should be preferred as it has greater context about the input state compared to the [Input] singleton. For example, [method InputEvent.is_action_pressed] checks for echo events and ignores them automatically, while [method Input.is_action_pressed] treats echo events like non-echo events.
|
||||
</description>
|
||||
</method>
|
||||
<method name="add_child">
|
||||
|
|
Loading…
Reference in New Issue