Unigine.Input Class
The Input class contains functions for simple manual handling of user inputs using a keyboard, a mouse or a gamepad.
This class represents an engine's singleton.
See Also#
- Input sample in C# Component Samples suite
Usage Examples#
The following example shows a way to move and rotate a node by using the Input class:
Source code (C#)
private Node box = null;
private const float moveSpeed = 1.0f;
private const float turnSpeed = 30.0f;
private void Init()
{
box = Primitives.CreateBox(vec3.ONE);
}
private void Update()
{
if (Unigine.Console.Active)
return;
if (Input.IsKeyPressed(Input.KEY.UP) || Input.IsKeyPressed(Input.KEY.W))
box.Translate(vec3.FORWARD * moveSpeed * Game.IFps);
if (Input.IsKeyPressed(Input.KEY.DOWN) || Input.IsKeyPressed(Input.KEY.S))
box.Translate(vec3.BACK * moveSpeed * Game.IFps);
if (Input.IsKeyPressed(Input.KEY.LEFT) || Input.IsKeyPressed(Input.KEY.A))
box.Rotate(0.0f, 0.0f, turnSpeed * Game.IFps);
if (Input.IsKeyPressed(Input.KEY.RIGHT) || Input.IsKeyPressed(Input.KEY.D))
box.Rotate(0.0f, 0.0f, -turnSpeed * Game.IFps);
}The following code demonstrates how to receive an event that changed the button state to IsKeyDown, IsKeyUp. Such code can also be used for the mouse and touch buttons.
Source code (C#)
private void Update()
{
if (Input.IsKeyDown(Input.KEY.T) || Input.IsKeyUp(Input.KEY.T))
{
InputEventKeyboard e = Input.GetKeyEvent(Input.KEY.T);
Unigine.Console.MessageLine($"{Input.GetKeyName(e.Key)} {e.Action} time = {e.Timestamp} frame = {e.Frame}");
}
}The following code illustrates receiving the immediate input — the user receives the event notification immediately after filtering:
Source code (C#)
private void Init()
{
Input.AddCallback(Input.CALLBACK_INDEX.IMMEDIATE_INPUT, OnImmediateInput);
}
private void OnImmediateInput(InputEvent e)
{
switch (e.Type)
{
case InputEvent.TYPE.INPUT_EVENT_KEYBOARD:
{
InputEventKeyboard k = e as InputEventKeyboard;
Unigine.Console.MessageLine($"keyboard event: {Input.GetKeyName(k.Key)} {k.Action}");
break;
}
case InputEvent.TYPE.INPUT_EVENT_MOUSE_BUTTON:
{
InputEventMouseButton m = e as InputEventMouseButton;
Unigine.Console.MessageLine($"mouse button event: {Input.GetMouseButtonName(m.Button)} {m.Action}");
break;
}
default: break;
}
}The following code illustrates how the event filter works. Pressing the "W" button and mouse movements will be declined, i.e. these events won't be taken as input:
Source code (C#)
private void Init()
{
Input.SetEventsFilter(EventFilter);
}
private int EventFilter(InputEvent e)
{
switch (e.Type)
{
case InputEvent.TYPE.INPUT_EVENT_KEYBOARD:
{
// skip 'W' key repeat events
InputEventKeyboard k = e as InputEventKeyboard;
if (k.Key == Input.KEY.W && k.Action == InputEventKeyboard.ACTION.REPEAT)
return 1;
break;
}
case InputEvent.TYPE.INPUT_EVENT_MOUSE_MOTION:
{
// skip all mouse motion events
return 1;
}
default: break;
}
return 0;
}The following code is an example of input events creation. We'll imitate the input of the show_profiler 1 console command as if it were an event from the keyboard.
Source code (C#)
enum STATE
{
OPEN_CONSOLE = 0,
TYPING_COMMAND,
APPLY_COMMAND,
FINISH,
}
private STATE state = STATE.OPEN_CONSOLE;
private string command = "show_profiler 1";
private void Update()
{
switch (state)
{
case STATE.OPEN_CONSOLE:
{
InputEventKeyboard key = new InputEventKeyboard();
key.Action = InputEventKeyboard.ACTION.DOWN;
key.Key = Input.KEY.BACK_QUOTE;
Input.SendEvent(key);
state = STATE.TYPING_COMMAND;
break;
}
case STATE.TYPING_COMMAND:
{
for (int i = 0; i < command.Length; i++)
{
InputEventText text = new InputEventText();
text.Unicode = (uint)command[i];
Input.SendEvent(text);
}
state = STATE.APPLY_COMMAND;
break;
}
case STATE.APPLY_COMMAND:
{
InputEventKeyboard key = new InputEventKeyboard();
key.Action = InputEventKeyboard.ACTION.REPEAT;
key.Key = Input.KEY.ENTER;
Input.SendEvent(key);
state = STATE.FINISH;
break;
}
default: break;
}
}The following code demonstrates how to obtain various button names using the GetKeyName(), KeyToUnicode(), and GetKeyLocalName() methods:
Source code (C#)
/*...*/
using System.Linq;
using System.Text;
/*...*/
private void Init()
{
Unigine.Console.Onscreen = true;
}
private void Update()
{
var printInfo = (string state, Input.KEY key) =>
{
uint unicode = Input.KeyToUnicode(key);
string unicodeName = Encoding.Unicode.GetString(BitConverter.GetBytes(unicode));
unicodeName = unicodeName.TrimEnd('\0');
Unigine.Console.Message($"{state}: (key='{Input.GetKeyName(key)}', unicode='{unicodeName}', local_name='{Input.GetKeyLocalName(key)}') ");
};
printInfo("Up", Input.KEY.W);
printInfo("Jump", Input.KEY.SPACE);
printInfo("Run", Input.KEY.RIGHT_SHIFT);
Unigine.Console.Message("\n");
}Input Class
Enums
MOUSE_HANDLE#
MOUSE_BUTTON#
MODIFIER#
KEY#
CALLBACK_INDEX#
DEVICE_TYPE#
GAMEPAD_BUTTON#
Buttons of the gamepad.GAMEPAD_AXIS#
JOYSTICK_POV#
POV (Point-of-View) switch or DPad states.Properties
int NumJoysticks#
The number of joysticks.
int NumGamePads#
The number of all gamepads.
int MouseWheelHorizontal#
The horizontal mouse scroll value.
int MouseWheel#
The vertical mouse scroll value.
ivec2 MouseDeltaPosition#
The vector containing delta values of the mouse cursor position.
ivec2 MousePosition#
The vector containing integer values of the mouse cursor position.
Input.MOUSE_HANDLE MouseHandle#
The mouse behavior mode, one of the MOUSE_HANDLE values.
bool MouseCursorNeedUpdate#
The value indicating that changes were made to the cursor (it was shown, hidden, changed to system, or anything else) and it has to be updated. Suppose the cursor was modified, for example, by the Interface plugin. After closing the plugin's window the cursor shall not return to its previous state because SDL doesn't even know about the changes. You can use this flag to signalize, that mouse cursor must be updated.
bool MouseCursorSystem#
The value indicating if the os mouse pointer is displayed.
bool MouseCursorHide#
The value indicating if the mouse cursor is hidden in the current frame.
bool MouseGrab#
The value indicating if the mouse pointer is bound to the application window.
string Clipboard#
The contents of the system clipboard.
bool IsEmptyClipboard#
The value indicating if the clipboard is empty.
ivec2 MouseDeltaRaw#
The change in the absolute mouse position, dots per inch.
Members
InputGamePad GetGamePad ( int num ) #
Returns a gamepad of the given index.Arguments
- int num - Gamepad index.
Return value
InputGamepad object.InputJoystick GetJoystick ( int num ) #
Returns a joystick with the given index.Arguments
- int num - Joystick index.
Return value
InputJoystick object.bool IsKeyPressed ( Input.KEY key ) #
Returns a value indicating if the given key is pressed. Check this value to perform continuous actions.Source code (C#)
if (Input.IsKeyPressed(Input.KEY.ENTER)) {
Log.Message("the Enter key is held down\n");
}Arguments
Return value
true if the key is pressed; otherwise, false.bool IsKeyDown ( Input.KEY key ) #
Returns a value indicating if the given key was pressed during the current frame. Check this value to perform one-time actions on pressing a key.Source code (C#)
if (Input.IsKeyDown(Input.KEY.SPACE)) {
Log.Message("the Space key was pressed\n");
}Arguments
Return value
True during the first frame when the key was pressed, false for the following ones until it is released and pressed again.bool IsKeyUp ( Input.KEY key ) #
Returns a value indicating if the given key was released during the current frame. Check this value to perform one-time actions on releasing a key.Source code (C#)
if (Input.IsKeyUp(Input.KEY.F)) {
Log.Message("the F key was released\n");
}Arguments
Return value
true during the first frame when the key was released; otherwise, false.bool IsMouseButtonPressed ( Input.MOUSE_BUTTON button ) #
Returns a value indicating if the given mouse button is pressed. Check this value to perform continuous actions.Source code (C#)
if (Input.IsMouseButtonPressed(Input.MOUSE_BUTTON.LEFT)) {
Log.Message("the left mouse button is held down\n");
}Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
Return value
True if the mouse button is pressed; otherwise, false.bool IsMouseButtonDown ( Input.MOUSE_BUTTON button ) #
Returns a value indicating if the given mouse button was pressed during the current frame. Check this value to perform one-time actions on pressing a mouse button.Source code (C#)
if (Input.IsMouseButtonDown(Input.MOUSE_BUTTON.LEFT)) {
Log.Message("the left mouse button was pressed\n");
}Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
Return value
True during the first frame when the mouse button was released; otherwise, false.bool IsMouseButtonUp ( Input.MOUSE_BUTTON button ) #
Returns a value indicating if the given mouse button was released during the current frame. Check this value to perform one-time actions on releasing a mouse button.Source code (C#)
if (Input.IsMouseButtonUp(Input.MOUSE_BUTTON.LEFT)) {
Log.Message("left mouse button was released\n");
}Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
Return value
True during the first frame when the mouse button was released; otherwise, false.bool IsTouchPressed ( int index ) #
Returns a value indicating if the touchscreen is pressed by the finger.Arguments
- int index - Touch input index.
Return value
true if the touchscreen is pressed; otherwise, false.bool IsTouchDown ( int index ) #
Returns a value indicating if the given touch was pressed during the current frame.Arguments
- int index - Touch input index.
Return value
true if the touchscreen is pressed during the current frame; otherwise, false.bool IsTouchUp ( int index ) #
Returns a value indicating if the given touch was released.Arguments
- int index - Touch input index.
Return value
true during the first frame when the touch was released; otherwise, false.ivec2 GetTouchPosition ( int index ) #
Returns a vector containing integer values of touch position.Arguments
- int index - Touch input index.
Return value
The touch position.ivec2 GetTouchDelta ( int index ) #
Returns a vector containing screen position change of the touch along the X and Y axes — the difference between the values in the previous and the current frames.Arguments
- int index - Touch input index.
Return value
The touch position delta.InputEventTouch GetTouchEvent ( int index ) #
Returns the action cast to the touch event.Arguments
- int index - Touch input index.
Return value
Touch input event.int GetTouchEvents ( int index, InputEventTouch[] events ) #
Returns the actions cast to the touch event.Arguments
- int index - Touch input index.
- InputEventTouch[] events - The buffer with touch input events.
Return value
Number of touch input events.InputEventKeyboard GetKeyEvent ( Input.KEY key ) #
Returns the currently processed keyboard input event.Arguments
Return value
Keyboard input event, or null if there are no events for the specified key in the current frame.int GetKeyEvents ( Input.KEY key, InputEventKeyboard[] events ) #
Returns the buffer with events for the specified key.Arguments
- Input.KEY key - One of the Input.KEY enum values.
- InputEventKeyboard[] events - The buffer with input events.
string GetKeyName ( Input.KEY key ) #
Returns the specified key name.Arguments
Return value
Key name.Input.KEY GetKeyByName ( string name ) #
Returns the key by its name.Arguments
- string name - Key name.
Return value
One of the Input.KEY enum values.InputEventMouseButton GetMouseButtonEvent ( Input.MOUSE_BUTTON button ) #
Returns the mouse motion input event for the specified button.Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
Return value
Mouse motion input event.string GetMouseButtonName ( Input.MOUSE_BUTTON button ) #
Returns the mouse button name.Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
Return value
Mouse button name.Input.MOUSE_BUTTON GetMouseButtonByName ( string name ) #
Returns the mouse button by its name.Arguments
- string name - Mouse button name.
Return value
One of the Input.MOUSE_BUTTON enum values.int GetEventsBuffer ( int frame, InputEvent[] events ) #
Returns the buffer with the input events for the specified frame.Arguments
- int frame - Number of frame for which the buffer of input events is to be obtained. Input events are stored for the last 60 frames. 0 is the current frame, 1 is the previous frame, etc.
- InputEvent[] events - The buffer with input events.
void SendEvent ( InputEvent e ) #
Creates a user event and dispatches it to the Engine.Arguments
- InputEvent e - Input event.
void SetEventsFilter ( IntPtr func ) #
Sets a callback function to be executed on receiving input events. This input event filter enables you to reject certain input events for the Engine and get necessary information on all input events.Arguments
- IntPtr func - Input event callback.
bool IsModifierEnabled ( Input.MODIFIER modifier ) #
Returns the value indicating if the specified modifier is enabled.Arguments
- Input.MODIFIER modifier - One of the MODIFIER. enum values.
Return value
true if the modifier is enabled; otherwise, false.uint KeyToUnicode ( Input.KEY key ) #
Returns the specified key transformed to unicode.Arguments
Return value
Unicode symbol.Input.KEY UnicodeToKey ( uint unicode ) #
Returns the specified key transformed to unicode.Arguments
- uint unicode - Unicode symbol.
Return value
One of the Input.KEY enum values.void SetMouseCursorSkinCustom ( Image image ) #
Sets a custom image to be used for the mouse cursor.Arguments
- Image image - Image containing pointer shapes to be set for the mouse cursor (e.g., select, move, resize, etc.).
void SetMouseCursorSkinSystem ( ) #
Sets the current OS cursor skin (pointer shapes like select, move, resize, etc.).void SetMouseCursorSkinDefault ( ) #
Sets the default Engine cursor skin (pointer shapes like select, move, resize, etc.).void SetMouseCursorCustom ( Image image, int x = 0, int y = 0 ) #
Sets a custom image for the OS mouse cursor. The image must be of the square size and RGBA8 format.Source code (C#)
// create an instance of the Image class
Image cursor = new Image("textures/my_cursor.png");
// set the image as the mouse cursor
Input.SetMouseCursorCustom(cursor);
// show the OS mouse pointer
Input.MouseCursorSystem = true;Arguments
- Image image - Cursor image to be set.
- int x - X coordinate of the cursor's hot spot.
- int y - Y coordinate of the cursor's hot spot.
void ClearMouseCursorCustom ( ) #
Clears the custom mouse cursor set via the setMouseCursorCustom() method.void UpdateMouseCursor ( ) #
Updates the mouse cursor. This method should be called after making changes to the mouse cursor to apply them all together. After calling this method the cursor shall be updated in the next frame.string GetKeyLocalName ( Input.KEY key ) #
Returns the name for the specified key taken from the currently selected keyboard layout.Notice
The returned value is affected by the modifier such as Shift.
Arguments
Return value
Localized name for the specified key.int GetMouseButtonEvents ( Input.MOUSE_BUTTON button, InputEventMouseButton[] events ) #
Returns the number of input events for the specified mouse button and puts the events to the specified output buffer.Arguments
- Input.MOUSE_BUTTON button - One of the Input.MOUSE_BUTTON enum values.
- InputEventMouseButton[] events - Buffer with input events.
Return value
Number of input events for the specified mouse button.ivec2 GetForceMousePosition ( ) #
Returns the absolute mouse position obtained from the OS.Return value
The absolute mouse position.bool IsKeyText ( Input.KEY key ) #
Returns a value indicating if the given key has a corresponding printable symbol (current Num Lock state is taken into account). For example, pressing 2 on the numpad with Num Lock enabled produces "2", while with disabled Num Lock the same key acts as a down arrow. Keys like Esc, PrintScreen, BackSpace do not produce any printable symbol at all.Arguments
Return value
true if the key value is a symbol; otherwise, false.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for mouse button events. Callback functions can be used to determine actions to be performed when various input events occur. Here is an example of tracking mouse button events via callbacks:Source code (C#)
public void button_clicked(Input.MOUSE_BUTTON button)
{
// actions to be performed ...
}
// somewhere in the code
// setting our callback function on clicking a mouse button
Input.AddCallback(Input.CALLBACK_INDEX.MOUSE_DOWN, button_clicked);Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)button - mouse button.
void CallbackDelegate(Input.MOUSE_BUTTON button);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for the mouse motion event. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)(x, y) - mouse coordinates delta.
void CallbackDelegate(int x, int y);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for keyboard events. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)key - keyboard key code.
void CallbackDelegate(Input.KEY key);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for a unicode key or a touch event. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)code - unicode value displayed for the key or touch index (depending on the callback type).
void CallbackDelegate(uint code);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)event - input event.
void CallbackDelegate(InputEvent event);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for a gamepad button event. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)index - gamepad index. button - gamepad button index.
void CallbackDelegate(uint index, Input.GAMEPAD_BUTTON button);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for a gamepad axis event. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)index - gamepad index. axis - gamepad axis index.
void CallbackDelegate(uint index, Input.GAMEPAD_AXIS axis);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #
Adds a callback of the specified type for an action event. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the following:
- CallbackDelegate func - Callback function with the following signature: Source code (C#)index - device index. action - action index.
void CallbackDelegate(uint index, int action);
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool RemoveCallback ( CALLBACK_INDEX callback, IntPtr id ) #
Removes the specified callback from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the CALLBACK_* variables.
- IntPtr id - Callback ID obtained when adding it.
Return value
true if the callback with the given ID was removed successfully; otherwise false.void ClearCallbacks ( CALLBACK_INDEX callback ) #
Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when various input events occur.Arguments
- CALLBACK_INDEX callback - Callback type. One of the CALLBACK_* variables.
string GetModifierName ( Input.MODIFIER modifier ) #
Returns the name of the key modifier by its scancode.Arguments
- Input.MODIFIER modifier - Scancode of the modifier.
Return value
Key name of the modifier.Input.MODIFIER GetModifierByName ( string name ) #
Returns the scancode of the key modifier by its name.Arguments
- string name - Key name of the modifier.
Return value
Scancode of the modifier.Last update:
2023-04-13
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)