diff --git a/tutorials/inputs/img/input_event_flow.png b/tutorials/inputs/img/input_event_flow.png deleted file mode 100644 index d031ac85b..000000000 Binary files a/tutorials/inputs/img/input_event_flow.png and /dev/null differ diff --git a/tutorials/inputs/img/input_event_flow.webp b/tutorials/inputs/img/input_event_flow.webp new file mode 100644 index 000000000..c6a6005a7 Binary files /dev/null and b/tutorials/inputs/img/input_event_flow.webp differ diff --git a/tutorials/inputs/inputevent.rst b/tutorials/inputs/inputevent.rst index 8df0f5565..2406a2abd 100644 --- a/tutorials/inputs/inputevent.rst +++ b/tutorials/inputs/inputevent.rst @@ -61,19 +61,19 @@ How does it work? Every input event is originated from the user/player (though it's possible to generate an InputEvent and feed them back to the engine, -which is useful for gestures). The OS object for each platform will read -events from the device, then feed them to the :ref:`Window `. +which is useful for gestures). The DisplayServer for each platform will read +events from the operating system, then feed them to the root :ref:`Window `. The window's :ref:`Viewport ` does quite a lot of stuff with the received input, in order: -.. image:: img/input_event_flow.png +.. image:: img/input_event_flow.webp 1. If the Viewport is embedding Windows, the Viewport tries to interpret the event in its capability as a Window-Manager (e.g. for resizing or moving Windows). 2. Next if an embedded Window is focused, the event is sent to that Window and processed in - the Windows Viewport. If no embedded Window is focused, The Event is sent to the nodes of - the current viewport in the following order. + the Windows Viewport and afterwards treated as handled. If no embedded Window is focused, + the event is sent to the nodes of the current viewport in the following order. 3. First of all, the standard :ref:`Node._input() ` function will be called in any node that overrides it (and hasn't disabled input processing with :ref:`Node.set_process_input() `). If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() `, and the event will @@ -96,17 +96,17 @@ received input, in order: :ref:`InputEventShortcut ` and :ref:`InputEventJoypadButton `. If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() `, and the event will not spread any more. The shortcut input callback is ideal for treating events that are intended as shortcuts. -6. If so far no one consumed the event, the :ref:`Node._unhandled_input() ` callback - will be called if overridden (and not disabled with - :ref:`Node.set_process_unhandled_input() `). - If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() `, and the - 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. -7. If so far no one consumed the event, the :ref:`Node._unhandled_key_input() ` callback +6. If so far no one consumed the event, the :ref:`Node._unhandled_key_input() ` callback will be called if overridden (and not disabled with :ref:`Node.set_process_unhandled_key_input() `). This happens only if the event is a :ref:`InputEventKey `. If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() `, and the event will not spread any more. The unhandled key input callback is ideal for key events. +7. If so far no one consumed the event, the :ref:`Node._unhandled_input() ` callback + will be called if overridden (and not disabled with + :ref:`Node.set_process_unhandled_input() `). + If any function consumes the event, it can call :ref:`Viewport.set_input_as_handled() `, and the + 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. 8. If no one wanted the event so far, and :ref:`Object Picking ` is turned on, the event is used for object picking. For the root viewport, this can also be enabled in :ref:`Project Settings `. @@ -119,7 +119,7 @@ received input, in order: When sending events to its child and descendant nodes, the viewport will do so, as depicted in the following graphic, in a reverse depth-first order, starting with the node at the bottom of -the scene tree, and ending at the root node. Excluded from this process are embedded Windows +the scene tree, and ending at the root node. Excluded from this process are Windows and SubViewports. .. image:: img/input_event_scene_flow.png @@ -131,8 +131,8 @@ Since Viewports don't send events to other :ref:`SubViewports `, which automatically - sends events to its child :ref:`SubViewports ` during - :ref:`Node._input() ` and :ref:`Node._unhandled_input() `. + sends events to its child :ref:`SubViewports ` after + :ref:`Node._input() ` or :ref:`Control._gui_input() `. 2. Implement event propagation based on the individual requirements. 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 There are several specialized types of InputEvent, described in the table below: -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| Event | Type Index | Description | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEvent ` | NONE | Empty Input Event. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventKey ` | KEY | Contains a keycode and Unicode value, | -| | | as well as modifiers. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventMouseButton ` | MOUSE_BUTTON | Contains click information, such as | -| | | button, modifiers, etc. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventMouseMotion ` | MOUSE_MOTION | Contains motion information, such as | -| | | relative, absolute positions and speed. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventJoypadMotion ` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis | -| | | information. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventJoypadButton ` | JOYSTICK_BUTTON | Contains Joystick/Joypad button | -| | | information. | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventScreenTouch ` | SCREEN_TOUCH | Contains multi-touch press/release | -| | | information. (only available on mobile | -| | | devices) | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventScreenDrag ` | SCREEN_DRAG | Contains multi-touch drag information. | -| | | (only available on mobile devices) | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventAction ` | SCREEN_ACTION | Contains a generic action. These events | -| | | are often generated by the programmer | -| | | as feedback. (more on this below) | -+-------------------------------------------------------------------+--------------------+-----------------------------------------+ ++-------------------------------------------------------------------+-----------------------------------------+ +| Event | Description | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEvent ` | Empty Input Event. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventKey ` | Contains a keycode and Unicode value, | +| | as well as modifiers. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventMouseButton ` | Contains click information, such as | +| | button, modifiers, etc. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventMouseMotion ` | Contains motion information, such as | +| | relative and absolute positions and | +| | speed. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventJoypadMotion ` | Contains Joystick/Joypad analog axis | +| | information. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventJoypadButton ` | Contains Joystick/Joypad button | +| | information. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventScreenTouch ` | Contains multi-touch press/release | +| | information. (only available on mobile | +| | devices) | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventScreenDrag ` | Contains multi-touch drag information. | +| | (only available on mobile devices) | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventMagnifyGesture ` | Contains a position, a factor as well | +| | as modifiers. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventPanGesture ` | Contains a position, a delta as well as | +| | modifiers. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventMIDI ` | Contains MIDI-related information. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventShortcut ` | Contains a shortcut. | ++-------------------------------------------------------------------+-----------------------------------------+ +| :ref:`InputEventAction ` | Contains a generic action. These events | +| | are often generated by the programmer | +| | as feedback. (more on this below) | ++-------------------------------------------------------------------+-----------------------------------------+ Actions -------