This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine::Input Class

Header: #include <UnigineInput.h>

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++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

#include <UnigineConsole.h>

#include <UnigineGame.h>
#include <UniginePrimitives.h>

using namespace Unigine;

using namespace Math;

NodePtr box;

float move_speed = 1.0f;
float turn_speed = 30.0f;

int AppWorldLogic::init()
{

	box = Primitives::createBox(vec3_one);

	return 1;
}

int AppWorldLogic::update()
{

	if (Console::isActive())
		return 1;

	if (Input::isKeyPressed(Input::KEY_UP) || Input::isKeyPressed(Input::KEY_W))
		box->translate(Vec3_forward * move_speed * Game::getIFps());

	if (Input::isKeyPressed(Input::KEY_DOWN) || Input::isKeyPressed(Input::KEY_S))
		box->translate(Vec3_back * move_speed * Game::getIFps());

	if (Input::isKeyPressed(Input::KEY_LEFT) || Input::isKeyPressed(Input::KEY_A))
		box->rotate(0.0f, 0.0f, turn_speed * Game::getIFps());

	if (Input::isKeyPressed(Input::KEY_RIGHT) || Input::isKeyPressed(Input::KEY_D))
		box->rotate(0.0f, 0.0f, -turn_speed * Game::getIFps());

	return 1;
}

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++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

#include <UnigineConsole.h>

using namespace Unigine;

int AppWorldLogic::update()
{

	if (Input::isKeyDown(Input::KEY_T) || Input::isKeyUp(Input::KEY_T))
	{
		InputEventKeyboardPtr e = Input::getKeyEvent(Input::KEY_T);
		Console::messageLine("%s %d time = %lld frame = %lld", Input::getKeyName(e->getKey()), e->getAction(), e->getTimestamp(), e->getFrame());
	}

	return 1;
}

The following code illustrates receiving the immediate input — the user receives the event notification immediately after filtering:

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

#include <UnigineConsole.h>

using namespace Unigine;

int AppWorldLogic::init()
{

	Input::addCallback(Input::CALLBACK_IMMEDIATE_INPUT, MakeCallback(on_immediate_input));

	return 1;
}

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++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

using namespace Unigine;

int event_filter(InputEventPtr& e)
{
	switch (e->getType())
	{
	case InputEvent::INPUT_EVENT_KEYBOARD:
	{
		// skip 'W' key repeat events
		InputEventKeyboardPtr k = checked_ptr_cast<InputEventKeyboard>(e);
		if (k->getKey() == Input::KEY_W && k->getAction() == InputEventKeyboard::ACTION_REPEAT)
			return 1;
		break;
	}

	case InputEvent::INPUT_EVENT_MOUSE_MOTION:
	{
		// skip all mouse motion events
		return 1;
	}

	default: break;
	}

	return 0;
}

int AppWorldLogic::init()
{

	Input::setEventsFilter(event_filter);

	return 1;
}

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++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

using namespace Unigine;

enum
{
	STATE_OPEN_CONSOLE = 0,
	STATE_TYPING_COMMAND,
	STATE_APPLY_COMMAND,
	STATE_FINISH,
};

int state = STATE_OPEN_CONSOLE;

void emulate_key_input(Input::KEY key)
{
	InputEventKeyboardPtr key_down = InputEventKeyboard::create();
	key_down->setAction(InputEventKeyboard::ACTION_DOWN);
	key_down->setKey(key);

	InputEventKeyboardPtr key_repeat = InputEventKeyboard::create();
	key_repeat->setAction(InputEventKeyboard::ACTION_REPEAT);
	key_repeat->setKey(key);

	InputEventKeyboardPtr key_up = InputEventKeyboard::create();
	key_up->setAction(InputEventKeyboard::ACTION_UP);
	key_up->setKey(key);

	Input::sendEvent(key_down);
	Input::sendEvent(key_repeat);
	Input::sendEvent(key_up);
}

void emulate_text_input(const char *text)
{
	int size = strlen(text);
	for (int i = 0; i < size; i++)
	{
		InputEventTextPtr text_input = InputEventText::create();
		text_input->setUnicode(text[i]);
		Input::sendEvent(text_input);
	}
}

