feat(mouse): Implement Cursor Capture functionality (#1369)

The Mouse Cursor Capture has 4 modes

"None": Game window does not capture the cursor
"InGame": Game window captures the cursor when playing and observing
"Always": Game window captures the cursor always in menus and game
"Auto": Applies mode "InGame" when Windowed, "Always" when Fullscreen

Adds new option "CursorCaptureMode" to Options.ini which uses the above option strings.

Author: xezon

Generals/Code/GameEngine/Include/Common/UserPreferences.h

@@ -38,6 +38,8 @@
 //-----------------------------------------------------------------------------
 #include "Common/STLTypedefs.h"
 
+enum CursorCaptureMode CPP_11(: Int);
+
 //-----------------------------------------------------------------------------
 // PUBLIC TYPES ///////////////////////////////////////////////////////////////
 //-----------------------------------------------------------------------------
@@ -90,6 +92,7 @@ class OptionPreferences : public UserPreferences
 	void setOnlineIPAddress(UnsignedInt IP);	// convenience function
 	Bool getAlternateMouseModeEnabled(void);	// convenience function
 	Real getScrollFactor(void);								// convenience function
+	CursorCaptureMode getCursorCaptureMode() const;
 	Bool getSendDelay(void);									// convenience function
 	Int getFirewallBehavior(void);						// convenience function
 	Short getFirewallPortAllocationDelta(void);	// convenience function

Generals/Code/GameEngine/Include/GameClient/Mouse.h

@@ -59,6 +59,8 @@
 
 // FORWARD REFERENCES /////////////////////////////////////////////////////////
 
+enum GameMode CPP_11(: Int);
+
 // TYPE DEFINES ///////////////////////////////////////////////////////////////
 
 enum MouseButtonState CPP_11(: Int)
@@ -139,13 +141,43 @@ class CursorInfo
 	Int						numDirections;	//number of directions for cursors like scrolling/panning.
 };
 
+enum CursorCaptureMode CPP_11(: Int)
+{
+	CursorCaptureMode_None, // Does not capture the cursor
+	CursorCaptureMode_InGame, // Captures the cursor when playing and observing
+	CursorCaptureMode_Always, // Captures the cursor always in menus and game
+	CursorCaptureMode_Auto, // Applies mode "InGame" when Windowed, "Always" when Fullscreen
+
+	CursorCaptureMode_Count,
+	CursorCaptureMode_Default = CursorCaptureMode_Auto,
+};
+
+extern const char* const TheCursorCaptureModeNames[];
+
 // Mouse ----------------------------------------------------------------------
-/** Class interface for working with a mouse pointing device */
+// Class interface for working with a mouse pointing device
+//
+// TheSuperHackers @feature xezon 26/07/2025 Implements mouse cursor capture
+// functionality. The Mouse class handles most of the logic for it internally.
 //-----------------------------------------------------------------------------
 class Mouse : public SubsystemInterface
 {
 
-public:  // enumerations and types
+	// enumerations and types
+
+	typedef UnsignedInt CursorCaptureBlockReasonInt;
+
+	enum CursorCaptureBlockReason
+	{
+		CursorCaptureBlockReason_NoInit,
+		CursorCaptureBlockReason_NoGame,
+		CursorCaptureBlockReason_Paused,
+		CursorCaptureBlockReason_Unfocused,
+
+		CursorCaptureBlockReason_Count
+	};
+
+public:
 
 	// ----------------------------------------------------------------------------------------------
 	/** If you update this enum make sure you update CursorININames[] */
@@ -228,10 +260,12 @@ class Mouse : public SubsystemInterface
 		RM_W3D,				//W3D model tied to frame rate.
 		RM_POLYGON,		//alpha blended polygon tied to frame rate.
 		RM_DX8,			//hardware cursor independent of frame rate.
+
 		RM_MAX	// keep this last.
 	};
 
