Skip to content

Commit 512a675

Browse files
SauermannSauermann
committed
Update input event tutorial
Update input event flow graphic based on recent changes. Made some descriptions more precise. Input Event table: - Added missing InputEvents Gesture, MIDI and Shortcut - Removed unused Type Index column
1 parent dac6f82 commit 512a675

File tree

3 files changed

+56
-45
lines changed

3 files changed

+56
-45
lines changed

‎tutorials/inputs/img/input_event_flow.png‎

-13.9 KB
Binary file not shown.

‎tutorials/inputs/img/input_event_flow.webp‎

6.71 KB
Loading

‎tutorials/inputs/inputevent.rst‎

Lines changed: 56 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -61,19 +61,19 @@ How does it work?
6161

6262
Every input event is originated from the user/player (though it's
6363
possible to generate an InputEvent and feed them back to the engine,
64-
which is useful for gestures). The OS object for each platform will read
65-
events from the device, then feed them to the :ref:`Window <class_Window>`.
64+
which is useful for gestures). The DisplayServer for each platform will read
65+
events from the operating system, then feed them to the root :ref:`Window <class_Window>`.
6666

6767
The window's :ref:`Viewport <class_Viewport>` does quite a lot of stuff with the
6868
received input, in order:
6969

70-
.. image:: img/input_event_flow.png
70+
.. image:: img/input_event_flow.webp
7171

