WidgetSetMouseCapture - ProGUI Reference Manual

Syntax

PreviousCaptureWidget = WidgetSetMouseCapture(Widget)

Description

Captures the mouse input for the specified widget. Once captured, all subsequent mouse events within the parent window, regardless of the cursor's position, are directed to this widget until capture is released using WidgetReleaseMouseCapture().

Parameters

Widget
The handle of the ProGUI widget that should capture the mouse.

Return Value

Returns the handle of the ProGUI widget that previously held the mouse capture, if any. Returns #Null if no widget previously held the capture or if the input `Widget` handle is invalid.

Remarks

This is typically used for drag operations initiated on a specific widget. It ensures that mouse move and button up events are received by the initiating widget even if the cursor leaves the widget's bounds. This function internally calls WindowSetMouseCapture() on the widget's parent window and manages routing within the DLL. Remember to release capture with WidgetReleaseMouseCapture().

Example

IncludeFile "ProGUI_PB.pbi"

Global DraggingWidget, DragOffsetX.d, DragOffsetY.d

; Custom draw procedure
Procedure DrawDraggableWidget(Widget, EventType, *EventData.PG_EventDraw, *UserData)
    DrawBox(0, 0, *EventData\width, *EventData\height, RGB(180, 210, 255), 1)
    DrawBoxStroke(0, 0, *EventData\width, *EventData\height, RGB(50, 80, 120))
EndProcedure

; Event handler for dragging
Procedure DragHandler(Widget, EventType, *EventData.PG_EventMouse)
  Select EventType
    Case #PG_Event_MouseLeftButtonDown
      Debug "Mouse Down on Widget - Capturing"
      DraggingWidget = Widget
      DragOffsetX = *EventData\x ; Store offset relative to widget top-left
      DragOffsetY = *EventData\y
      WidgetSetMouseCapture(Widget) ; Capture mouse for this widget

    Case #PG_Event_MouseMove
      If DraggingWidget = Widget
        ParentWindow = WidgetGetParentWindow(Widget)
        CurrentX.d = *EventData\x + WidgetGetX(Widget) - DragOffsetX
        CurrentY.d = *EventData\y + WidgetGetY(Widget) - DragOffsetY
        Debug "Dragging Widget... Window Coords X: " + StrD(CurrentX) + ", Y: " + StrD(CurrentY)
        WindowRedraw(ParentWindow) ; Redraw parent to show potential movement effect
      EndIf

    Case #PG_Event_MouseLeftButtonUp
      If DraggingWidget = Widget
        Debug "Mouse Up on Widget - Releasing Capture"
        WidgetReleaseMouseCapture()
        DraggingWidget = #Null
      EndIf
  EndSelect
EndProcedure

StartProGUI()

MyWindow = CreateWindow(0, 0, 400, 300, "Widget Mouse Capture")
RootLayout = WindowGetLayout(MyWindow)
LayoutSetType(RootLayout, #PG_Layout_Type_Basic)
LayoutSetPadding(RootLayout, 10)

If MyWindow
  Draggable = CreateWidget(50, 50, 80, 40)
  WidgetSetClass(Draggable, "draggable")
  AddEventHandler(Draggable, #PG_Event_Draw, @DrawDraggableWidget())
  AddEventHandler(Draggable, #PG_Event_MouseLeftButtonDown, @DragHandler())
  AddEventHandler(Draggable, #PG_Event_MouseMove, @DragHandler())
  AddEventHandler(Draggable, #PG_Event_MouseLeftButtonUp, @DragHandler())

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow
EndIf

StopProGUI()

Supported OS

Windows, Linux