Input System

Microsoft::Xna::Framework::Input — Keyboard, Mouse, GamePad, TouchPanel, TextInputEXT, Accelerometer

Overview

All input classes live in the Microsoft::Xna::Framework::Input namespace and follow a polling model that matches XNA 4.0 exactly: you call GetState() once per frame, store the result, and compare it with the previous frame's state to detect transitions. The selected CNA platform (SDL3 by default) receives the underlying OS events and translates them into the state snapshots that CNA exposes.

The typical per-frame pattern for any device is:

// Declare in your Game class
KeyboardState previousKeyboard;

// In Update()
KeyboardState currentKeyboard = Keyboard::GetState();

if (currentKeyboard.IsKeyDown(Keys::Space) && previousKeyboard.IsKeyUp(Keys::Space)) {
    // Space was just pressed this frame
}

previousKeyboard = currentKeyboard;  // save for next frame

The same pattern applies to MouseState and GamePadState. Because the state objects are plain value types, storing and copying them is cheap.

Keyboard

The Keyboard class provides a snapshot of every key on the physical keyboard (Keyboard::GetState(), or Keyboard::GetState(PlayerIndex)). There is no distinction between left and right modifier keys at the KeyboardState level — use Keys::LeftShift / Keys::RightShift etc. when you need that granularity.

The Keys enum (160 enumerators) covers the full keyboard: alphanumeric keys, function keys (F1–F24), numpad keys (NumPad0–NumPad9, Multiply, Add, etc.), navigation keys (Home, End, PageUp, PageDown), and modifier keys (LeftShift, RightShift, LeftControl, RightControl, LeftAlt, RightAlt).

Detecting a key press (held last frame, pressed this frame) versus a key release:

// Press: key was up last frame and is down this frame
bool justPressed  = current.IsKeyDown(k) && previous.IsKeyUp(k);

// Release: key was down last frame and is up this frame
bool justReleased = current.IsKeyUp(k)   && previous.IsKeyDown(k);

Example: WASD movement

#include <Microsoft/Xna/Framework/Input/Keyboard.hpp>

using namespace Microsoft::Xna::Framework::Input;

// In Game::Update(GameTime& gameTime)
KeyboardState kb = Keyboard::GetState();

Vector2 velocity = Vector2::Zero;
float speed = 200.0f * (float)gameTime.getElapsedGameTimeProperty().getTotalSecondsProperty();

if (kb.IsKeyDown(Keys::W) || kb.IsKeyDown(Keys::Up))    velocity.Y -= speed;
if (kb.IsKeyDown(Keys::S) || kb.IsKeyDown(Keys::Down))  velocity.Y += speed;
if (kb.IsKeyDown(Keys::A) || kb.IsKeyDown(Keys::Left))  velocity.X -= speed;
if (kb.IsKeyDown(Keys::D) || kb.IsKeyDown(Keys::Right)) velocity.X += speed;

playerPosition = playerPosition + velocity;

Mouse

The Mouse class returns a MouseState containing cursor coordinates in screen pixels, scroll wheel accumulation, and the state of all five buttons. Coordinates are relative to the top-left corner of the game window. On the SDL3 platform’s x11, windows and cocoa video drivers CNA reads the global cursor position minus the window position, as XNA and FNA do, so the value is current and is not clamped to the window edge; other drivers report the window-relative state. In a browser, Mouse::SetPosition cannot move the real cursor, so CNA emulates the warp: it anchors the requested position and applies later physical movement to it, which keeps re-centring mouse-look working.

Example: mouse click detection

#include <Microsoft/Xna/Framework/Input/Mouse.hpp>

using namespace Microsoft::Xna::Framework::Input;

MouseState previousMouse;

// In Game::Update(GameTime& gameTime)
MouseState mouse = Mouse::GetState();

// Single click: button was released this frame
if (mouse.getLeftButtonProperty() == ButtonState::Released &&
    previousMouse.getLeftButtonProperty() == ButtonState::Pressed)
{
    // Left click at (mouse.getXProperty(), mouse.getYProperty())
    OnLeftClick(mouse.getXProperty(), mouse.getYProperty());
}

