int SDL_CaptureMouse(SDL_bool enabled)
| enabled | 捕捉するか否か |
マウスを捕捉すると, ウィンドウの中だけでなく, どこでもマウスイベントを得られるようになる. 全てのビデオがこの機能に対応しているわけではない. 有効にすると, 現在のウィンドウが全てのマウスイベントを獲得する. しかし相対モードとは違い, カーソルは変わらず, ウィンドウの内部に止められることもない.
この関数は他のウィンドウ(あなたのアプリケーションと他のシステムの両方)のマウス入力を禁止する. よってこの関数の使用は慎重かつ最小限でなければならない. 例えば, ユーザが何かをドラッグしてからボタンを離すまでマウスを追跡したい場合に使えるかもしれない. アプリケーションを実行している間ずっとのように長時間マウスを捕捉することは推奨しない.
マウスを捕捉している間は, カーソルの座標は現在の(フォーカスのある)ウィンドウからの相対座標が報告される. そして, その座標はウィンドウの外(負の値を含む)もありうる. 捕捉はフォーカスのあるウィンドウのみ可能である. 捕捉中にフォーカスを失うと, 自動的に捕捉も解除される.
捕捉している間はフォーカスのあるウィンドウにはSDL_WINDOW_MOUSE_CAPTUREフラグが設定される.
SDL 2.0.22では, SDLはユーザがボタンを押している間「自動的に捕捉」しようとする. これは複数の環境間でマウスの挙動の一貫性を保つため, そしてユーザがウィンドウの外にドラッグした一般的なケースのためである. これは, このような理由のためだけにSDL_CaptureMouse()を呼ぶ必要は(行っても害はないが)なくなったことを意味する. この動作があなたのアプリケーションで問題を引き起こすならば, SDL_HINT_MOUSE_AUTO_CAPTUREヒントを0にして自動捕捉を無効にできる.