This project is now hosted on GitHub
. This site is being maintained for now, but please move to using GitHub
This is a helper for simplified mouse tracking modeled after the XNA C# Mouse class.
Mouse is a singleton.
std::unique_ptr<Mouse> mouse( new Mouse );
For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr.
The application needs to call SetWindow
and make calls during the main WndProc message processing to
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
Mouse::ProcessMessage(message, wParam, lParam);
return DefWindowProc(hWnd, message, wParam, lParam);
Universal Windows apps, Windows Store apps
You need to call SetWindow
in the appropriate places.
void App::SetWindow(CoreWindow^ window)
void App::OnDpiChanged(DisplayInformation^ sender, Object^ args)
queries the current state of the mouse.
auto state = mouse->GetState();
if ( state.leftButton )
// Left button is down
XMFLOAT2 mousePosInPixels( float(m.x), float(m.y) );
// This is the absolute position of the mouse relative
// to the upper-left corner of the window
Button state tracker
A common pattern is to trigger an action when a mouse button is pressed or released, but you don't want to trigger the action every single frame if the button is held down for more than a single frame. This helper class simplifies this.
When resuming from a pause or suspend, be sure to call Reset on the tracker object to clear the state history.
std::unique_ptr<Mouse::ButtonStateTracker> tracker( new Mouse::ButtonStateTracker );
auto state = mouse->GetState();
tracker->Update( state );
if ( tracker->rightButton == Mouse::ButtonStateTracker::PRESSED )
// Take an action when Right mouse button is first pressed, but don't do
// it again until the button is released and then pressed again
Absolute vs. Relative Mouse position
By default, the mouse state is returned as a absolute pixel location in the x and y values of State. For 'mouse-look' behavior in games, however, relative mouse movement is desired. While there are some older tricks for emulating this with absolute
pixel locations and computing deltas, there are better options which are implemented by Mouse.
Control of the mode is set by SetMode
passing either MODE_ABSOLUTE (the default) or MODE_RELATIVE. The current mode is returned in State in the positionMode value to inform your input code locally the mode of the x, y values.
Here, we are using relative movement whenever the left mouse button is held down:
auto state = g_mouse->GetState();
if (state.positionMode == Mouse::MODE_RELATIVE)
// state.x and state.y are relative values; system cursor is not visible
// state.x and state.y are absolute pixel values; system cursor is visible
if (tracker.leftButton == Mouse::ButtonStateTracker::ButtonState::PRESSED)
else if (tracker.leftButton == Mouse::ButtonStateTracker::ButtonState::RELEASED)
: When using MODE_RELATIVE, the system cursor is hidden so a user can't navigate away to another monitor or app or even exit. If your game makes use of 'mouse-look' controls, you should ensure that a simple key (like the ESC key) returns
to the game's menu/pause screen and that needs to restore MODE_ABSOLUTE behavior.
The mouse scroll wheel value is accumulated. To reset the value to 0, use ResetScrollWheelValue
The Mouse class should be thread-safe with the exception of the ProcessMessage
which should only be called in your windows message loop.
The Xbox One platform doesn't support pointer or mouse input devices.
For Windows Store, universal Windows apps, and Windows phone touch/pointer devices are captured as mouse movement. Touch/pointer devices do not, however, result in changes to button state. Relative mouse movement is captured per this MSDN article:
For Windows desktop apps, relative mouse movement is captured using "raw input" per the MSDN article
. Note that a consequence of this implementation is that relative mouse movement is not available when using the application through Remote Desktop.