int AppWorldLogic::update()
{
	switch (state)
	{
		case STATE_OPEN_CONSOLE:
		{
			emulate_key_input(Input::KEY_BACK_QUOTE);
			state = STATE_TYPING_COMMAND;
			break;
		}

		case STATE_TYPING_COMMAND:
		{
			emulate_text_input("show_profiler 1");
			state = STATE_APPLY_COMMAND;
			break;
		}

		case STATE_APPLY_COMMAND:
		{
			emulate_key_input(Input::KEY_ENTER);
			state = STATE_FINISH;
			break;
		}

		default: break;
	}

	return 1;
}

The following code demonstrates how to obtain various button names using the getKeyName(), keyToUnicode(), and getKeyLocalName() methods:

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineInput.h>

#include <UnigineConsole.h>

using namespace Unigine;

int AppWorldLogic::init()
{

	Console::setOnscreen(true);

	return 1;
}

int AppWorldLogic::update()
{

	auto print_info = [](const char* state, Input::KEY key)
	{
		unsigned int unicode = Input::keyToUnicode(key);
		Console::message("%s: (key='%s', unicode='%s', local_name='%s') ",
			state,
			Input::getKeyName(key),
			String::unicodeToUtf8(unicode).get(),
			Input::getKeyLocalName(key));
	};

	print_info("Up", Input::KEY_W);
	print_info("Jump", Input::KEY_SPACE);
	print_info("Run", Input::KEY_RIGHT_SHIFT);
	Console::message("\n");

	return 1;
}

Input Class

Enums

MOUSE_HANDLE#

NameDescription
MOUSE_HANDLE_GRAB = 0The mouse is grabbed when clicked (the cursor disappears and camera movement is controlled by the mouse).
MOUSE_HANDLE_SOFT = 1The mouse cursor disappears after being idle for a short time period.
MOUSE_HANDLE_USER = 2The mouse is not handled by the system (allows input handling by some custom module).

MOUSE_BUTTON#

NameDescription
MOUSE_BUTTON_UNKNOWN = 0Unknown mouse button.
MOUSE_BUTTON_LEFT = 1Left mouse button.
MOUSE_BUTTON_MIDDLE = 2Middle mouse button.
MOUSE_BUTTON_RIGHT = 3Right mouse button.
MOUSE_BUTTON_DCLICK = 4Left mouse button double click.
MOUSE_BUTTON_AUX_0 = 5Auxiliary mouse button.
MOUSE_BUTTON_AUX_1 = 6Auxiliary mouse button.
MOUSE_BUTTON_AUX_2 = 7Auxiliary mouse button.
MOUSE_BUTTON_AUX_3 = 8Auxiliary mouse button.
MOUSE_NUM_BUTTONS = 9Number of mouse buttons.

MODIFIER#

NameDescription
MODIFIER_LEFT_SHIFT = 0Left Shift key used as modifier.
MODIFIER_RIGHT_SHIFT = 1Right Shift key used as modifier.
MODIFIER_LEFT_CTRL = 2Left Ctrl key used as modifier.
MODIFIER_RIGHT_CTRL = 3Right Ctrl key used as modifier.
MODIFIER_LEFT_ALT = 4Left Alt key used as modifier.
MODIFIER_RIGHT_ALT = 5Right Alt key used as modifier.
MODIFIER_LEFT_CMD = 6Left Command key used as modifier.
MODIFIER_RIGHT_CMD = 7Right Command key used as modifier.
MODIFIER_NUM_LOCK = 8Num Lock key used as modifier.
MODIFIER_CAPS_LOCK = 9Caps Lock key used as modifier.
MODIFIER_SCROLL_LOCK = 10Scroll Lock key used as modifier.
MODIFIER_ALT_GR = 11Alt Gr key used as modifier.
MODIFIER_ANY_SHIFT = 12Any Shift key used as modifier.
MODIFIER_ANY_CTRL = 13Any Ctrl key used as modifier.
MODIFIER_ANY_ALT = 14Any Alt key used as modifier.
MODIFIER_ANY_CMD = 15Any Command key used as modifier.
MODIFIER_NONE = 16
NUM_MODIFIERS = 17

KEY#