-	static const char *RedrawModeName[RM_MAX];
+	static const char *const CursorCaptureBlockReasonNames[];
+	static const char *const RedrawModeName[];
 
 	CursorInfo m_cursorInfo[NUM_MOUSE_CURSORS];
 
@@ -255,8 +289,8 @@ class Mouse : public SubsystemInterface
 	virtual void setPosition( Int x, Int y );						///< set the mouse position
 	virtual void setCursor( MouseCursor cursor ) = 0;		///< set mouse cursor
 
-	virtual void capture( void ) = 0;					///< capture the mouse
-	virtual void releaseCapture( void ) = 0;  ///< release mouse capture
+	void setCursorCaptureMode(CursorCaptureMode mode); ///< set the rules for the mouse capture
+	void refreshCursorCapture(); ///< refresh the mouse capture
 
 	// access methods for the mouse data
 	const MouseIO *getMouseStatus( void ) { return &m_currMouse; }							///< get current mouse status
@@ -278,7 +312,12 @@ class Mouse : public SubsystemInterface
 	Int getCursorIndex( const AsciiString& name );
 	void resetTooltipDelay( void );
 
+	virtual void loseFocus();
+	virtual void regainFocus();
+
 	void mouseNotifyResolutionChange(void);
+	void onGameModeChanged(GameMode prev, GameMode next);
+	void onGamePaused(Bool paused);
 
 	Bool isClick(const ICoord2D *anchor, const ICoord2D *dest, UnsignedInt previousMouseClick, UnsignedInt currentMouseClick);
 
@@ -308,6 +347,14 @@ class Mouse : public SubsystemInterface
 
 protected:
 
+	void initCapture();
+	Bool canCapture() const;
+	void unblockCapture(CursorCaptureBlockReason reason);
+	void blockCapture(CursorCaptureBlockReason reason);
+
+	virtual void capture( void ) = 0; ///< capture the mouse
+	virtual void releaseCapture( void ) = 0; ///< release mouse capture
+
 	/// you must implement getting a buffered mouse event from you device here
 	virtual UnsignedByte getMouseEvent( MouseIO *result, Bool flush ) = 0;
 
@@ -324,7 +371,7 @@ class Mouse : public SubsystemInterface
 
 	UnsignedByte m_numButtons;  ///< number of buttons on this mouse
 	UnsignedByte m_numAxes;			///< number of axes this mouse has
-	Bool m_forceFeedback;				///< set to TRUE if mouse supprots force feedback
+	Bool m_forceFeedback;				///< set to TRUE if mouse supports force feedback
 
 	UnicodeString m_tooltipString;	///< tooltip text
 	DisplayString *m_tooltipDisplayString; ///< tooltipDisplayString
@@ -368,6 +415,9 @@ class Mouse : public SubsystemInterface
 
 	Int m_eventsThisFrame;
 
+	CursorCaptureMode m_cursorCaptureMode;
+	CursorCaptureBlockReasonInt m_captureBlockReasonBits;
+
 };  // end class Mouse
 
 // TheSuperHackers @feature helmutbuhler 17/05/2025

Generals/Code/GameEngine/Include/GameLogic/GameLogic.h

@@ -173,6 +173,9 @@ class GameLogic : public SubsystemInterface, public Snapshot
 	Bool isInInternetGame( void );
 	Bool isInShellGame( void );
 	Bool isInMultiplayerGame( void );
+
+	static Bool isInInteractiveGame(GameMode mode) { return mode != GAME_NONE && mode != GAME_SHELL; }
+
 	Bool isLoadingGame();
 	void enableScoring(Bool score) { m_isScoringEnabled = score; }
 	Bool isScoringEnabled() const { return m_isScoringEnabled; }

Generals/Code/GameEngine/Source/Common/GameEngine.cpp

@@ -366,11 +366,6 @@ void GameEngine::init()
 		initSubsystem(TheWritableGlobalData, "TheWritableGlobalData", TheWritableGlobalData, &xferCRC, "Data\\INI\\Default\\GameData.ini", "Data\\INI\\GameData.ini");
 		TheWritableGlobalData->parseCustomDefinition();
 
