Window Framework for UI Toolkit v2.0.x
GWG.WindowFramework.Manipulators.WindowFrameDragger Class Reference

A mouse manipulator that enables drag-and-move functionality for WindowFrame elements in Unity's UI Toolkit. More...

Inheritance diagram for GWG.WindowFramework.Manipulators.WindowFrameDragger:
Collaboration diagram for GWG.WindowFramework.Manipulators.WindowFrameDragger:

Public Member Functions

 WindowFrameDragger ()
 Initializes a new instance of the WindowFrameDragger with left-click activation.
void StartDirectDrag (Vector2 mousePos, int suppressSnappingFrames=10)
 Programmatically starts a drag operation on the target window from a mouse position (e.g. during a tab tear-off).

Protected Member Functions

override void RegisterCallbacksOnTarget ()
 Registers mouse event callbacks on the target element.
override void UnregisterCallbacksFromTarget ()
 Unregisters mouse event callbacks from the target element.

Private Member Functions

WindowFrame FindWindowDockedAt (WindowDockState state, WindowFrame exclude)
Vector2 GetClampedWindowLocation (float rootX, float rootY, VisualElement _targetWindow, bool bypassSnapping=false)
 Calculates and enforces position constraints for window movement operations.
void HideDockPreview ()
void HideTabDropGhost ()
void OnMouseDown (MouseDownEvent e)
 Handles mouse down events to initiate window dragging operations.
void OnMouseMove (MouseMoveEvent e)
 Handles mouse move events to update window position during drag operations.
void OnMouseUp (MouseUpEvent e)
 Handles mouse up events to complete window dragging operations.
void ShowDockPreview (VisualElement root, Rect rect, WindowFrame existingTarget=null)
void ShowTabDropGhost (WindowFrame targetWindow)
void UpdateDockZonePreview (Vector2 mousePos, WindowFrame wf)
bool UpdateTabDropTarget (Vector2 mousePos, WindowFrame draggedWindow)

Private Attributes

float _clickXOffset
 The horizontal offset between the mouse click position and the window's left edge.
float _clickYOffset
 The vertical offset between the mouse click position and the window's top edge.
VisualElement _dockPreviewGhost
 VisualElement displaying the semi-transparent preview ghost of the dock target.
bool _isActive
 Indicates whether a drag operation is currently active.
WindowDockState _pendingDockState = WindowDockState.Floating
 Active dock zone detected during the current drag operation.
WindowFrame _pendingTabTargetWindow
 Active neighbor window targeted for tab nesting during the drag operation.
int _suppressSnapFrames = 0
 Frame counter for temporarily suppressing magnetic snapping right after a tab tear-off.
VisualElement _tabDropGhost
 VisualElement displaying the tab-shaped drop ghost over a target window's tab bar.
Vector2? _tearOffOrigin = null
 Starting cursor position when tearing off from fullscreen or dock, used for Option B deadzone bypass.

Detailed Description

A mouse manipulator that enables drag-and-move functionality for WindowFrame elements in Unity's UI Toolkit.

This manipulator allows users to click and drag windows to reposition them within the screen boundaries. It respects window locking states and movement permissions while ensuring windows remain visible on screen. The dragger integrates seamlessly with the WindowFrame system to provide smooth, constrained window movement.

KeyValue Features:

  • Left-click drag movement from any attached element (typically title bars)
  • Respects WindowFrame.Locked and WindowFrame.AllowMove properties
  • Keeps windows within screen boundaries during movement
  • Maintains proper mouse capture and event handling
  • Brings windows to front when dragging begins
  • Smooth movement with click offset preservation
// Add dragger to a window's title bar for standard window movement
var titleBar = windowFrame.Q("title-bar");
titleBar.AddManipulator(new WindowFrameDragger());
// Add dragger to the entire window header area
var windowHeader = new VisualElement();
windowHeader.AddToClassList("window-header");
windowHeader.AddManipulator(new WindowFrameDragger());
windowFrame.Add(windowHeader);
// CSS styling for draggable areas
.window-header {
height: 30px;
background-color: #333;
cursor: move;
}
.window-header:hover {
background-color: #555;
}
WindowFrameDragger()
Initializes a new instance of the WindowFrameDragger with left-click activation.
Definition WindowFrameDragger.cs:137

Constructor & Destructor Documentation

◆ WindowFrameDragger()

GWG.WindowFramework.Manipulators.WindowFrameDragger.WindowFrameDragger ( )
inline

Initializes a new instance of the WindowFrameDragger with left-click activation.

The constructor configures the manipulator to respond only to left mouse button interactions. This prevents conflicts with other mouse operations such as context menus (right-click) or specialized middle-click behaviors.

The manipulator starts in an inactive state and will only begin drag operations when proper mouse down events are received on elements that allow movement.

// Create and attach dragger to a window's draggable area
var dragger = new WindowFrameDragger();
titleBarElement.AddManipulator(dragger);
// The dragger is now ready to handle left-click drag operations
// Right-click and middle-click events will be ignored
Here is the caller graph for this function:

Member Function Documentation