NameDescription
KEY_UNKNOWN = 0Unknown key
KEY_ESC = 1Escape key
KEY_F1 = 2F1 key
KEY_F2 = 3F2 key
KEY_F3 = 4F3 key
KEY_F4 = 5F4 key
KEY_F5 = 6F5 key
KEY_F6 = 7F6 key
KEY_F7 = 8F7 key
KEY_F8 = 9F8 key
KEY_F9 = 10F9 key
KEY_F10 = 11F10 key
KEY_F11 = 12F11 key
KEY_F12 = 13F12 key
KEY_PRINTSCREEN = 14Print Screen key
KEY_SCROLL_LOCK = 15Scroll Lock key
KEY_PAUSE = 16Pause key
KEY_BACK_QUOTE = 17Back quote key
KEY_DIGIT_1 = 18The 1 key of the alphanumeric keyboard
KEY_DIGIT_2 = 19The 2 key of the alphanumeric keyboard
KEY_DIGIT_3 = 20The 3 key of the alphanumeric keyboard
KEY_DIGIT_4 = 21The 4 key of the alphanumeric keyboard
KEY_DIGIT_5 = 22The 5 key of the alphanumeric keyboard
KEY_DIGIT_6 = 23The 6 key of the alphanumeric keyboard
KEY_DIGIT_7 = 24The 7 key of the alphanumeric keyboard
KEY_DIGIT_8 = 25The 8 key of the alphanumeric keyboard
KEY_DIGIT_9 = 26The 9 key of the alphanumeric keyboard
KEY_DIGIT_0 = 27The 0 key of the alphanumeric keyboard
KEY_MINUS = 28Minus key
KEY_EQUALS = 29Equals key
KEY_BACKSPACE = 30Backspace key
KEY_TAB = 31Tab key
KEY_Q = 32Q key
KEY_W = 33W key
KEY_E = 34E key
KEY_R = 35R key
KEY_T = 36T key
KEY_Y = 37Y key
KEY_U = 38U key
KEY_I = 39I key
KEY_O = 40O key
KEY_P = 41P key
KEY_LEFT_BRACKET = 42Left square bracket key
KEY_RIGHT_BRACKET = 43Right square bracket key
KEY_ENTER = 44Enter key
KEY_CAPS_LOCK = 45Caps Lock key
KEY_A = 46A key
KEY_S = 47S key
KEY_D = 48D key
KEY_F = 49F key
KEY_G = 50G key
KEY_H = 51H key
KEY_J = 52J key
KEY_K = 53K key
KEY_L = 54L key
KEY_SEMICOLON = 55Semicolon key
KEY_QUOTE = 56Quote key
KEY_BACK_SLASH = 57Backward slash key
KEY_LEFT_SHIFT = 58Left Shift key
KEY_LESS = 59Less than key
KEY_Z = 60Z key
KEY_X = 61X key
KEY_C = 62C key
KEY_V = 63V key
KEY_B = 64B key
KEY_N = 65N key
KEY_M = 66M key
KEY_COMMA = 67Comma key
KEY_DOT = 68Dot key
KEY_SLASH = 69Slash key
KEY_RIGHT_SHIFT = 70Right Shift key
KEY_LEFT_CTRL = 71Left Ctrl key
KEY_LEFT_CMD = 72Left Command key
KEY_LEFT_ALT = 73Left Alt key
KEY_SPACE = 74Space key
KEY_RIGHT_ALT = 75Right Alt key
KEY_RIGHT_CMD = 76Right Command key
KEY_MENU = 77Menu key
KEY_RIGHT_CTRL = 78Right Ctrl key
KEY_INSERT = 79Insert key
KEY_DELETE = 80Delete key
KEY_HOME = 81Home key
KEY_END = 82End key
KEY_PGUP = 83Page Up key
KEY_PGDOWN = 84Page down
KEY_UP = 85Up arrow key
KEY_LEFT = 86Left arrow key
KEY_DOWN = 87Down arrow key
KEY_RIGHT = 88Right arrow key
KEY_NUM_LOCK = 89Num Lock key
KEY_NUMPAD_DIVIDE = 90Divide key of the numeric keypad
KEY_NUMPAD_MULTIPLY = 91Multiply key of the numeric keypad
KEY_NUMPAD_MINUS = 92Minus key of the numeric keypad
KEY_NUMPAD_DIGIT_7 = 93The 7 key of the numeric keypad
KEY_NUMPAD_DIGIT_8 = 94The 8 key of the numeric keypad
KEY_NUMPAD_DIGIT_9 = 95The 9 key of the numeric keypad
KEY_NUMPAD_PLUS = 96Plus key of the numeric keypad
KEY_NUMPAD_DIGIT_4 = 97The 4 key of the numeric keypad
KEY_NUMPAD_DIGIT_5 = 98The 5 key of the numeric keypad
KEY_NUMPAD_DIGIT_6 = 99The 6 key of the numeric keypad
KEY_NUMPAD_DIGIT_1 = 100The 1 key of the numeric keypad
KEY_NUMPAD_DIGIT_2 = 101The 2 key of the numeric keypad
KEY_NUMPAD_DIGIT_3 = 102The 3 key of the numeric keypad
KEY_NUMPAD_ENTER = 103Enter key of the numeric keypad
KEY_NUMPAD_DIGIT_0 = 104The 0 key of the numeric keypad
KEY_NUMPAD_DOT = 105Dot key of the numeric keypad
KEY_ANY_SHIFT = 106Any Shift key
KEY_ANY_CTRL = 107Any Ctrl key
KEY_ANY_ALT = 108Any Alt key
KEY_ANY_CMD = 109Any Command key
KEY_ANY_UP = 110Any up arrow key
KEY_ANY_LEFT = 111Any left arrow key
KEY_ANY_DOWN = 112Any down arrow key
KEY_ANY_RIGHT = 113Any right arrow key
KEY_ANY_ENTER = 114Any up arrow key
KEY_ANY_DELETE = 115Any Delete key
KEY_ANY_INSERT = 116Any Insert key
KEY_ANY_HOME = 117Any Home key
KEY_ANY_END = 118Any End key
KEY_ANY_PGUP = 119Any Page Up key
KEY_ANY_PGDOWN = 120Any Page Down key
KEY_ANY_DIGIT_1 = 121The 1 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_2 = 122The 2 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_3 = 123The 3 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_4 = 124The 4 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_5 = 125The 5 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_6 = 126The 6 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_7 = 127The 7 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_8 = 128The 8 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_9 = 129The 9 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_DIGIT_0 = 130The 0 key of either alphanumeric keyboard or numeric keypad
KEY_ANY_MINUS = 131Any minus key
KEY_ANY_EQUALS = 132Any Equals key
KEY_ANY_DOT = 133Any dot key
NUM_KEYS = 134Number of keys.