-		// TheSuperHackers @bugfix helmutbuhler 14/04/2025
-		// Pump messages during startup to ensure that the application window is correctly
-		// positioned on slower computers and in debug builds by a later call to SetWindowPos.
-		// It is unclear what the issue with SetWindowPos is when it fails to reposition the window.
-		serviceWindowsOS();
 
 
 	#if defined(RTS_DEBUG)

Generals/Code/GameEngine/Source/GameClient/GUI/GUICallbacks/Menus/OptionsMenu.cpp

@@ -346,6 +346,24 @@ Real OptionPreferences::getScrollFactor(void)
 	return factor/100.0f;
 }
 
+CursorCaptureMode OptionPreferences::getCursorCaptureMode() const
+{
+	CursorCaptureMode mode = CursorCaptureMode_Default;
+	OptionPreferences::const_iterator it = find("CursorCaptureMode");
+	if (it != end())
+	{
+		for (Int i = 0; i < CursorCaptureMode_Count; ++i)
+		{
+			if (stricmp(it->second.str(), TheCursorCaptureModeNames[i]) == 0)
+			{
+				mode = static_cast<CursorCaptureMode>(i);
+				break;
+			}
+		}
+	}
+	return mode;
+}
+
 Bool OptionPreferences::usesSystemMapDir(void)
 {
 	OptionPreferences::const_iterator it = find("UseSystemMapDir");
@@ -1140,6 +1158,13 @@ static void saveOptions( void )
 	TheWritableGlobalData->m_useAlternateMouse = GadgetCheckBoxIsChecked(checkAlternateMouse);
 	(*pref)["UseAlternateMouse"] = TheWritableGlobalData->m_useAlternateMouse ? AsciiString("yes") : AsciiString("no");
 
+	// TheSuperHackers @todo Add combo box ?
+	{
+		CursorCaptureMode mode = pref->getCursorCaptureMode();
+		(*pref)["CursorCaptureMode"] = TheCursorCaptureModeNames[mode];
+		TheMouse->setCursorCaptureMode(mode);
+	}
+
 	//-------------------------------------------------------------------------------------------------
 	// scroll speed val
 	val = GadgetSliderGetPosition(sliderScrollSpeed);

Generals/Code/GameEngine/Source/GameClient/GameClient.cpp

@@ -183,6 +183,7 @@ GameClient::~GameClient()
 	delete TheFontLibrary;
 	TheFontLibrary = NULL;
 
+	TheMouse->reset();
 	delete TheMouse;
 	TheMouse = NULL;
 

Generals/Code/GameEngine/Source/GameClient/InGameUI.cpp

@@ -2810,7 +2810,6 @@ void InGameUI::setScrolling( Bool isScrolling )
 
 	if (isScrolling)
 	{
-		TheMouse->capture();
 		setMouseCursor( Mouse::SCROLL );
 
 		// break any camera locks
@@ -2820,7 +2819,6 @@ void InGameUI::setScrolling( Bool isScrolling )
 	else
 	{
 		setMouseCursor( Mouse::ARROW );
-		TheMouse->releaseCapture();
 	}
 
 	m_isScrolling = isScrolling;
@@ -3019,9 +3017,6 @@ void InGameUI::placeBuildAvailable( const ThingTemplate *build, Drawable *buildD
 
 			Drawable *draw;
 
-			// capture the mouse for our window, windows is lame and changes it if we don't
-			TheMouse->capture();
-
 			// hack for changing cursor
 			setMouseCursor( Mouse::CROSS );
 
@@ -3070,7 +3065,6 @@ void InGameUI::placeBuildAvailable( const ThingTemplate *build, Drawable *buildD
 				m_mouseModeCursor = Mouse::ARROW;
 			}
 
-			TheMouse->releaseCapture();
 			setMouseCursor( Mouse::ARROW );
 			setPlacementStart( NULL );