|
|
@@ -31,32 +31,32 @@ received input, in order:
|
|
|
.. image:: /img/input_event_flow.png
|
|
|
|
|
|
1. First, it will try to feed the input to the GUI, and see if any
|
|
|
-control can receive it. If so, the :ref:`Control <class_Control>` will be called the
|
|
|
-virtual function :ref:`Control._input_event() <class_Control__input_event>` and the signal
|
|
|
-"input_event" will be emitted (this function is re-implementable by
|
|
|
-script by inheriting from it). If the control wants to "consume" the
|
|
|
-event, it will call :ref:`Control.accept_event() <class_Control_accept_event>` and the event will
|
|
|
-not spread any more.
|
|
|
+ control can receive it. If so, the :ref:`Control <class_Control>` will be called the
|
|
|
+ virtual function :ref:`Control._input_event() <class_Control__input_event>` and the signal
|
|
|
+ "input_event" will be emitted (this function is re-implementable by
|
|
|
+ script by inheriting from it). If the control wants to "consume" the
|
|
|
+ event, it will call :ref:`Control.accept_event() <class_Control_accept_event>` and the event will
|
|
|
+ not spread any more.
|
|
|
2. If the GUI does not want the event, the standard _input function
|
|
|
-will be called in any node with input processing enabled (enable with
|
|
|
-:ref:`Node.set_process_input() <class_Node_set_process_input>`) and override
|
|
|
-:ref:`Node._input() <class_Node__input>`). If any function consumes the event, it can
|
|
|
-call :ref:`SceneTree.set_input_as_handled() <class_SceneTree_set_input_as_handled>`, and the event will
|
|
|
-not spread any more.
|
|
|
+ will be called in any node with input processing enabled (enable with
|
|
|
+ :ref:`Node.set_process_input() <class_Node_set_process_input>`) and override
|
|
|
+ :ref:`Node._input() <class_Node__input>`). If any function consumes the event, it can
|
|
|
+ call :ref:`SceneTree.set_input_as_handled() <class_SceneTree_set_input_as_handled>`, and the event will
|
|
|
+ not spread any more.
|
|
|
3. If so far no one consumed the event, the unhandled input callback
|
|
|
-will be called (enable with
|
|
|
-:ref:`Node.set_process_unhandled_input() <class_Node_set_process_unhandled_input>`) and override
|
|
|
-:ref:`Node._unhandled_input() <class_Node__unhandled_input>`). If any function consumes the
|
|
|
-event, it can call :ref:`SceneTree.set_input_as_handled() <class_SceneTree_set_input_as_handled>`, and the
|
|
|
-event will not spread any more.
|
|
|
+ will be called (enable with
|
|
|
+ :ref:`Node.set_process_unhandled_input() <class_Node_set_process_unhandled_input>`) and override
|
|
|
+ :ref:`Node._unhandled_input() <class_Node__unhandled_input>`). If any function consumes the
|
|
|
+ event, it can call :ref:`SceneTree.set_input_as_handled() <class_SceneTree_set_input_as_handled>`, and the
|
|
|
+ event will not spread any more.
|
|
|
4. If no one wanted the event so far, and a :ref:`Camera <class_Camera>` is assigned
|
|
|
-to the Viewport, a ray to the physics world (in the ray direction from
|
|
|
-the click) will be casted. If this ray hits an object, it will call the
|
|
|
-:ref:`CollisionObject._input_event() <class_CollisionObject__input_event>` function in the relevant
|
|
|
-physics object (bodies receive this callback by default, but areas do
|
|
|
-not. This can be configured through :ref:`Area <class_Area>` properties).
|
|
|
+ to the Viewport, a ray to the physics world (in the ray direction from
|
|
|
+ the click) will be casted. If this ray hits an object, it will call the
|
|
|
+ :ref:`CollisionObject._input_event() <class_CollisionObject__input_event>` function in the relevant
|
|
|
+ physics object (bodies receive this callback by default, but areas do
|
|
|
+ not. This can be configured through :ref:`Area <class_Area>` properties).
|
|
|
5. Finally, if the event was unhandled, it will be passed to the next
|
|
|
-Viewport in the tree, otherwise it will be ignored.
|
|
|
+ Viewport in the tree, otherwise it will be ignored.
|
|
|
|
|
|
Anatomy of an InputEvent
|
|
|
------------------------
|
|
|
@@ -67,7 +67,7 @@ anything and only contains some basic information, such as event ID
|
|
|
|
|
|
InputEvent has a "type" member. By assigning it, it can become
|
|
|
different types of input event. Every type of InputEvent has different
|
|
|
-properties, according to it's role.
|
|
|
+properties, according to its role.
|
|
|
|
|
|
Example of changing event type.
|
|
|
|
|
|
@@ -82,27 +82,37 @@ Example of changing event type.
|
|
|
|
|
|
There are several types of InputEvent, described in the table below:
|
|
|
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| Event | Type Index | Description |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEvent <class_InputEvent>` | NONE | Empty Input Event |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventKey <class_InputEventKey>` | KEY | Contains a scancode and unicode value, as well as modifiers |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventMouseButton <class_InputEventMouseButton>` | MOUSE_BUTTON | Contains click information, such as button, modifiers, etc. |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventMouseMotion <class_InputEventMouseMotion>` | MOUSE_MOTION | Contains motion information, such as relative, absolute positions and speed. |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventJoystickMotion <class_InputEventJoystickMotion>` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis information. |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventJoystickButton <class_InputEventJoystickButton>` | JOYSTICK_BUTTON | Contains Joystick/Joypad button information. |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventScreenTouch <class_InputEventScreenTouch>` | SCREEN_TOUCH | Contains multi-touch press/release information. (only available on mobile devices) |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventScreenDrag <class_InputEventScreenDrag>` | SCREEN_DRAG | Contains multi-touch drag information. (only available on mobile devices) |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
-| :ref:`InputEventAction <class_InputEventAction>` | SCREEN_ACTION | Contains a generic action. These events are often generated by the programmer as feedback. (more on this below) |
|
|
|
-+-------------------------------------------------------------------+--------------------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| Event | Type Index | Description |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEvent <class_InputEvent>` | NONE | Empty Input Event |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventKey <class_InputEventKey>` | KEY | Contains a scancode and unicode value, |
|
|
|
+| | | as well as modifiers |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventMouseButton <class_InputEventMouseButton>` | MOUSE_BUTTON | Contains click information, such as |
|
|
|
+| | | button, modifiers, etc. |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventMouseMotion <class_InputEventMouseMotion>` | MOUSE_MOTION | Contains motion information, such as |
|
|
|
+| | | relative, absolute positions and speed. |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventJoystickMotion <class_InputEventJoystickMotion>` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis |
|
|
|
+| | | information. |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventJoystickButton <class_InputEventJoystickButton>` | JOYSTICK_BUTTON | Contains Joystick/Joypad button |
|
|
|
+| | | information. |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventScreenTouch <class_InputEventScreenTouch>` | SCREEN_TOUCH | Contains multi-touch press/release |
|
|
|
+| | | information. (only available on mobile |
|
|
|
+| | | devices) |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventScreenDrag <class_InputEventScreenDrag>` | SCREEN_DRAG | Contains multi-touch drag information. |
|
|
|
+| | | (only available on mobile devices) |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
+| :ref:`InputEventAction <class_InputEventAction>` | SCREEN_ACTION | Contains a generic action. These events |
|
|
|
+| | | are often generated by the programmer |
|
|
|
+| | | as feedback. (more on this below) |
|
|
|
++-------------------------------------------------------------------+--------------------+-----------------------------------------+
|
|
|
|
|
|
Actions
|
|
|
-------
|
|
|
@@ -142,6 +152,6 @@ InputMap
|
|
|
Customizing and re-mapping input from code is often desired. If your
|
|
|
whole workflow depends on actions, the :ref:`InputMap <class_InputMap>` singleton is
|
|
|
ideal for reassigning or creating different actions at run-time. This
|
|
|
-singleton is not saved (must be modified manually) and it's state is run
|
|
|
+singleton is not saved (must be modified manually) and its state is run
|
|
|
from the project settings (engine.cfg). So any dynamic system of this
|
|
|
type needs to store settings in the way the programmer sees best fit.
|
Rémi Verschelde