inpUnclipMouse - BambooBasic API Reference

Parameters & Returns

Parameters

This function takes no parameters.

Returns

Void

Quick Summary

Removes mouse cursor confinement (allows cursor to move freely across desktop). Takes no parameters. Returns nothing.

Technical Exegesis...

Removes mouse cursor confinement (allows cursor to move freely across desktop). Takes no parameters. Returns nothing. Calls Win32 ClipCursor(NULL) to release cursor clip restriction.

This function unclips mouse. Mouse unclipping: removes cursor movement restriction, cursor can move freely across entire desktop, allows user to interact with other windows/applications, reverses effect of inpClipMouseToWindow.

Removes mouse cursor confinement (allows cursor to move freely across desktop). Takes no parameters. Returns nothing. Calls Win32 ClipCursor(NULL) to release cursor clip restriction.

This function unclips mouse. Mouse unclipping: removes cursor movement restriction, cursor can move freely across entire desktop, allows user to interact with other windows/applications, reverses effect of inpClipMouseToWindow. ClipCursor(NULL): Win32 API with NULL parameter releases clip region, removes any active cursor confinement, cursor returns to normal unrestricted behavior, global system-wide change (affects entire OS cursor). Use cases: (1) Show pause/menu (user needs cursor to click UI), (2) Window deactivation (release cursor when Alt-Tabbing away), (3) Game exit (restore normal cursor behavior), (4) Debug mode (allow developer to access other windows), (5) Cutscenes (player not controlling camera, free cursor). Common patterns: pause menu = unclip + show cursor, game exit = unclip before shutdown, window focus loss = auto-unclip, debug toggle = F12 to toggle clip/unclip, menu system = unclip on menu open, re-clip on menu close. Typical usage: call when showing menus or pausing game, call on window deactivation (focus lost), pair with inpClipMouseToWindow for clip/unclip cycles, combine with inpSetMouseVisible(True) to show cursor, call on game shutdown to restore normal behavior. Pause menu pattern: user presses ESC to pause, unclip mouse so they can click menu buttons, show cursor for visibility, when unpausing, re-clip mouse and hide cursor, maintains FPS control during gameplay, allows menu interaction while paused. Window focus: automatically unclip when window loses focus, user expects normal cursor behavior outside game, re-clip when window regains focus (if appropriate), handle WM_ACTIVATE messages for automatic clip/unclip. Debug workflow: toggle unclip with debug key (F12), allows developer to access debugger/editor, click outside game window without closing, re-clip to resume testing, improves development iteration speed. Cursor visibility: unclipping doesn't show cursor automatically, cursor may still be hidden (inpSetMouseVisible(False)), typically call both inpUnclipMouse + inpSetMouseVisible(True) for menus, unclip without show for hidden cursor that can still escape. State management: track clip state if needed (mouseClipped% boolean), prevents redundant clip/unclip calls, helps debug cursor behavior issues, useful for focus management logic. Game shutdown: always unclip before game exits, prevents cursor stuck in clip region after crash, good practice to restore system state, users expect normal cursor after closing game. Alt-Tab handling: Windows may auto-release clip on Alt-Tab, explicitly call inpUnclipMouse on deactivation for clarity, re-clip on activation if game running and not paused, ensures cursor behavior matches window state. Menu systems: unclip when entering any menu (main menu, pause menu, settings), user needs to click buttons that may be outside clipped region, re-clip when returning to gameplay, maintains smooth transitions between game and UI. Cutscenes: optionally unclip during cutscenes if player not controlling camera, allows cursor to move freely during non-interactive moments, re-clip when gameplay resumes, depends on game design (some keep cursor hidden and clipped even in cutscenes). Performance: negligible cost (single Win32 API call), no per-frame overhead, only call when state changes (pause, unpause, focus, unfocus), minimal CPU usage. User experience: prevents frustrating trapped cursor after game, allows normal desktop interaction when paused, essential for windowed mode usability, improves overall polish and user satisfaction. Clipping lifecycle: (1) game starts -> clip mouse, (2) user plays (cursor confined), (3) user pauses -> unclip mouse, (4) user interacts with menu (free cursor), (5) user unpauses -> re-clip, (6) user quits -> unclip permanently. Error handling: ClipCursor(NULL) always succeeds (no error checking needed), safe to call multiple times (idempotent), no side effects if already unclipped, defensive programming = call on exit even if not clipped. Common mistake: forgetting to unclip on menu, user cannot click menu buttons outside previous game view, always pair gameplay clipping with menu unclipping, test menu interactions in windowed mode to catch this. Related functions: inpClipMouseToWindow confines cursor (opposite of this function), inpSetMouseVisible shows/hides cursor (commonly paired with clip/unclip), inpIsWindowActive detects focus (determines when to unclip), inpGetMouseX/Y read cursor position (unrestricted after unclip). Example workflow: (1) user playing FPS (clipped + hidden), (2) presses ESC, (3) game unclips + shows cursor, (4) user clicks "Resume" button, (5) game clips + hides cursor, (6) gameplay continues. Related: inpClipMouseToWindow confines cursor to window (clip counterpart), inpSetMouseVisible shows cursor (commonly called together), inpIsKeyHit detects pause key (triggers unclip), inpIsWindowActive detects focus loss (triggers auto-unclip).