CALLBACK_INDEX#

NameDescription
CALLBACK_MOUSE_DOWN = 0Callback when the mouse button is pressed.
CALLBACK_MOUSE_UP = 1Callback when the mouse button is released.
CALLBACK_MOUSE_WHEEL = 2Callback when the mouse scroll wheel is moved.
CALLBACK_MOUSE_WHEEL_HORIZONTAL = 3Callback when the mouse wheel is moved horizontally.
CALLBACK_MOUSE_MOTION = 4Callback when the mouse is moved.
CALLBACK_KEY_DOWN = 5Callback when the key is pressed and held.
CALLBACK_KEY_UP = 6Callback when the key is released.
CALLBACK_KEY_REPEAT = 7Callback when the key is pressed repeatedly.
CALLBACK_TEXT_PRESS = 8Callback when the key that has a corresponding printable symbol is pressed.
CALLBACK_TOUCH_DOWN = 9Callback when the touch is pressed.
CALLBACK_TOUCH_UP = 10Callback when the touch is released.
CALLBACK_TOUCH_MOTION = 11Callback when the touch is moved.
CALLBACK_GAMEPAD_CONNECTED = 12Callback when a gamepad is connected. The callback signature is as follows:
Source code (C++)
void gamepad_connected_callback(unsigned int index)
index - gamepad index.
CALLBACK_GAMEPAD_DISCONNECTED = 13Callback when a gamepad is disconnected. The callback signature is as follows:
Source code (C++)
void gamepad_disconnected_callback(unsigned int index)
index - gamepad index.
CALLBACK_GAMEPAD_BUTTON_DOWN = 14Callback when a gamepad button is pressed. The callback signature is as follows:
Source code (C++)
void gamepad_button_down_callback(unsigned int index, Input::GAMEPAD_BUTTON b)
index - gamepad index, b - gamepad button.
CALLBACK_GAMEPAD_BUTTON_UP = 15Callback when a gamepad button is released. The callback signature is as follows:
Source code (C++)
void gamepad_button_up_callback(unsigned int index, Input::GAMEPAD_BUTTON b)
index - gamepad index, b - gamepad button.
CALLBACK_GAMEPAD_AXIS_MOTION = 16Callback when a gamepad axis state value is changed. The callback signature is as follows:
Source code (C++)
void gamepad_axis_callback(unsigned int index, Input::GAMEPAD_AXIS a)
index - gamepad index, a - gamepad axis.
CALLBACK_GAMEPAD_TOUCH_DOWN = 17Callback when the gamepad touch panel is touched. The callback signature is as follows:
Source code (C++)
void gamepad_touch_down_callback(unsigned int index, int touch, int finger)
index - gamepad index, touch - touch index, finger - finger index.
CALLBACK_GAMEPAD_TOUCH_UP = 18Callback when the touch is withdrawn from the gamepad touch panel. The callback signature is as follows:
Source code (C++)
void gamepad_touch_up_callback(unsigned int index, int touch, int finger)
index - gamepad index, touch - touch index, finger - finger index.
CALLBACK_GAMEPAD_TOUCH_MOTION = 19Callback when the finger touching the gamepad touch panel moves across it. The callback signature is as follows:
Source code (C++)
void gamepad_touch_motion_callback(unsigned int index, int touch, int finger)
index - gamepad index, touch - touch index, finger - finger index.
CALLBACK_JOY_CONNECTED = 20Callback when a joystick is connected. The callback signature is as follows:
Source code (C++)
void joystick_connected_callback(unsigned int index)
index - joystick index.
CALLBACK_JOY_DISCONNECTED = 21Callback when a joystick is disconnected. The callback signature is as follows:
Source code (C++)
void joystick_disconnected_callback(unsigned int index)
index - joystick index.
CALLBACK_JOY_BUTTON_DOWN = 22Callback when a joystick button is pressed. The callback signature is as follows:
Source code (C++)
void joystick_button_down_callback(unsigned int index, int b)
index - joystick index, b - button index.
CALLBACK_JOY_BUTTON_UP = 23Callback when a joystick button is released. The callback signature is as follows:
Source code (C++)
void joystick_button_up_callback(unsigned int index, int b)
index - joystick index, b - button index.
CALLBACK_JOY_AXIS_MOTION = 24Callback when a joystick axis state value is changed. The callback signature is as follows:
Source code (C++)
void joystick_axis_callback(unsigned int index, int a)
index - joystick index, a - axis index.
CALLBACK_JOY_POV_MOTION = 25Callback when a joystick POV state value is changed. The callback signature is as follows:
Source code (C++)
void joystick_pov_callback(unsigned int index, int pov)
index - joystick index, pov - pov index.
CALLBACK_IMMEDIATE_INPUT = 26Callback that allows receiving input events immediately from proxy before being processed by the engine. This callback can be called in different threads depending on the proxy implementation.
NUM_CALLBACKS = 27Callback counter.

