Windows API Reference

System Services - Input Management

Input Management API

This section details the Windows API functions and structures used for managing user input, including keyboard, mouse, touch, and other input devices.

Core Input Concepts

Windows provides a robust input model that allows applications to receive and process various forms of user interaction. Key concepts include:

  • Input Events: Messages generated by hardware devices when a user interacts with them.
  • Input Queue: A system-managed queue where input events are stored before being dispatched to applications.
  • Window Procedures: The message loops within applications that receive and process input events.
  • Raw Input: A more direct way to access input data, bypassing some of the higher-level message processing.

Keyboard Input

Functions for retrieving keyboard states and processing keyboard messages.

GetAsyncKeyState

Determines whether a key is currently up or down (non-blocking).

SHORT GetAsyncKeyState(
  [in] int vKey
);
Parameter Type Description
vKey int Virtual-key code for the key to be checked.

Return Value: If the function is successful, the return value is zero if the key is currently up, and non-zero if the key is down. If the function is unsuccessful, the return value is zero.

GetKeyState

Retrieves the status of a specified virtual key (blocking if called within a message loop).

SHORT GetKeyState(
  [in] int nVirtKey
);
Parameter Type Description
nVirtKey int Virtual-key code for the key to be checked.

Return Value: A SHORT value representing the state of the virtual key.

Keyboard Message Types

  • WM_KEYDOWN: A key has been pressed.
  • WM_KEYUP: A key has been released.
  • WM_CHAR: A character has been generated.

Mouse Input

Functions and messages for handling mouse movements and button clicks.

GetCursorPos

Retrieves the screen coordinates of the mouse cursor.

BOOL GetCursorPos(
  [out] LPPOINT lpPoint
);
Parameter Type Description
lpPoint LPPOINT A pointer to a POINT structure that receives the screen coordinates of the cursor.

Return Value: TRUE if successful, FALSE otherwise.

GetSystemMetrics

Retrieves various system metric values, including mouse metrics.

int GetSystemMetrics(
  [in] int nIndex
);

Common mouse-related indices include SM_CXDOUBLECLK, SM_CYDOUBLECLK, and SM_MOUSEPRESENT.

Mouse Message Types

  • WM_MOUSEMOVE: The mouse pointer has moved.
  • WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN: A mouse button has been pressed.
  • WM_LBUTTONUP, WM_MBUTTONUP, WM_RBUTTONUP: A mouse button has been released.
  • WM_MOUSEWHEEL: The user has rotated the mouse wheel.

Raw Input API

For more advanced input handling, especially for multiple devices or specific device types.

RegisterRawInputDevices

Registers the devices that the application wants to receive raw input data from.

BOOL RegisterRawInputDevices(
  [in] PRAWINPUTDEVICE pRawInputDevices,
  [in] UINT uiNumDevices,
  [in] UINT cbSize
);

Requires the use of RAWINPUTDEVICE structures to specify device types and usage.

GetRawInputData

Retrieves raw input data from the input buffer.

UINT GetRawInputData(
  [in] HRAWINPUT hRawInput,
  [in] UINT uiCommand,
  [out] LPVOID pData,
  [in, out] PUINT pcbSize,
  [in] UINT cbSizeHeader
);

Used to process WM_INPUT messages.

Note on Message Handling

Most standard input is processed through the Windows message loop mechanism. Applications typically override the WindowProc function to handle messages like WM_KEYDOWN, WM_LBUTTONDOWN, etc. For low-level, device-specific input, consider using the Raw Input API.

Touch Input (Modern Applications)

For applications targeting Windows 7 and later, a more sophisticated touch input model is available.

  • WM_TOUCH message: Sent when touch input occurs.
  • GetMessageExtraInfo with TOUCH_MASK: Used to retrieve touch input information.
  • Windows Touch API: A set of APIs for gesture recognition and multi-touch handling.

Refer to the dedicated Windows Touch API documentation for in-depth details.