Example

Example.bam

; Pause menu toggle - clip/unclip with menu state
If inpIsKeyHit(VKEY_ESCAPE) Then
    paused% = Not paused%

    If paused% Then
        ; Entering pause menu
        inpUnclipMouse()          ; Free cursor for menu
        inpSetMouseVisible(True)  ; Show cursor
    Else
        ; Resuming gameplay
        inpClipMouseToWindow()    ; Re-confine cursor
        inpSetMouseVisible(False) ; Hide cursor
    EndIf
EndIf

; Game shutdown - always unclip before exit
Function Shutdown()
    inpUnclipMouse()  ; Restore normal cursor behavior
    inpSetMouseVisible(True)  ; Ensure cursor visible
    b2dEnd()
    End
EndFunction

; Window focus management
Function OnWindowDeactivate()
    ; User Alt-Tabbed or clicked outside window
    inpUnclipMouse()  ; Free cursor immediately
    gamePaused% = True
EndFunction

Function OnWindowActivate()
    ; User clicked back into window
    If Not menuActive% Then
        inpClipMouseToWindow()  ; Re-confine if in gameplay
        gamePaused% = False
    EndIf
EndFunction

; Debug toggle for development
If inpIsKeyHit(VKEY_F12) Then
    debugMode% = Not debugMode%

    If debugMode% Then
        inpUnclipMouse()          ; Free cursor for debugger access
        inpSetMouseVisible(True)  ; Show cursor
        Print "Debug mode: cursor free"
    Else
        inpClipMouseToWindow()    ; Re-confine for gameplay testing
        inpSetMouseVisible(False)  ; Hide cursor
        Print "Debug mode: cursor clipped"
    EndIf
EndIf

; Menu system with proper cursor management
Function ShowMainMenu()
    inpUnclipMouse()          ; Free cursor
    inpSetMouseVisible(True)  ; Show cursor
    menuActive% = True
EndFunction

Function HideMainMenu()
    inpClipMouseToWindow()    ; Confine cursor
    inpSetMouseVisible(False) ; Hide cursor
    menuActive% = False
EndFunction

; Game state management with cleanup
Function MainLoop()
    While running%
        sysUpdateEvents()

        If inpIsKeyHit(VKEY_ESCAPE) Then
            TogglePauseMenu()
        EndIf

        If Not paused% Then
            UpdateGameplay()
        Else
            UpdateMenu()
        EndIf

        Render()
    Wend

    ; Cleanup - always unclip on exit
    inpUnclipMouse()
    inpSetMouseVisible(True)
EndFunction

; Cutscene handling (optional unclip during non-interactive scenes)
Function StartCutscene()
    cutscenePlaying% = True
    inpUnclipMouse()          ; Allow free cursor (or keep clipped, depends on design)
    inpSetMouseVisible(False) ; Cursor still hidden but can move freely
EndFunction

Function EndCutscene()
    cutscenePlaying% = False
    inpClipMouseToWindow()    ; Re-confine for gameplay
    inpSetMouseVisible(False) ; Keep hidden
EndFunction

; Error-safe game loop with guaranteed cleanup
Function SafeGameLoop()
    Try
        inpClipMouseToWindow()
        inpSetMouseVisible(False)

        While running%
            ; ... game logic ...
        Wend
    Finally
        ; Always execute cleanup even on error/crash
        inpUnclipMouse()
        inpSetMouseVisible(True)
    EndTry
EndFunction

Since: 1.0 Status: Stable