DEVICE#

NameDescription
DEVICE_UNKNOWN = 0Unknown device.
DEVICE_GAME_CONTROLLER = 1Game controller device.
DEVICE_WHEEL = 2Wheel device.
DEVICE_ARCADE_STICK = 3Arcade stick device.
DEVICE_FLIGHT_STICK = 4Flight stick device.
DEVICE_DANCE_PAD = 5Dance pad device.
DEVICE_GUITAR = 6Guitar.
DEVICE_DRUM_KIT = 7Drum kit.
DEVICE_THROTTLE = 8Throttle device.

GAMEPAD_BUTTON#

Buttons of the gamepad.
NameDescription
GAMEPAD_BUTTON_A = 0Button A of the gamepad.
GAMEPAD_BUTTON_B = 1Button B of the gamepad.
GAMEPAD_BUTTON_X = 2Button X of the gamepad.
GAMEPAD_BUTTON_Y = 3Button Y of the gamepad.
GAMEPAD_BUTTON_BACK = 4Button "Back" of the gamepad.
GAMEPAD_BUTTON_START = 5Button "Start" of the gamepad.
GAMEPAD_BUTTON_DPAD_UP = 6Button "Up" of the gamepad.
GAMEPAD_BUTTON_DPAD_DOWN = 7Button "Down" of the gamepad.
GAMEPAD_BUTTON_DPAD_LEFT = 8Button "Left" of the gamepad.
GAMEPAD_BUTTON_DPAD_RIGHT = 9Button "Right" of the gamepad.
GAMEPAD_BUTTON_THUMB_LEFT = 10Left thumbstick button of the gamepad.
GAMEPAD_BUTTON_THUMB_RIGHT = 11Right thumbstick button of the gamepad.
GAMEPAD_BUTTON_SHOULDER_LEFT = 12Left shoulder (bumper) button of the gamepad.
GAMEPAD_BUTTON_SHOULDER_RIGHT = 13Right shoulder (bumper) button of the gamepad.
GAMEPAD_BUTTON_GUIDE = 14Button "Guide" of the gamepad.
GAMEPAD_BUTTON_MISC1 = 15The miscellaneous button of the gamepad.
GAMEPAD_BUTTON_TOUCHPAD = 16Touchpad of the gamepad.
NUM_GAMEPAD_BUTTONS = 17Number of buttons on a gamepad.

