The input interface allows you to check and control input events. The Input
class can be seen below:
class Input
{
static uint8_t getKey(uint16_t key) noexcept;
static const InputAction& getAction(const UImGui::FString& name) noexcept;
static std::vector<InputAction>& getActions() noexcept;
static FVector2 getMousePositionChange() noexcept;
static FVector2 getCurrentMousePosition() noexcept;
static FVector2 getLastMousePosition() noexcept;
static FVector2 getScroll() noexcept;
};
The following functions can be used to track mouse movements:
getMousePositionChange
getCurrentMousePosition
getLastMousePosition
getScroll
These functions return 2D vectors, where X is left/right and Y is up/down/forward/backward.
Additionally, the following functions can be used to change the type of motion and cursor state:
setCursorVisibility
- Sets the visibility of the cursorgetCurrentCursorVisibility
- Returns the current cursor’s visibilitysetRawMouseMotion
- Can be used to set the raw motion to raw. If set to true, this will only get enabled on compatible platforms and if the mouse state is equal to UIMGUI_CURSOR_VISIBILITY_STATE_DISABLED
getRawMouseMotion
- Returns a bool to check whether raw mouse motion is currently enabledCursor visibility is set using one of the members of the CursorVisibilityState
enum. It looks like this:
enum CursorVisibilityState
{
UIMGUI_CURSOR_VISIBILITY_STATE_NORMAL,
UIMGUI_CURSOR_VISIBILITY_STATE_HIDDEN,
UIMGUI_CURSOR_VISIBILITY_STATE_DISABLED,
};
States:
UIMGUI_CURSOR_VISIBILITY_STATE_NORMAL
- Cursor is visible and can leave the window area at any point. Set by default and enough for most GUI applicationsUIMGUI_CURSOR_VISIBILITY_STATE_HIDDEN
- Cursor is hidden when over the window, but can leave the window area at any point.UIMGUI_CURSOR_VISIBILITY_STATE_DISABLED
- Cursor is hidden and cannot leave the window area. This is useful for 3D camera controls used in gamesThe following functions can be used to track keyboard + some mouse key events:
getKey
getAction
getActions
The getKey
function takes a key code for which to return an event type. Key codes can be found under the Keys
namespace and represent the keys on a standard full width QWERTY keyboard, custom keyboard layouts do not change the location of the keys. A
will always be QWERTY A.
The function returns an integer, which you can check to find what the event type for the current key is. There are currently 3 events:
KeyReleased
KeyPressed
KeyRepeat
These values too are stored under the Keys
namespace.
The getAction
function returns an InputAction
struct given an action name. The InputAction
struct looks like this:
struct InputAction
{
FString name{};
std::vector<uint16_t> keyCodes;
uint8_t state{};
};
You can use the state
member variable to check against the same key events mentioned above. To get all input actions simply call Input::getActions()
InputAction
s were created so that you can provide a config file to the user to can create custom keybindings. To create keybindings, simply open your project’s keybindings file under Config/Core/Keybindings.yaml
. It should look like this:
bindings:
- key: empty-binding
val: [ 1 ]
all you need to do is create a new list entry, give it a name and a value like this:
- key: another-binding
val: [ 65, 66 ]
This binding will be for the key combination of A
and B
. Key codes can be found under the Framework/Core/Events/Keys.hpp
header that defines the Keys
namespace.
We don’t recommend using this method, however, and we recommend that you implement a custom solution to manage keys graphically. Thankfully, the Utility
class provides 4 functions for converting a key to text. All you need to do it iterate all input actions, then use the Utility::keyToText
functions to convert your key event to a string. There are 4 variants of this function, as can be seen below:
static void keyToText(FString& text, const uint16_t& key, bool bLong) noexcept;
static FString keyToText(const uint16_t& key, bool bLong) noexcept;
static void keyToText(FString& text, const InputAction& action, bool bLong) noexcept
static FString keyToText(const InputAction& action, bool bLong) noexcept
The difference between the 2 is that the first one uses a reference to a string buffer, while the second just returns a new string.
The bLong
boolean controls whether to return long or short names. Generally you would like to use short names for places where you need to save space, like menus, menu bar dropdowns, etc.
A small peculiarity to our architecture is that technically Windows own the input, so input settings are controlled by the Window interface. This means that to save the keybindings, you need to call Window::saveSettings
with an argument of true
or false
if you don’t want to save them.
Using the following functions, you can modify key behaviour:
setStickyKeys
- Sets sticky keysgetStickyKeys
- Returns whether sticky keys are currently enabledsetLockKeyMods
- Sets lock key modifiersgetLockKeyMods
- Returns whether lock key modifiers are enabledThe entire module is flagged as event safe at Any time
, except for the following functions, which are rated as begin
, style
and post-begin
:
setCursorVisibility
getCurrentCursorVisibility
setStickyKeys
getStickyKeys
setRawMouseMotion
getRawMouseMotion
setLockKeyMods
getLockKeyMods