◆ FindWindowDockedAt()

WindowFrame GWG.WindowFramework.Manipulators.WindowFrameDragger.FindWindowDockedAt ( WindowDockState state,
WindowFrame exclude )
inlineprivate
Here is the caller graph for this function:

◆ GetClampedWindowLocation()

Vector2 GWG.WindowFramework.Manipulators.WindowFrameDragger.GetClampedWindowLocation ( float rootX,
float rootY,
VisualElement _targetWindow,
bool bypassSnapping = false )
inlineprivate

Calculates and enforces position constraints for window movement operations.

Parameters
rootXThe requested X position of the mouse cursor
rootYThe requested Y position of the mouse cursor
_targetWindowThe VisualElement being moved (typically a WindowFrame)
Returns
A Vector2 containing the constrained X (x) and Y (y) position values

This method implements comprehensive position constraint logic to ensure windows remain visible and usable within the screen boundaries:

Position Calculation:

  • Converts mouse position to window position using stored click offsets
  • Accounts for the difference between cursor location and window origin

Boundary Enforcement:

  1. Left boundary: Prevents window from moving beyond X = 0
  2. Top boundary: Prevents window from moving beyond Y = 0
  3. Right boundary: Ensures window's right edge stays within screen width
  4. Bottom boundary: Ensures window's bottom edge stays within screen height

The constraints ensure that windows remain fully accessible and cannot be accidentally moved off-screen where they would become difficult to retrieve.

// GetClampedWindowLocation is used internally during drag operations
// Example constraint scenarios:
// Screen size: 1920x1080, Window size: 400x300
// Scenario 1: User drags beyond left edge
// Mouse at (-50, 100), click offset (20, 10)
// Calculated position: (-50 - 20, 100 - 10) = (-70, 90)
// Clamped position: (0, 90) - window stays on screen
// Scenario 2: User drags beyond right edge
// Mouse at (1900, 200), window would be at (1880, 190)
// Window right edge: 1880 + 400 = 2280 > 1920 (screen width)
// Clamped position: (1520, 190) - right edge at screen edge
// Scenario 3: Normal movement within bounds
// Mouse at (500, 300), calculated position (480, 290)
// Window edges: left=480, right=880, top=290, bottom=590
// All within screen bounds → no clamping needed
Here is the call graph for this function:
Here is the caller graph for this function:

◆ HideDockPreview()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.HideDockPreview ( )
inlineprivate
Here is the caller graph for this function:

◆ HideTabDropGhost()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.HideTabDropGhost ( )
inlineprivate
Here is the caller graph for this function:

◆ OnMouseDown()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.OnMouseDown ( MouseDownEvent e)
inlineprivate

Handles mouse down events to initiate window dragging operations.

Parameters
eThe mouse down event data containing click position and button information

This method performs comprehensive validation and setup for drag operations:

Validation Steps:

  1. Verifies that the manipulation can start (correct mouse button, etc.)
  2. Locates the parent WindowFrame element
  3. Checks if the window is locked (Locked property)
  4. Verifies movement is allowed (AllowMove property)

Setup Operations:

  1. Brings the target window to the front for better user experience
  2. Calculates click offsets to maintain cursor-to-window relationship
  3. Activates the drag state
  4. Captures mouse input to ensure reliable drag tracking

The method will exit early if any validation fails, ensuring that locked or movement-disabled windows cannot be dragged.

// OnMouseDown is triggered automatically when user clicks the draggable element
// Example validation scenarios:
// Scenario 1: Normal window (can be dragged)
window.Locked = false;
window.AllowMove = true;
// → Drag operation begins successfully
// Scenario 2: Locked window
window.Locked = true;
window.AllowMove = true;
// → Drag operation prevented, method exits early
// Scenario 3: Movement disabled
window.Locked = false;
window.AllowMove = false;
// → Drag operation prevented, method exits early
// Click offset calculation:
// If window is at (100, 50) and user clicks at (120, 60):
// _clickXOffset = 120 - 100 = 20
// _clickYOffset = 60 - 50 = 10
// During drag, window position = mousePosition - offset
Here is the caller graph for this function:

◆ OnMouseMove()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.OnMouseMove ( MouseMoveEvent e)
inlineprivate

Handles mouse move events to update window position during drag operations.

Parameters
eThe mouse move event data containing current cursor position
Here is the call graph for this function:
Here is the caller graph for this function:

◆ OnMouseUp()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.OnMouseUp ( MouseUpEvent e)
inlineprivate

Handles mouse up events to complete window dragging operations.

Parameters
eThe mouse up event data
Here is the call graph for this function:
Here is the caller graph for this function:

◆ RegisterCallbacksOnTarget()

override void GWG.WindowFramework.Manipulators.WindowFrameDragger.RegisterCallbacksOnTarget ( )
inlineprotected

Registers mouse event callbacks on the target element.

This method is automatically called by the UI Toolkit when the manipulator is added to a target element. It establishes the event handling chain for:

  • MouseDownEvent: Initiates drag operations and validates permissions
  • MouseMoveEvent: Updates window position during active drag operations
  • MouseUpEvent: Completes drag operations and restores normal input