GAMEPAD_AXIS#

NameDescription
GAMEPAD_AXIS_LEFT_X = 0X axis of the left stick of the gamepad.
GAMEPAD_AXIS_LEFT_Y = 1Y axis of the left stick of the gamepad.
GAMEPAD_AXIS_RIGHT_X = 2X axis of the right stick of the gamepad.
GAMEPAD_AXIS_RIGHT_Y = 3Y axis of the right stick of the gamepad.
GAMEPAD_AXIS_LEFT_TRIGGER = 4Left trigger of the gamepad.
GAMEPAD_AXIS_RIGHT_TRIGGER = 5Right trigger of the gamepad.
NUM_GAMEPAD_AXES = 6Number of axes on a gamepad.

JOYSTICK_POV#

POV (Point-of-View) switch or DPad states.
NameDescription
JOYSTICK_POV_NOT_PRESSED = 0POV (Point-of-View) hat switch or D-Pad (directional pad) button is not pressed.
JOYSTICK_POV_UP = 1POV (Point-of-View) hat switch or D-Pad (directional pad) is in up position.
JOYSTICK_POV_UP_RIGHT = 2POV (Point-of-View) hat switch or D-Pad (directional pad) is in right-up position.
JOYSTICK_POV_RIGHT = 3POV (Point-of-View) hat switch or D-Pad (directional pad) is in right position.
JOYSTICK_POV_DOWN_RIGHT = 4POV (Point-of-View) hat switch or D-Pad (directional pad) is in down-right position.
JOYSTICK_POV_DOWN = 5POV (Point-of-View) hat switch or D-Pad (directional pad) is in down position.
JOYSTICK_POV_DOWN_LEFT = 6POV (Point-of-View) hat switch or D-Pad (directional pad) is in down-left position.
JOYSTICK_POV_LEFT = 7POV (Point-of-View) hat switch or D-Pad (directional pad) is in left position.
JOYSTICK_POV_UP_LEFT = 8POV (Point-of-View) hat switch or D-Pad (directional pad) is in left-up position.

Members


Math::ivec2 getMousePosition ( ) const#

Returns a vector containing the global coordinates of the mouse cursor. In case of a mouse button event, the cursor position at the moment of the processed event is returned. In case of no such event, the mouse position at the beginning of the frame is returned. To get the cursor position during another type of event, get this event (for example getKeyEvent()) and get the cursor position stored inside it.

Return value

Global coordinates of the cursor.

Math::ivec2 getMouseDeltaPosition ( ) #

Returns a vector containing screen position change of the mouse pointer along the X and Y axes — the difference between the values in the previous and the current frames.

Return value

Float mouse pointer position delta.

int getMouseWheel ( ) const#

Returns the current mouse scroll value. Negative values correspond to scrolling downwards; positive values correspond to scrolling upwards; the value is zero when the mouse wheel is not scrolled.

Return value

Mouse scroll value in the [-1;1] range.

int getMouseWheelHorizontal ( ) const#

Returns the current horizontal mouse scroll value.

Return value

Horizontal mouse scroll value in the [-1;1] range.

void setMouseGrab ( bool grab ) #

Sets the value indicating if the mouse pointer is bound to the application window.

Arguments

  • bool grab - 1 if the mouse cannot leave the application window; otherwise, 0.

bool isMouseGrab ( ) const#

Returns the value indicating if the mouse pointer is bound to the application window.

Return value

true if the mouse cannot leave the application window; otherwise, false.

int getNumGamePads ( ) const#

Returns the total number of all gamepads.

Return value

Number of all gamepads.

Ptr<InputGamePad> getGamePad ( int num ) const#

