.\" This manpage content is licensed under Creative Commons
.\"  Attribution 4.0 International (CC BY 4.0)
.\"   https://creativecommons.org/licenses/by/4.0/
.\" This manpage was generated from SDL's wiki page for SDL_CaptureMouse:
.\"   https://wiki.libsdl.org/SDL_CaptureMouse
.\" Generated with SDL/build-scripts/wikiheaders.pl
.\"  revision SDL-3.1.0
.\" Please report issues in this manpage's content at:
.\"   https://github.com/libsdl-org/sdlwiki/issues/new
.\" Please report issues in the generation of this manpage from the wiki at:
.\"   https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20SDL_CaptureMouse
.\" SDL can be found at https://libsdl.org/
.de URL
\$2 \(laURL: \$1 \(ra\$3
..
.if \n[.g] .mso www.tmac
.TH SDL_CaptureMouse 3 "SDL 3.1.0" "SDL" "SDL3 FUNCTIONS"
.SH NAME
SDL_CaptureMouse \- Capture the mouse and to track input outside an SDL window\[char46]
.SH SYNOPSIS
.nf
.B #include \(dqSDL3/SDL.h\(dq
.PP
.BI "int SDL_CaptureMouse(SDL_bool enabled);
.fi
.SH DESCRIPTION
Capturing enables your app to obtain mouse events globally, instead of just
within your window\[char46] Not all video targets support this function\[char46] When
capturing is enabled, the current window will get all mouse events, but
unlike relative mode, no change is made to the cursor and it is not
restrained to your window\[char46]

This function may also deny mouse input to other windows--both those in
your application and others on the system--so you should use this function
sparingly, and in small bursts\[char46] For example, you might want to track the
mouse while the user is dragging something, until the user releases a mouse
button\[char46] It is not recommended that you capture the mouse for long periods
of time, such as the entire time your app is running\[char46] For that, you should
probably use 
.BR SDL_SetRelativeMouseMode
() or

.BR SDL_SetWindowGrab
(), depending on your goals\[char46]

While captured, mouse events still report coordinates relative to the
current (foreground) window, but those coordinates may be outside the
bounds of the window (including negative values)\[char46] Capturing is only allowed
for the foreground window\[char46] If the window loses focus while capturing, the
capture will be disabled automatically\[char46]

While capturing is enabled, the current window will have the

.BR
.BR SDL_WINDOW_MOUSE_CAPTURE
flag set\[char46]

Please note that as of SDL 2\[char46]0\[char46]22, SDL will attempt to "auto capture" the
mouse while the user is pressing a button; this is to try and make mouse
behavior more consistent between platforms, and deal with the common case
of a user dragging the mouse outside of the window\[char46] This means that if you
are calling 
.BR SDL_CaptureMouse
() only to deal with this
situation, you no longer have to (although it is safe to do so)\[char46] If this
causes problems for your app, you can disable auto capture by setting the

.BR
.BR SDL_HINT_MOUSE_AUTO_CAPTURE
hint to zero\[char46]

.SH FUNCTION PARAMETERS
.TP
.I enabled

.BR SDL_TRUE
 to enable capturing, 
.BR SDL_FALSE
 to disable\[char46]
.SH RETURN VALUE
Returns 0 on success or a negative error code on failure; call

.BR SDL_GetError
() for more information\[char46]

.SH AVAILABILITY
This function is available since SDL 3\[char46]0\[char46]0\[char46]

.SH SEE ALSO
.BR SDL_GetGlobalMouseState (3)