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;
};

Mouse

The following functions can be used to track mouse movements:

  1. getMousePositionChange
  2. getCurrentMousePosition
  3. getLastMousePosition
  4. getScroll

These functions return 2D vectors, where X is left/right and Y is up/down/forward/backward.

Cursor and motion

Additionally, the following functions can be used to change the type of motion and cursor state:

  1. setCursorVisibility - Sets the visibility of the cursor

Cursor 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,
};

States:

  1. 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 applications
  2. UIMGUI_CURSOR_VISIBILITY_STATE_HIDDEN - Cursor is hidden when over the window, but can leave the window area at any point.

Keyboard

The following functions can be used to track keyboard + some mouse key events:

  1. getKey
  2. getAction
  3. getActions

The getKey function takes a key code for which to return an event type. Key codes are represented as Keys_ enum members and feature 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:

  1. KeyReleased
  2. KeyPressed
  3. KeyRepeat

Tip

Because on macOS there are both the Control and Command keys we have the Keys_LeftControlCmd and Keys_LeftControl/Keys_RightControlCmd and Keys_RightControl keys. In most cases you should use ControlCmd and you should only really use Control for macOS-specific keybindings that actually use the Control key. On platforms that are not macOS these keys are set to the same value.

Tip

Related to macOS' keyboard, the Keys_LeftSuper and Keys_RightSuper keys have the same value as Keys_LeftControlCmd/Keys_RightControlCmd on macOS.

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().

InputActions 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/C/Internal/Keys.h header that defines the CKeys enum.

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:

  1. static void keyToText(FString& text, const uint16_t& key, bool bLong) noexcept;
  2. static FString keyToText(const uint16_t& key, bool bLong) noexcept;
  3. static void keyToText(FString& text, const InputAction& action, bool bLong) noexcept
  4. 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.

Saving keybindings

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.

Event safety

The entire module is flagged as event safe at Any time, except for the following functions, which are rated as begin, style and post-begin:

  1. setCursorVisibility
  2. setRawMouseMotion
  3. getRawMouseMotion

C API

The C API implements its own InputAction struct, called UImGui_CInputAction. It looks like this:

struct UImGui_CInputAction_I
{
    const char* name;

    uint16_t* keyCodes;
    size_t keyCodesSize;

    uint8_t state;
};

The C API also defines the UImGui_CursorVisibilityState enum, which, in the C++ API, is typedef-ed to CursorVisiblityState:

enum UImGui_CursorVisibilityState
{
    UIMGUI_CURSOR_VISIBILITY_STATE_NORMAL = 0x00034001,
    UIMGUI_CURSOR_VISIBILITY_STATE_HIDDEN = 0x00034002,
};

The functions, part of the C API, are the same, except that they are prefixed with UImGui_Input_ and that the getActions() function is not available. They follow the basic C API development conventions, as defined here.