Returns a gamepad of the given index.

Arguments

  • int num - Gamepad index.

Return value

InputGamepad object.

int getNumJoysticks ( ) const#

Returns the total number of all joysticks.

Return value

Number of all joysticks.

Ptr<InputJoystick> getJoystick ( int num ) const#

Returns a joystick with the given index.

Arguments

  • int num - Joystick index.

Return value

InputJoystick object.

bool isKeyPressed ( Input::KEY key ) const#

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 ) const#

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

1 during the first frame when the key was pressed, 0 for the following ones until it is released and pressed again.

bool isKeyUp ( Input::KEY key ) const#

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 ) const#

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

Return value

1 if the mouse button is pressed; otherwise, 0.

bool isMouseButtonDown ( Input::MOUSE_BUTTON button ) const#

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

Return value

1 during the first frame when the mouse button was released; otherwise, 0.

bool isMouseButtonUp ( Input::MOUSE_BUTTON button ) const#

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("the left mouse button was released\n");
	}

Arguments

Return value

1 during the first frame when the mouse button was released; otherwise, 0.

void setMouseHandle ( Input::MOUSE_HANDLE handle ) #

Sets the mouse behavior mode.

Arguments

Input::MOUSE_HANDLE getMouseHandle ( ) const#

Returns the mouse behavior mode.

Return value

Mouse behavior mode, one of the MOUSE_HANDLE_* values.

bool isTouchPressed ( int index ) const#

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 ) const#

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 ) const#

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.

Math::ivec2 getTouchPosition ( int index ) const#

Returns a vector containing integer values of touch position.

Arguments

  • int index - Touch input index.

Return value

The touch position.

Math::ivec2 getTouchDelta ( int index ) const#

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.

Ptr<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, Vector<Ptr<InputEventTouch>> & events ) #

Returns the actions cast to the touch event.

Arguments

Return value

Number of touch input events.

Ptr<InputEventKeyboard> getKeyEvent ( Input::KEY key ) #

Returns the currently processed keyboard input event.

Arguments

Return value

Keyboard input event, or nullptr if there are no events for the specified key in the current frame.

int getKeyEvents ( Input::KEY key, Vector<Ptr<InputEventKeyboard>> & events ) #

Returns the buffer with events for the specified key.

Arguments

const char * getKeyName ( Input::KEY key ) const#

Returns the specified key name.

Arguments

Return value

Key name.

Input::KEY getKeyByName ( const char * name ) const#

Returns the key by its name.

Arguments

  • const char * name - Key name.

Return value

One of the preset KEY_ codes.

Ptr<InputEventMouseButton> getMouseButtonEvent ( Input::MOUSE_BUTTON button ) #

Returns the mouse motion input event for the specified button.

Arguments

Return value

Mouse motion input event.

const char * getMouseButtonName ( Input::MOUSE_BUTTON button ) const#

Returns the mouse button name.

Arguments

Return value

Mouse button name.

Input::MOUSE_BUTTON getMouseButtonByName ( const char * name ) const#

Returns the mouse button by its name.

Arguments

  • const char * name - Mouse button name.

Return value

One of the preset MOUSE_BUTTON_ codes.

int getEventsBuffer ( int frame, Vector<Ptr<InputEvent>> & events ) const#

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.
  • Vector<Ptr<InputEvent>> & events - The buffer with input events.

void sendEvent ( const Ptr<InputEvent> & e ) #

Creates a user event and dispatches it to the Engine.

Arguments

