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:

Public Member Functions
	WindowFrameDragger ()
	Initializes a new instance of the WindowFrameDragger with left-click activation.

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
Vector2	GetClampedWindowLocation (float rootX, float rootY, VisualElement _targetWindow)
	Calculates and enforces position constraints for window movement operations.
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.

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.
bool	_isActive
	Indicates whether a drag operation is currently active.

Detailed Description

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.

Key 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;
}

Constructor & Destructor Documentation

WindowFrameDragger()

GWG.WindowFramework.Manipulators.WindowFrameDragger.WindowFrameDragger

(

)

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

Member Function Documentation

GetClampedWindowLocation()

Vector2 GWG.WindowFramework.Manipulators.WindowFrameDragger.GetClampedWindowLocation ( float rootX, float rootY, VisualElement _targetWindow )

private

Parameters

rootX	The requested X position of the mouse cursor
rootY	The requested Y position of the mouse cursor
_targetWindow	The 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

OnMouseDown()

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

private

Parameters

e	The 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

OnMouseMove()

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

private

Parameters

e	The mouse move event data containing current cursor position

This method continuously updates the window position while a drag operation is active:

1. Validates that the drag operation is active and mouse capture is maintained
2. Locates the target WindowFrame element
3. Calculates the new window position based on mouse position and stored click offsets
4. Applies position constraints through GetClampedWindowLocation()
5. Updates the window's top and left style properties
6. Stops event propagation to prevent interference with other UI elements

The position calculation uses the stored click offsets to maintain the relative position between the cursor and the window, providing smooth and predictable movement behavior throughout the drag operation.

// OnMouseMove is called continuously while dragging
 
// Example position calculation:
// Initial click: mouse at (120, 60), window at (100, 50)
// Offsets: _clickXOffset = 20, _clickYOffset = 10
 
// During drag: mouse moves to (200, 150)
// New window position = (200 - 20, 150 - 10) = (180, 140)
// After clamping: position constrained to screen boundaries
 
// Position constraints applied:
// - Minimum X: 0 (left edge of screen)
// - Minimum Y: 0 (top edge of screen)
// - Maximum X: Screen.width - window.width
// - Maximum Y: Screen.height - window.height

OnMouseUp()

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

private

Parameters

e	The mouse up event data

This method finalizes the drag operation when the user releases the mouse button:

1. Validates that an active drag operation exists and can be properly terminated
2. Deactivates the drag state to prevent further position updates
3. Releases mouse capture to restore normal input handling
4. Stops event propagation to maintain clean event flow

After this method completes, the window remains in its new position and normal mouse interaction is fully restored. The drag operation is complete and the window can be interacted with normally or dragged again.

// OnMouseUp is triggered when user releases the mouse button
 
// Example completion sequence:
// 1. User releases left mouse button after dragging
// 2. OnMouseUp validates the operation can be stopped
// 3. _isActive = false (prevents further position updates)
// 4. Mouse capture released (restores normal input)
// 5. Event propagation stopped (clean event handling)
// 6. Window stays at final drag position
// 7. Ready for next interaction (click, drag, etc.)

RegisterCallbacksOnTarget()

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

protected

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

UnregisterCallbacksFromTarget()

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

protected

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()

Member Data Documentation

_clickXOffset

float GWG.WindowFramework.Manipulators.WindowFrameDragger._clickXOffset

private

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

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.

_isActive

bool GWG.WindowFramework.Manipulators.WindowFrameDragger._isActive

private

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.