namespace CEGUI {
/**
@page input_tutorial 5 - The Beginners Guide to Injecting Inputs
@author Paul D Turner, Vladimir "Niello" Orlov
@tableofcontents

Having read the previous tutorials in this series, you now have your GUI
rendering set up, the files loaded and even have a window on screen - however
you are probably wanting to have some user interaction too.  This is the subject
of this final tutorial in the series; here we will show the required tasks in
order to end up with a complete functioning GUI in your application.

<br>
@section input_tutorial_intro Introduction to input for CEGUI

@subsection input_tutorial_intro_badnews First the bad news
It shocks some people to discover that CEGUI does not do any automatic
collection of user input; it is the responsibility of the application itself to
tell CEGUI about any events that it needs to know about.  This means that you
have to tell CEGUI each time a key is pressed, or the mouse moves, and so on.
While this may seem strange at first, the reality is that it affords you a lot
more power and flexibility; we are not tying you down to any particular system
for your inputs, and you may additionally filter input before it gets to CEGUI,
although these are more advanced concepts best left for another time.

@subsection input_tutorial_intro_injectors Get your inputs injected
In order to tell CEGUI about the input events going on around it, we have an
input injection interface (CEGUI::InjectedInputReceiver). This provides one
member function for each type of base input:

- bool InjectedInputReceiver::injectMouseMove( float delta_x, float delta_y );
- bool InjectedInputReceiver::injectMousePosition( float x_pos, float y_pos );
- bool InjectedInputReceiver::injectMouseLeaves( void );
- bool InjectedInputReceiver::injectMouseButtonDown( MouseButton button );
- bool InjectedInputReceiver::injectMouseButtonUp( MouseButton button );
- bool InjectedInputReceiver::injectKeyDown( Key::Scan scan_code );
- bool InjectedInputReceiver::injectKeyUp( Key::Scan scan_code );
- bool InjectedInputReceiver::injectChar( utf32 code_point );
- bool InjectedInputReceiver::injectMouseWheelChange( float delta );

And also some optional functions for click and multi-click events (which are
normally automatically generated internally by the system):
- bool InjectedInputReceiver::injectMouseButtonClick( MouseButton button );
- bool InjectedInputReceiver::injectMouseButtonDoubleClick( MouseButton button );
- bool InjectedInputReceiver::injectMouseButtonTripleClick( MouseButton button );

Yes, that's quite a collection!  The first thing that you might notice is that
there appears to be some repetition - things like 'mouse move' and
'mouse position', 'key down' and 'char'.  For the mouse, we offer the
possibility of injecting a relative movement of the mouse from it's last
injected location or an absolute position - which one of these you choose will
largely depend upon the type of inputs that your input library provides you with
for the mouse.  For keys, it is generally required that both up/down strokes and
also characters are injected - there are a couple of reasons for this; first,
not all keys generate a character code (like shift, alt, and so on), and second,
it allows you to do your own custom (or operating system supplied) key-mapping
and key auto-repeat (since CEGUI does not currently offer these functions).

The other thing to notice is the boolean return value from the injection
functions.  This is used to relay back to your application whether or not CEGUI
actually consumed the input.  If this returns false, it means that CEGUI did
nothing useful with the input, and that your application may like to perform
some action based on it instead.

CEGUI implements InjectedInputReceiver internally by the GUIContext.

<br>
@section input_tutorial_detail A little more detail: What each injector is used for
Here we will offer a brief description of what each injection function is used
for, the data it expects, and what, in general, is done with the input.

@subsection input_tutorial_mousemove bool InjectedInputReceiver::injectMouseMove( float delta_x, float delta_y )
This is used to inject relative mouse movements.  The vales @c delta_x and
@c delta_y specify the direction and number of screen pixels the mouse has moved
on the x axis and y axis respectively.  This causes the mouse to move by the
specified amount. Since Sep 2022 update, if you want to scale mouse movement amount,
you should do it in the calling code. CEGUI no longer handles this.
If you inject movement, you generally do not need to use injectMousePosition.

@subsection input_tutorial_mousepos bool InjectedInputReceiver::injectMousePosition( float x_pos, float y_pos )
This is used to inject the current absolute position of the mouse.  The values
@c x_pos and @c y_pos specify the position of the mouse in pixels, where a
position of (0, 0) represents the top-left hand corner of the CEGUI display
(so if you're in windowed mode, it's the corner of the window and not the corner
of the entire screen).  The CEGUI mouse cursor will be set to the new position.
Actually this function calls injectMouseMove inside calculating movement
amount as a difference between the current CEGUI cursor position and the new one.
If you inject position, you generally do not need to use injectMouseMove.

@subsection input_tutorial_mouseleaves bool InjectedInputReceiver::injectMouseLeaves( void )
This function informs CEGUI that the mouse cursor has left the host window that
CEGUI considers it's rendering area.  This is useful if running in windowed mode
to inform widgets that the mouse has actually left the CEGUI display completely
(otherwise it may not get to know, since under many systems no more mouse events
are generated for an OS window once the mouse has left it).

@subsection input_tutorial_mbdown bool InjectedInputReceiver::injectMouseButtonDown( MouseButton button )
This tells CEGUI that a mouse button has been pressed down.  The value @c button
is one of the CEGUI::MouseButton enumerated values, which are as follows:
@code
enum class MouseButton
{
    Left = 0,
    Right,
    Middle,
    X1,
    X2,
    Count,
    Invalid
};
@endcode

If the values from your input library do not match these, you will have to
perform a translation step.  Also note that the value Invalid is not 0.

When the mouse down event is injected, the Window under the cursor becomes active,
and mouse click tracking is updated. If the window supports auto-repeating of the
mouse down event (isCursorAutoRepeatEnabled()), repeated events will be generated
for the target window until injectMouseButtonUp is called for this GUIContext.
Only the last pressed button generates repeated down events.

In the case event was not handled by the target Window, it can be propagated to
the parent if isCursorInputPropagationEnabled() for the target window returns true
and the current window is not modal. This works recursively until the event is
handled or further propagation is forbidden or the root window is reached.

Regardles of being handled, a mouse down event is considered consumed by CEGUI if
it was sent to any non-input-transparent window (i.e. isCursorPassThroughEnabled()
is false). This prevents mouse clicks leaking through GUI visuals into the external scene.

@subsection input_tutorial_mbup bool InjectedInputReceiver::injectMouseButtonUp( MouseButton button )
This tells CEGUI that a mouse button has been released.  As for the
InjectedInputReceiver::injectMouseButtonDown function, the value @c button is
one of the CEGUI::MouseButton enumerated values.

Injecting this event stops generation of auto-repeated mouse down events.

Before a mouse up event is sent to the window, click events may be generated by CEGUI.
See @ref input_tutorial_clickgen for complete description.

Child to parent propagation, cursor passthrough and event consuming work the same
way as for mouse down events.

@subsection input_tutorial_keydown bool InjectedInputReceiver::injectKeyDown( Key::Scan scan_code )
This tells CEGUI that a key has been pressed.  The value @c scan_code is the scan
code for the key - note that this is not an ASCII or other text encoding value.
The available scan codes are defined in the CEGUI::Key::Scan enumeration.  If
you are using Microsoft DirectInput, then our scan codes are the same ones
output by that library, in other cases you may be required to perform some
translation.  Note that for current releases, and depending upon your expected
use, it may not be required to inject @e all key down/up strokes - the most
common ones that you likely will need are for backspace, delete, enter, modifier
keys (Alt, Shift, Ctrl/Cmd) and the arrow keys.

At present no automatic key mapping and generation of character codes is
performed, also there is no integrated key auto-repeat functionality - though
these functions may appear in future releases.  If you need key auto-repeat then
you will need to either use an input library that offers this function, or
implement something directly.  Of course you will almost certainly need
character input, so for that look at the InjectedInputReceiver::injectChar
function below.

@subsection input_tutorial_keyup bool InjectedInputReceiver::injectKeyUp( Key::Scan scan_code )
This tells CEGUI that a key has been released.  As for the
InjectedInputReceiver::injectKeyDown function, the value @c scan_code is a scan
code for the key - and again note that this is not an ASCII or other text
encoding value - see above for a more detailed description of the key scan
codes.

@subsection input_tutorial_char bool InjectedInputReceiver::injectChar( utf32 code_point )
This function tells CEGUI that a character key has been pressed - you will need
this in order to input text into CEGUI widgets.  The value @c code_point' is a
Unicode UTF32 code point value (see the unicode website at http://unicode.org/
for information about unicode).  How you obtain this value is something that is
dependant upon the input library that you are using.  For many people, who just
wish to use ASCII values, you can just pass in your ASCII codes unmodified,
since Unicode values between 0 and 127 are the same as the standard ASCII codes.
For other uses, you will need to consult the API documentation for your input
library (it is possible, for example, to get the Microsoft Windows message pump
to send you key codes in UTF32 form, though exactly how it is done is beyond the
scope of this introductory tutorial).

@subsection input_tutorial_mwheel bool InjectedInputReceiver::injectMouseWheelChange( float delta )
This function is used to tell CEGUI about the use of the mouse wheel or scroll
wheel (whatever you like to call it).  Use positive values for forward movement
(rolling the wheel away from the user), and negative values for backwards
movement (rolling the wheel towards the user). This event is a bit special
because it is first sent to the window under the cursor, and if it and its
parent do not handle the scroll, the event is sent to the window that has the
input focus, i.e. to an active window.

@subsection input_tutorial_click bool InjectedInputReceiver::injectMouseButtonClick( MouseButton button )
This is an optional injection function that informs CEGUI that a mouse button
click has occurred; normally that is a down -> up sequence.  Calling this
function is only necessary if the built-in automatic generation of click and
multi-click events is unsuitable for your needs.  If you decide you need to use
this function you will normally disable the automatic event generation first by
way of the GUIContext::setMouseClickEventGeneration function.  While it is
possible to call this injection function \e without disabling the auto generated
events, it will affect the behaviour as to the way events are marked as
'handled' and therefore the return code from this function.

@subsection input_tutorial_doubleclick bool InjectedInputReceiver::injectMouseButtonDoubleClick( MouseButton button )
This is an optional injection function that informs CEGUI that a mouse button
double-click has occurred; normally that is a down -> up -> down sequence.
Calling this function is only necessary if the built-in automatic generation of
click and multi-click events is unsuitable for your needs.  If you decide you
need to use this function you will normally disable the automatic event
generation first by way of the GUIContext::setMouseClickEventGeneration
function.  While it is possible to call this injection function \e without
disabling the auto generated events, it will affect the behaviour as to the way
events are marked as 'handled' and therefore the return code from this function.

@subsection input_tutorial_tripleclick bool InjectedInputReceiver::injectMouseButtonTripleClick( MouseButton button )
This is an optional injection function that informs CEGUI that a mouse button
triple-click has occurred; normally that is a down -> up -> down -> up -> down
sequence.  Calling this function is only necessary if the built-in automatic
generation of click and multi-click events is unsuitable for your needs.  If you
decide you need to use this function you will normally disable the automatic
event generation first by way of the GUIContext::setMouseClickEventGeneration
function.  While it is possible to call this injection function \e without
disabling the auto generated events, it will affect the behaviour as to the way
events are marked as 'handled' and therefore the return code from this function.

<br>
@section input_tutorial_clickgen Click event generation
CEGUI supports automatic generation of click events from mouse down and up events.
There are some rules for such generation though. First, down and up must happen
within the same window. Since there is a possibility of child to parent propagation,
CEGUI remembers what hierarchy chain received the down event, from the most nested
window (immediate cursor target) to the window that handled the down event, or to
the root window. Second, both down and up must happen within the same window visually.
This means that even with capturing the mouse cursor, there won't be a click generated
if mouse up happened outside the window hit area.

Click generator tries to find the most nested window in the clicked hierarchy which
satisfies these conditions. As soon as the window is found, a click event is sent to
it, and its further propagation stops regardless of whether the click was handled.
Mouse up propagation continues normally.

@subsection input_tutorial_click_settings Click generation settings
Use GUIContext::setMouseClickEventGeneration to set the click generation limit.
Setting it to 0 prevents click auto-generations and you have to inject clicks
manually. Setting it to 1 limits the system to generate single clicks only,
and so forth. There is no artificial cap for this settings, but practically
one rarely needs multi-clicks of the order higher than 3.

GUIContext::setMouseButtonMultiClickTimeout and
GUIContext::setMouseButtonMultiClickTolerance are used for multi-clicks
generation. Default values provide the familiar experience, but you may
cnage it to your liking. More on multi-click generation just below.

@subsection input_tutorial_multiclick Multi-clicks
CEGUI is capable of generating double and triple clicks, and windows provide
virtual methods onDoubleClick and onTripleClick along with corresponding events.
For multi-click to be generated, mouse down and up events must happen within
the certain distance threshold and timeout. Once these locality conditions
are violated, the click tracker is reset and generates a new single click.

Window is not obliged to implement multi-click handlers. In this situation,
a window is taken a chance to handle a multi-click as a single click. If
this happens, a tracker is updated so that this click is counted as single.
Among other, this behaviour allows a window to handle only single and double
clicks and skip generation of triple clicks. A side effect of this behaviour
is that for receiving triple clicks you either have to mark double clicks
handled or skip handling single clicks.

MouseButtonEventArgs::d_generatedClickEventOrder field does its best to
tell the receiver the current order of the generated multi-click event.
This enables handling 4-clicks and higher order clicks given the click
generation order limit is high enough. But windows have no special
callbacks for these multi-clicks. You need to use onClick.

@subsection input_tutorial_multiclick Mouse button event order
A order of mouse button events will be as follows:
- onMouseButtonDown
- onClick
- onMouseButtonUp
- onMouseButtonDown
- onDoubleClick
- onMouseButtonUp
- onMouseButtonDown
- onTripleClick
- onMouseButtonUp
and so on in a loop. Handling multi-click event as a single click
resets the counter so that the next click will be treated as double.

<br>
@section input_tutorial_targets Input targets (receivers)
Input events are intended to be processed by some Window and, under some
circumstances, its parents.

Keyboard events go to the window that has input focus. In CEGUI it is also
called an "active window". An active window may have a distinctive look to
indicate that keyboard input will go there. GUIContext::getInputTargetWindow()
is responsible for determining this kind of target.

Most of mouse events target the window under cursor, no matter if it is enabled
or not. GUIContext::getCursorTargetWindow() is responsible for determining this
kind of target. Invisible window can't be a mouse target.

Wheel events are special in this. First, an attempt is made to handle the
wheel event in the cursor target. And if it is not handled there, it is
dispatched to the focused (active) window. This behaviour was inspired by
how Qt handles mouse wheel messages.

Window can <b>capture input</b>, in this case it and its children will intercept
input messages from both mouse and keyboard. Mouse inputs are distributed
to children if Window::distributesCapturedInputs() is true. Keyboard
inputs are sent to the active window if it or its parent holds the capture.
In other cases a capture window itself receives all input events.

One window at a time in each context can be made <b>modal</b> by the call to
GUIContext::setModalWindow(). Setting nullptr makes no window being modal
in the given context. A modal window works much like a capturing window,
restricting input handling to it and its children.
NB: for cursor target, the modal window overrules the capturing window,
but for keyboard input the opposite is true. This may be changed later.

<br>
@section input_tutorial_eventargs Event arguments
KeyEventArgs are sent to keyboard down and up events and besides the key
scan code they bear an information about modifier keys currently pressed.
Modifier keys are Alt, Shift, Ctrl / Cmd. Others may be added in the future.

TextEventArgs are sent to character input handlers, with UTF-32 character code.

Mouse related events accept CursorInputEventArgs and its various subclasses.
CursorInputEventArgs provides a cursor position in pixels in different
coordinate systems:
- screen (or GUI context rendering surface) coordinates
- coordinates on the immediate rendering surface of the window
- local coordinates relative to the window origin
Besides this, pressed modifier keys and pressed mouse buttons are provided.

CursorMoveEventArgs are extended with movement delta in pixels and is sent to
mouse movement and dragging handlers.

MouseButtonEventArgs are extended with the button that caused the event,
and the order of an automatically generated click, if it was generated.
These args are passed to down, up and click events.

ScrollEventArgs are extended with the wheel scroll amount.

<br>
@section input_tutorial_semantic Semantics
Semantics are input events or actions abstracted from exact keys / buttons and
even from exact input device types. They are useful for defining consistent
mapping for typical GUI application operations. For example, well known
Cut, Copy, Paste, Undo or Redo actions can be represented as CEGUI semantics,
removing the need to hardcode keys like Ctrl+C etc.

CEGUI defines a wide set of predefined semantics in CEGUI::SemanticValue.
Each value is a string, so your application can define additional semantics
easily without altering CEGUI code. GUIContext::initDefaultInputSemantics()
initializes a default mapping for predefined semantics. These rules must be
enough for most of users, but you are not required to use them. You may
override it partially or even define your own complete set of rules from
scratch, again without altering the library code.

Currently semantic rules are specific to input devices, with most useful ones
being for keyboard. This means that your exotic input devices must be injected
as keyboard or mouse input. This may be improved in the future based on user
requests. E.g. we can relatively easily add semantic rules for raw text input,
but this requires adding a support for raw text input first :)

<br>
@section input_tutorial_conclusion Conclusion
Here we have seen the general idiom that CEGUI uses for obtaining externally
generated input events.  We have seen the methods for passing these inputs to
CEGUI, and the type and format of the information to be passed.

Unlike some of the other tutorials in this series, we did not provide concrete
code examples.  The main reason for this was to keep the tutorial reasonably
short; to prevent it becoming a jumble of code for every possible combination of
input system, and in the process causing more confusion.  The use of any
individual input library could easily fill a tutorial of it's own.
*/
}