void setEventsFilter ( int (*)(const Ptr<InputEvent> &) 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

bool isModifierEnabled ( Input::MODIFIER modifier ) const#

Returns the value indicating if the specified modifier is enabled.

Arguments

Return value

true if the modifier is enabled; otherwise, false.

unsigned int keyToUnicode ( Input::KEY key ) const#

Returns the specified key transformed to unicode.

Arguments

Return value

Unicode symbol.

Input::KEY unicodeToKey ( unsigned int unicode ) const#

Returns the specified key transformed to unicode.

Arguments

  • unsigned int unicode - Unicode symbol.

Return value

One of the preset KEY_ codes.

Math::ivec2 getMouseDeltaRaw ( ) const#

Returns the physical change in the absolute mouse position (not the screen cursor).

Return value

The change in the absolute mouse position, dots per inch.

bool isEmptyClipboard ( ) const#

Returns a value indicating if the clipboard is empty.

Return value

true if the clipboard is empty; otherwise, false.

void setClipboard ( const char * clipboard ) #

Updates the contents of the system clipboard.

Arguments

  • const char * clipboard - Contents to set.

const char * getClipboard ( ) const#

Retrieves the contents of the system clipboard.

Return value

Contents of the system clipboard.

void setMouseCursorHide ( bool hide ) #

Sets a value indicating if the mouse cursor should be hidden. Can be used, for example, to hide mouse cursor for a certain element.
Notice
This method hides the cursor only for one frame. So, you should call it each frame if a longer period is required.

Arguments

  • bool hide - true to hide the mouse cursor for a single frame, false - to show it.

bool isMouseCursorHide ( ) const#

Returns a value indicating if the mouse cursor is hidden in the current frame.

Return value

true if mouse cursor is hidden in the current frame, false - to show it.

void setMouseCursorSystem ( bool system ) #

Sets a value indicating if the OS mouse pointer should be displayed.

Arguments

  • bool system - true to display the OS mouse pointer; otherwise, false.

bool isMouseCursorSystem ( ) const#

Returns a value indicating if the OS mouse pointer is displayed.

Return value

true if the OS mouse pointer is displayed; otherwise, false.

void setMouseCursorNeedUpdate ( bool update ) #

Sets a value indicating that some changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) 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.

Arguments

  • bool update - true to signalize that the mouse cursor has to be updated; otherwise, false.

bool isMouseCursorNeedUpdate ( ) const#

Returns a value indicating that changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) 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.

Return value

true if the mouse cursor has to be updated; otherwise, false.

void setMouseCursorSkinCustom ( const Ptr<Image> & image ) #

Sets a custom image to be used for the mouse cursor.

Arguments

  • const Ptr<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 ( const Ptr<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
	ImagePtr cursor = Image::create("textures/my_cursor.png");
	// set the image as the mouse cursor
	Input::setMouseCursorCustom(cursor);
	// show the OS mouse pointer
	Input::setMouseCursorSystem(1);

Arguments

  • const Ptr<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.

const char * getKeyLocalName ( Input::KEY key ) const#

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, Vector<Ptr<InputEventMouseButton>> & events ) #

Returns the number of input events for the specified mouse button and puts the events to the specified output buffer.

Arguments

Return value

Number of input events for the specified mouse button.

Math::ivec2 getForceMousePosition ( ) #

Returns the absolute mouse position obtained from the OS.

Return value

The absolute mouse position.

bool isKeyText ( Input::KEY key ) const#

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase1< Input::MOUSE_BUTTON > * 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++)
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_MOUSE_DOWN, MakeCallback(button_clicked));

Arguments

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase2< int, int > * 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:
  • Unigine::CallbackBase2< int, int > * func - Callback function pointer. The callback signature should be as follows:
    Source code (C++)
    void callback_function_name(int x, int y);
    (x, y) - mouse coordinates delta.

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase1< Input::KEY > * 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

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase1< unsigned int > * 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

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase1< Ptr <InputEvent> > * 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

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase2< unsigned int, Input::GAMEPAD_BUTTON> * 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

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase2< unsigned int, Input::GAMEPAD_AXIS> * 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:
  • Unigine::CallbackBase2< unsigned int, Input::GAMEPAD_AXIS> * func - Callback function pointer. The callback signature should be as follows:
    Source code (C++)
    void callback_function_name(unsigned int index, Input::GAMEPAD_AXIS axis);
    index - gamepad index. axis - gamepad axis index.

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.

void * addCallback ( CALLBACK_INDEX callback, Unigine::CallbackBase2< unsigned int, int> * 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:
  • Unigine::CallbackBase2< unsigned int, int> * func - Callback function pointer. The callback signature should be as follows:
    Source code (C++)
    void callback_function_name(unsigned int index, int action);
    index - device index. action - action index.

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, void * 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

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

const char * getModifierName ( Input::MODIFIER modifier ) const#

Returns the name of the key modifier by its scancode.

Arguments

Return value

Key name of the modifier.

Input::MODIFIER getModifierByName ( const char * name ) const#

Returns the scancode of the key modifier by its name.

Arguments

  • const char * name - Key name of the modifier.

Return value

Scancode of the modifier.
Last update: 2023-08-14
Build: ()