// Track scroll
int scrollDelta = mouse.getScrollWheelValueProperty() - previousMouse.getScrollWheelValueProperty();
if (scrollDelta != 0) {
    camera.Zoom(scrollDelta * 0.1f);
}

previousMouse = mouse;

GamePad

The GamePad class supports up to four simultaneously connected controllers via the PlayerIndex enum (One through Four). GamePadState exposes analog sticks, triggers, buttons, and the D-pad. Always check getIsConnectedProperty() before reading state to avoid acting on a zeroed-out snapshot for an absent controller.

Behind the XNA surface, on the default SDL3 platform, sits a substantial SDL3 bridge. It is not a thin passthrough: it handles hot-plug (controllers connected and disconnected mid-session), per-device capability probing (so GamePadCapabilities reports what the specific pad actually has rather than a fixed assumption), and the full haptics surface — standard rumble, trigger rumble on pads that support it, and LED control.

Dead zone handling

Analog sticks rarely rest at exactly (0, 0) due to hardware tolerances. CNA applies a dead zone before returning stick values. The dead zone mode is passed as an optional second argument to GetState():

Example: analog stick movement

#include <Microsoft/Xna/Framework/Input/GamePad.hpp>

using namespace Microsoft::Xna::Framework::Input;

GamePadState previousPad;

// In Game::Update(GameTime& gameTime)
GamePadState pad = GamePad::GetState(PlayerIndex::One);

if (pad.getIsConnectedProperty()) {
    float speed = 200.0f * (float)gameTime.getElapsedGameTimeProperty().getTotalSecondsProperty();

    // Left stick movement
    Vector2 move = pad.getThumbSticksProperty().getLeftProperty();
    move.Y = -move.Y;  // XNA Y axis: up is positive on stick, down on screen
    playerPosition = playerPosition + move * speed;

    // Right trigger as an accelerator
    speed *= 1.0f + pad.getTriggersProperty().getRightProperty();

    // A button just pressed
    if (pad.getButtonsProperty().getAProperty() == ButtonState::Pressed &&
        previousPad.getButtonsProperty().getAProperty() == ButtonState::Released)
    {
        Jump();
    }

    // Vibrate on damage
    if (playerHit) {
        GamePad::SetVibration(PlayerIndex::One, 0.8f, 0.4f);
    }
}

previousPad = pad;

Beyond XNA: GamePad EXT methods

XNA 4.0 was designed around the Xbox 360 controller, so its GamePad API has no vocabulary for anything a modern pad does. CNA adds 21 CNAEXT-tagged static functions to GamePad to cover the gap: the keyboard-emulation switch above, device GUID, light bar colour, trigger vibration, gyroscope and accelerometer readings, battery/power info, touchpad finger positions, and the Steam input handle. The extra buttons modern pads expose — back paddles, Misc1, and the touchpad click — are available too, alongside six Keyboard scancode methods, MouseCursor, and TextInputEXT.