7272
1. If the Viewport is embedding Windows, the Viewport tries to interpret the event in its
7373
capability as a Window-Manager (e.g. for resizing or moving Windows).
7474
2. Next if an embedded Window is focused, the event is sent to that Window and processed in
75-
the Windows Viewport. If no embedded Window is focused, The Event is sent to the nodes of
76-
the current viewport in the following order.
75+
the Windows Viewport and afterwards treated as handled. If no embedded Window is focused,
76+
the event is sent to the nodes of the current viewport in the following order.
7777
3. First of all, the standard :ref:`Node._input() <class_Node_method__input>` function
7878
will be called in any node that overrides it (and hasn't disabled input processing with :ref:`Node.set_process_input() <class_Node_method_set_process_input>`).
7979
If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() <class_Viewport_method_set_input_as_handled>`, and the event will
@@ -96,17 +96,17 @@ received input, in order:
9696
:ref:`InputEventShortcut <class_InputEventShortcut>` and :ref:`InputEventJoypadButton <class_InputEventJoypadButton>`.
9797
If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() <class_Viewport_method_set_input_as_handled>`, and the
9898
event will not spread any more. The shortcut input callback is ideal for treating events that are intended as shortcuts.
99-
6. If so far no one consumed the event, the :ref:`Node._unhandled_input() <class_Node_method__unhandled_input>` callback
100-
will be called if overridden (and not disabled with
101-
:ref:`Node.set_process_unhandled_input() <class_Node_method_set_process_unhandled_input>`).
102-
If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() <class_Viewport_method_set_input_as_handled>`, and the
103-
event will not spread any more. The unhandled input callback is ideal for full-screen gameplay events, so they are not received when a GUI is active.
104-
7. If so far no one consumed the event, the :ref:`Node._unhandled_key_input() <class_Node_method__unhandled_key_input>` callback
99+
6. If so far no one consumed the event, the :ref:`Node._unhandled_key_input() <class_Node_method__unhandled_key_input>` callback
105100
will be called if overridden (and not disabled with
106101
:ref:`Node.set_process_unhandled_key_input() <class_Node_method_set_process_unhandled_key_input>`).
107102
This happens only if the event is a :ref:`InputEventKey <class_InputEventKey>`.
108103
If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() <class_Viewport_method_set_input_as_handled>`, and the
109104
event will not spread any more. The unhandled key input callback is ideal for key events.
105+
7. If so far no one consumed the event, the :ref:`Node._unhandled_input() <class_Node_method__unhandled_input>` callback
106+
will be called if overridden (and not disabled with
107+
:ref:`Node.set_process_unhandled_input() <class_Node_method_set_process_unhandled_input>`).
108+
If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() <class_Viewport_method_set_input_as_handled>`, and the
109+
event will not spread any more. The unhandled input callback is ideal for full-screen gameplay events, so they are not received when a GUI is active.
110110
8. If no one wanted the event so far, and :ref:`Object Picking <class_viewport_property_physics_object_picking>`
111111
is turned on, the event is used for object picking. For the root viewport, this can also be
112112
enabled in :ref:`Project Settings <class_ProjectSettings_property_physics/common/enable_object_picking>`.
@@ -119,7 +119,7 @@ received input, in order:
119119

120120
When sending events to its child and descendant nodes, the viewport will do so, as depicted in
121121
the following graphic, in a reverse depth-first order, starting with the node at the bottom of
122-
the scene tree, and ending at the root node. Excluded from this process are embedded Windows
122+
the scene tree, and ending at the root node. Excluded from this process are Windows
123123
and SubViewports.
124124

125125
.. image:: img/input_event_scene_flow.png
@@ -131,8 +131,8 @@ Since Viewports don't send events to other :ref:`SubViewports <class_SubViewport
131131
methods has to be used:
132132

133133
1. Use a :ref:`SubViewportContainer <class_SubViewportContainer>`, which automatically
134-
sends events to its child :ref:`SubViewports <class_SubViewport>` during
135-
:ref:`Node._input() <class_Node_method__input>` and :ref:`Node._unhandled_input() <class_Node_method__unhandled_input>`.
134+
sends events to its child :ref:`SubViewports <class_SubViewport>` after
135+
:ref:`Node._input() <class_Node_method__input>` or :ref:`Control._gui_input() <class_Control_method__gui_input>`.
136136
2. Implement event propagation based on the individual requirements.
137137

138138
GUI events also travel up the scene tree but, since these events target
@@ -152,37 +152,48 @@ anything and only contains some basic information, such as event ID
152152

153153
There are several specialized types of InputEvent, described in the table below:
154154

155-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
156-
| Event | Type Index | Description |
157-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
158-
| :ref:`InputEvent <class_InputEvent>` | NONE | Empty Input Event. |
159-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
160-
| :ref:`InputEventKey <class_InputEventKey>` | KEY | Contains a keycode and Unicode value, |
161-
| | | as well as modifiers. |
162-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
163-
| :ref:`InputEventMouseButton <class_InputEventMouseButton>` | MOUSE_BUTTON | Contains click information, such as |
164-
| | | button, modifiers, etc. |
165-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
166-
| :ref:`InputEventMouseMotion <class_InputEventMouseMotion>` | MOUSE_MOTION | Contains motion information, such as |
167-
| | | relative, absolute positions and speed. |
168-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
169-
| :ref:`InputEventJoypadMotion <class_InputEventJoypadMotion>` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis |
170-
| | | information. |
171-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
172-
| :ref:`InputEventJoypadButton <class_InputEventJoypadButton>` | JOYSTICK_BUTTON | Contains Joystick/Joypad button |
173-
| | | information. |
174-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
175-
| :ref:`InputEventScreenTouch <class_InputEventScreenTouch>` | SCREEN_TOUCH | Contains multi-touch press/release |
176-
| | | information. (only available on mobile |
177-
| | | devices) |
178-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
179-
| :ref:`InputEventScreenDrag <class_InputEventScreenDrag>` | SCREEN_DRAG | Contains multi-touch drag information. |
180-
| | | (only available on mobile devices) |
181-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
182-
| :ref:`InputEventAction <class_InputEventAction>` | SCREEN_ACTION | Contains a generic action. These events |
183-
| | | are often generated by the programmer |
184-
| | | as feedback. (more on this below) |
185-
+-------------------------------------------------------------------+--------------------+-----------------------------------------+
155+
+-------------------------------------------------------------------+-----------------------------------------+
156+
| Event | Description |
157+
+-------------------------------------------------------------------+-----------------------------------------+
158+
| :ref:`InputEvent <class_InputEvent>` | Empty Input Event. |
159+
+-------------------------------------------------------------------+-----------------------------------------+
160+
| :ref:`InputEventKey <class_InputEventKey>` | Contains a keycode and Unicode value, |
161+
| | as well as modifiers. |
162+
+-------------------------------------------------------------------+-----------------------------------------+
163+
| :ref:`InputEventMouseButton <class_InputEventMouseButton>` | Contains click information, such as |
164+
| | button, modifiers, etc. |
165+
+-------------------------------------------------------------------+-----------------------------------------+
166+
| :ref:`InputEventMouseMotion <class_InputEventMouseMotion>` | Contains motion information, such as |
167+
| | relative and absolute positions and |
168+
| | speed. |
169+
+-------------------------------------------------------------------+-----------------------------------------+
170+
| :ref:`InputEventJoypadMotion <class_InputEventJoypadMotion>` | Contains Joystick/Joypad analog axis |
171+
| | information. |
172+
+-------------------------------------------------------------------+-----------------------------------------+
173+
| :ref:`InputEventJoypadButton <class_InputEventJoypadButton>` | Contains Joystick/Joypad button |
174+
| | information. |
175+
+-------------------------------------------------------------------+-----------------------------------------+
176+
| :ref:`InputEventScreenTouch <class_InputEventScreenTouch>` | Contains multi-touch press/release |
177+
| | information. (only available on mobile |
178+
| | devices) |
179+
+-------------------------------------------------------------------+-----------------------------------------+
180+
| :ref:`InputEventScreenDrag <class_InputEventScreenDrag>` | Contains multi-touch drag information. |
181+
| | (only available on mobile devices) |
182+
+-------------------------------------------------------------------+-----------------------------------------+
183+
| :ref:`InputEventMagnifyGesture <class_InputEventMagnifyGesture>` | Contains a position, a factor as well |
184+
| | as modifiers. |
185+
+-------------------------------------------------------------------+-----------------------------------------+
186+
| :ref:`InputEventPanGesture <class_InputEventPanGesture>` | Contains a position, a delta as well as |
187+
| | modifiers. |
188+
+-------------------------------------------------------------------+-----------------------------------------+
189+
| :ref:`InputEventMIDI <class_InputEventMIDI>` | Contains MIDI-related information. |
190+
+-------------------------------------------------------------------+-----------------------------------------+
191+
| :ref:`InputEventShortcut <class_InputEventShortcut>` | Contains a shortcut. |
192+
+-------------------------------------------------------------------+-----------------------------------------+
193+
| :ref:`InputEventAction <class_InputEventAction>` | Contains a generic action. These events |
194+
| | are often generated by the programmer |
195+
| | as feedback. (more on this below) |
196+
+-------------------------------------------------------------------+-----------------------------------------+
186197

187198
Actions
188199
-------

0 commit comments

Comments
 (0)