The callbacks are registered to handle events in the appropriate phase to ensure reliable drag behavior even with complex UI hierarchies.

// RegisterCallbacksOnTarget is called automatically when you attach the manipulator
myDraggableElement.AddManipulator(new WindowFrameDragger());
// ↑ This automatically calls RegisterCallbacksOnTarget()
// The element now responds to:
// - Mouse down: Check if drag can start, calculate offsets
// - Mouse move: Update window position if dragging
// - Mouse up: End drag operation, release mouse capture
Here is the call graph for this function:

◆ ShowDockPreview()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.ShowDockPreview ( VisualElement root,
Rect rect,
WindowFrame existingTarget = null )
inlineprivate
Here is the caller graph for this function:

◆ ShowTabDropGhost()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.ShowTabDropGhost ( WindowFrame targetWindow)
inlineprivate
Here is the caller graph for this function:

◆ StartDirectDrag()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.StartDirectDrag ( Vector2 mousePos,
int suppressSnappingFrames = 10 )
inline

Programmatically starts a drag operation on the target window from a mouse position (e.g. during a tab tear-off).

Parameters
mousePosThe current screen position of the cursor.
suppressSnappingFramesNumber of mouse move frames to suppress magnetic snapping to prevent jumpiness on tear-off.

◆ UnregisterCallbacksFromTarget()

override void GWG.WindowFramework.Manipulators.WindowFrameDragger.UnregisterCallbacksFromTarget ( )
inlineprotected

Unregisters mouse event callbacks from the target element.

This method is automatically called by the UI Toolkit when the manipulator is removed from an element or when the element is destroyed. It ensures proper cleanup of event handlers to prevent memory leaks.

Unregistration is essential for maintaining application performance and preventing orphaned event handlers from consuming resources or causing unexpected behavior after elements are no longer active.

// UnregisterCallbacksFromTarget is called automatically when you remove the manipulator
myDraggableElement.RemoveManipulator(existingDragger);
// ↑ This automatically calls UnregisterCallbacksFromTarget()
// Also called automatically when the element is destroyed
myDraggableElement.RemoveFromHierarchy();
// ↑ This triggers cleanup including UnregisterCallbacksFromTarget()
Here is the call graph for this function:

◆ UpdateDockZonePreview()

void GWG.WindowFramework.Manipulators.WindowFrameDragger.UpdateDockZonePreview ( Vector2 mousePos,
WindowFrame wf )
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ UpdateTabDropTarget()

bool GWG.WindowFramework.Manipulators.WindowFrameDragger.UpdateTabDropTarget ( Vector2 mousePos,
WindowFrame draggedWindow )
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

Field Documentation

◆ _clickXOffset

float GWG.WindowFramework.Manipulators.WindowFrameDragger._clickXOffset
private

The horizontal offset between the mouse click position and the window's left edge.

This offset is calculated when a drag operation begins and maintains the relative position between the cursor and window origin throughout the drag operation. This ensures smooth, predictable movement regardless of where on the draggable element the user initially clicks.

◆ _clickYOffset

float GWG.WindowFramework.Manipulators.WindowFrameDragger._clickYOffset
private

The vertical offset between the mouse click position and the window's top edge.

This offset is calculated when a drag operation begins and maintains the relative position between the cursor and window origin throughout the drag operation. This ensures smooth, predictable movement regardless of where on the draggable element the user initially clicks.

◆ _dockPreviewGhost

VisualElement GWG.WindowFramework.Manipulators.WindowFrameDragger._dockPreviewGhost
private

VisualElement displaying the semi-transparent preview ghost of the dock target.

◆ _isActive

bool GWG.WindowFramework.Manipulators.WindowFrameDragger._isActive
private

Indicates whether a drag operation is currently active.

Set to true when a valid drag operation begins and false when it ends. Used to control event processing and ensure drag operations are properly contained within mouse down/up pairs.

◆ _pendingDockState

WindowDockState GWG.WindowFramework.Manipulators.WindowFrameDragger._pendingDockState = WindowDockState.Floating
private

Active dock zone detected during the current drag operation.

◆ _pendingTabTargetWindow

WindowFrame GWG.WindowFramework.Manipulators.WindowFrameDragger._pendingTabTargetWindow
private

Active neighbor window targeted for tab nesting during the drag operation.

◆ _suppressSnapFrames

int GWG.WindowFramework.Manipulators.WindowFrameDragger._suppressSnapFrames = 0
private

Frame counter for temporarily suppressing magnetic snapping right after a tab tear-off.

◆ _tabDropGhost

VisualElement GWG.WindowFramework.Manipulators.WindowFrameDragger._tabDropGhost
private

VisualElement displaying the tab-shaped drop ghost over a target window's tab bar.

◆ _tearOffOrigin

Vector2? GWG.WindowFramework.Manipulators.WindowFrameDragger._tearOffOrigin = null
private

Starting cursor position when tearing off from fullscreen or dock, used for Option B deadzone bypass.