Interface IMouseGrabHandler

Namespace: Terminal.Gui.App

Assembly: Terminal.Gui.dll

Defines a contract for tracking which View (if any) has 'grabbed' the mouse, giving it exclusive priority for mouse events such as movement, button presses, and release.

public interface IMouseGrabHandler

Remarks

When to Use Mouse Grab:

Mouse grab is essential for scenarios where a view must receive all mouse events during an operation, even when the mouse moves outside the view's bounds. Common use cases include:

Dragging operations (e.g., moving windows, resizing borders, dragging scrollbar thumbs)
Button hold-to-repeat behavior (e.g., scrollbar arrows, spin buttons)
Selection operations (e.g., drag-selecting text or items)
Custom drag-and-drop interactions

Grab Lifecycle:

Press: View calls GrabMouse(View?) (typically on Button1Pressed). The GrabbingMouse event fires first (can be cancelled), then GrabbedMouse.
During Grab: All mouse events (movement, additional presses) are routed exclusively to the grabbed view with coordinates converted to the view's viewport. HandleMouseGrab(View?, Mouse) intercepts and redirects events.
Release: View calls UngrabMouse() (typically on Button1Released or Button1Clicked). The UnGrabbingMouse event fires first (can be cancelled), then UnGrabbedMouse. Normal mouse routing resumes.

Auto-Grab Feature:

Views with MouseHighlightStates or MouseHoldRepeat enabled automatically grab the mouse on button press. See NewMouseEvent(Mouse) for details.

Implementation Notes:

The grabbed view is stored using a WeakReference<T>, so disposed views are automatically released without causing memory leaks.
Only one view can hold the mouse grab at a time. Calling GrabMouse(View?) with a new view implicitly releases the previous grab.
Grab events (GrabbingMouse, UnGrabbingMouse) follow the Cancellable Work Pattern (CWP) - handlers can set Cancel = true to prevent the operation.

Example Usage (Manual Grab):

protected override bool OnMouseEvent (Mouse mouse)
{
    if (mouse.Flags.HasFlag (MouseFlags.Button1Pressed))
    {
        App?.Mouse.GrabMouse (this);
        _isDragging = true;
        return true;
    }

    if (_isDragging && mouse.Flags.HasFlag (MouseFlags.Button1Released))
    {
        App?.Mouse.UngrabMouse ();
        _isDragging = false;
        return true;
    }

    if (_isDragging)
    {
        // Handle drag - mouse.Position is relative to this view's viewport
        UpdateDragPosition (mouse.Position);
        return true;
    }

    return false;
}

Methods

GrabMouse(View?): Grabs the mouse, forcing all mouse events to be routed exclusively to the specified view until UngrabMouse() is called.

HandleMouseGrab(View?, Mouse): INTERNAL: Handles mouse grab logic for a mouse event, routing events to the grabbed view if one exists.

IsGrabbed(): Determines whether any view currently has the mouse grabbed.

IsGrabbed(View?): Determines whether the specified view currently has the mouse grabbed.

UngrabMouse(): Releases the mouse grab, restoring normal mouse event routing to the view under the mouse pointer.

Events

GrabbedMouse: Raised after a view has successfully grabbed the mouse.

GrabbingMouse: Raised when a view requests to grab the mouse; can be cancelled.

UnGrabbedMouse: Raised after a view has released the mouse grab.

UnGrabbingMouse: Raised when a view requests to release the mouse grab; can be cancelled.

Table of Contents

Interface IMouseGrabHandler

Remarks

Methods

Events

See Also