These are outside the XNA surface by construction. Compile with the CNA_STRICT_XNA_API definition on your target and the compiler flags every use as deprecated, which is what you want if the goal is a codebase that could also build against real XNA. (It is a compile definition, not a CMake option; CNA's own automated check of it covers the Devices namespace only.)

TouchPanel

The TouchPanel class exposes multi-touch and gesture recognition. All 10 XNA gesture types are genuinely detected — not stubbed, not partially wired — by a 474-line state machine that tracks contacts over time and computes flick velocity with exponential smoothing. Three points to know: GetState() is event-driven where FNA polls the platform every frame (a deliberate deviation from FNA; see Touch and gestures), while MaximumTouchCount reports 4 and GetState() caps at 8 touches, both matching FNA.

All 10 GestureType values are detected: Tap, DoubleTap, Hold, HorizontalDrag, VerticalDrag, FreeDrag, Flick, Pinch, PinchComplete, DragComplete.

Example: gesture reading

#include <Microsoft/Xna/Framework/Input/Touch/TouchPanel.hpp>

using namespace Microsoft::Xna::Framework::Input::Touch;

// Configure which gestures you want before your game loop
TouchPanel::setEnabledGesturesProperty(
    GestureType::Tap | GestureType::FreeDrag | GestureType::Flick);

// In Game::Update(GameTime& gameTime)
while (TouchPanel::getIsGestureAvailableProperty()) {
    GestureSample gesture = TouchPanel::ReadGesture();

    switch (gesture.getGestureTypeProperty()) {
        case GestureType::Tap:
            OnTap(gesture.getPositionProperty());
            break;
        case GestureType::Flick:
            // getDeltaProperty() holds the flick velocity
            playerVelocity = playerVelocity + gesture.getDeltaProperty() * 0.01f;
            break;
        case GestureType::FreeDrag:
            cameraOffset = cameraOffset - gesture.getDeltaProperty();
            break;
        default:
            break;
    }
}

New in this snapshot: mouse emulation and touch suppression

Two CNAEXT switches were added to TouchPanel. setMouseTouchEmulationEnabledEXT(true) makes the left mouse button synthesise a touch, so a touch UI can be tried on a desktop; it is off by default, matching XNA and FNA. getInputSuppressedEXT()/setInputSuppressedEXT() withhold touch input while a Guide message box or keyboard prompt is on screen; CNA raises it for you while such an overlay is pending. Mouse events that SDL synthesised from a touch do not feed the emulation back, so a real pinch stays two real fingers, and an emulated touch is clamped to the display. CNA also gained a MIME-typed CNA::Input::Clipboard API (including the X11 primary selection).

TextInputEXT

TextInputEXT is a CNA extension (not in the original XNA 4.0 API) that captures text entry events from the OS input method, including IME composition on platforms that support it. It is the correct way to implement chat boxes, in-game consoles, or any other free-text input — keyboard polling alone will not handle key repeat, modifier combinations, or international characters correctly. Draft IME text arrives separately through TextEditing (UTF-8), and TextEditingCandidatesEXT reports candidate lists.

#include <Microsoft/Xna/Framework/Input/TextInputEXT.hpp>

using namespace Microsoft::Xna::Framework::Input;

// In Game::Initialize() or wherever you set up input
// inputBuffer is a std::u16string; TextInput passes one UTF-16 code unit per call
TextInputEXT::TextInput += [this](char16_t c) {
    if (c == u'\b') {          // backspace
        if (!inputBuffer.empty()) inputBuffer.pop_back();
    } else if (c >= u' ') {   // printable
        inputBuffer += c;
    }
};

// To stop receiving events (e.g. when the text field is dismissed)
// TextInputEXT::StopTextInput();

Accelerometer (Sensors)

The Accelerometer class provides access to the device accelerometer. It is backed by the selected platform's real sensor service (the SDL3 sensor API on the default platform) on Android, iOS and desktop wherever a sensor exists, with correct m/s²-to-g conversion and substantial concurrency hardening around the sensor callbacks. Its sibling Gyroscope works the same way. See Sensors for the full Microsoft::Devices::Sensors surface, including which sensors are Android-only. Unlike the input classes above, the sensors are instances: construct one, Start() it and read it.

Keyboard sensor and orientation emulation (CNAEXT, off by default). Accelerometer::setKeyboardEmulationEnabledEXT(true) replaces the primary accelerometer with a software one driven by the arrow keys (tilt of one g, no keys reads (0, 0, -1)), and getIsSupportedProperty() becomes true on desktop and in the browser without hardware; stop every running accelerometer before switching. Separately, getWindowProperty().setKeyboardOrientationEmulationEnabledEXT(true) lets Up, Left and Right request Portrait, LandscapeLeft and LandscapeRight within SupportedOrientations, through the normal device-reset path. Both are for trying phone-style games on a desktop; see Sensors.

Implementation status