GWG.WindowFramework.Manipulators.TooltipManipulator Class Reference

A sophisticated pointer manipulator that manages tooltip behavior for UI elements within the Window Framework. More...

Inheritance diagram for GWG.WindowFramework.Manipulators.TooltipManipulator:

Public Member Functions
	TooltipManipulator ()
	Initializes a new instance of the TooltipManipulator and establishes connection to the tooltip system.

Protected Member Functions
override void	RegisterCallbacksOnTarget ()
	Registers pointer and mouse event callbacks on the target element.
override void	UnregisterCallbacksFromTarget ()
	Unregisters all event callbacks from the target element during cleanup.

Properties
float	TooltipShowDelay [get]
	Gets the tooltip display delay from the WindowFrameController settings, converted to seconds.

Private Member Functions
void	HideTooltipImmediately ()
	Immediately hides any visible tooltip and cancels all pending tooltip operations.
void	MouseMove (MouseMoveEvent evt)
	Handles mouse movement events to manage tooltip display timing and cancellation.
void	OnPointerCaptured (PointerCaptureEvent evt)
	Handles pointer capture events that indicate the start of drag operations.
void	OnPointerCaptureOut (PointerCaptureOutEvent evt)
	Handles pointer capture release events that indicate the end of drag operations.
void	PointerDown (PointerDownEvent evt)
	Handles pointer down events to immediately hide tooltips when user interaction begins.
void	PointerEnter (PointerEnterEvent evt)
	Handles pointer enter events to begin tooltip tracking when cursor enters the element.
void	PointerLeave (PointerLeaveEvent evt)
	Handles pointer leave events to hide tooltips and stop tracking when cursor exits the element.
void	PointerUp (PointerUpEvent evt)
	Handles pointer up events to reset dragging state after user interactions.

Private Attributes
bool	_isDragging
	Tracks whether a drag operation is currently in progress.
Vector2	_lastMousePosition
	Stores the last recorded mouse position for movement detection.
bool	_mouseIsOverTarget
	Tracks whether the mouse pointer is currently positioned over the target element.
bool	_tooltipScheduled
	Indicates whether a tooltip display operation has been scheduled.
IVisualElementScheduledItem	_tooltipTask
	Reference to the scheduled tooltip display task.
readonly WindowFrameTooltip	_windowFrameTooltip
	Reference to the Window Framework's tooltip system.

Static Private Attributes
const float	MOUSE_MOVEMENT_THRESHOLD = 2f
	The minimum mouse movement distance (in pixels) required to cancel tooltip display.

Detailed Description

This manipulator provides intelligent tooltip management that integrates seamlessly with UI interactions:

Key Features:

• Smart timing based on WindowFrameController settings
• Mouse movement detection to prevent premature tooltip display
• Drag operation awareness to hide tooltips during interactions
• Pointer capture detection for better UI responsiveness
• Automatic cleanup and proper event handling
• Integration with WindowFrameTooltip system

The manipulator automatically handles complex interaction scenarios such as:

• Hiding tooltips when dragging begins
• Canceling tooltip display during rapid mouse movement
• Respecting global pointer capture states
• Managing tooltip lifecycle across hover/leave events

This manipulator is automatically applied to elements with tooltip content when WindowFrameController.ApplyTooltips() is called.

// Automatic application (recommended approach)
var button = new Button { text = "Save", tooltip = "Save the current document" };
container.Add(button);
WindowFrameController.ApplyTooltips(container); // Automatically adds TooltipManipulator
 
// Manual application (for advanced scenarios)
var customElement = new VisualElement { tooltip = "Custom tooltip text" };
customElement.AddManipulator(new TooltipManipulator());
 
// Programmatic tooltip setup
var dynamicButton = new Button { text = "Dynamic" };
dynamicButton.tooltip = GetDynamicTooltipText();
dynamicButton.AddManipulator(new TooltipManipulator());

Constructor & Destructor Documentation

TooltipManipulator()

GWG.WindowFramework.Manipulators.TooltipManipulator.TooltipManipulator

(

)

The constructor attempts to obtain a reference to the Window Framework's tooltip system through the WindowFrameController. If the controller is not available, tooltip functionality will be disabled for this manipulator instance.

The manipulator is designed to gracefully handle scenarios where the WindowFrameController is not yet initialized or is unavailable, ensuring robust operation in various application startup sequences.

// Standard usage - manipulator automatically connects to tooltip system
var tooltipManipulator = new TooltipManipulator();
myElement.AddManipulator(tooltipManipulator);
 
// The manipulator will automatically:
// 1. Connect to WindowFrameController.WindowFrameTooltip if available
// 2. Gracefully handle missing WindowFrameController
// 3. Provide tooltip functionality when tooltip system is ready
 
// Verification of tooltip system availability
if (WindowFrameController.Instance != null)
{
    // Tooltip system is available - full functionality enabled
    var manipulator = new TooltipManipulator();
    element.AddManipulator(manipulator);
}

Member Function Documentation

HideTooltipImmediately()

void GWG.WindowFramework.Manipulators.TooltipManipulator.HideTooltipImmediately ( )

private

This method provides immediate tooltip suppression for scenarios where tooltips must be hidden without delay:

Operations Performed:

1. Cancels any scheduled tooltip display operations
2. Pauses active tooltip display timers
3. Immediately hides visible tooltips without fade animation

This method is used in high-priority scenarios such as:

• User clicks or interactions begin
• Drag operations start
• Rapid cursor movement detected
• Pointer capture events occur

The immediate hiding ensures responsive UI behavior and prevents tooltips from interfering with user interactions.

// HideTooltipImmediately is called automatically in various scenarios:
 
// Scenario 1: User clicks element
// PointerDown → HideTooltipImmediately() → Instant tooltip removal
 
// Scenario 2: Drag operation begins
// OnPointerCaptured → HideTooltipImmediately() → Clear UI for dragging
 
// Scenario 3: Rapid mouse movement
// MouseMove (large distance) → HideTooltipImmediately() → No tooltip during sweep
 
// Manual usage (for custom scenarios):
void OnCustomInteraction()
{
    // Hide tooltips before starting custom operation
    tooltipManipulator.HideTooltipImmediately(); // If method were public
}

MouseMove()

void GWG.WindowFramework.Manipulators.TooltipManipulator.MouseMove ( MouseMoveEvent evt )

private

Parameters

evt	The mouse move event data containing current cursor position

This method implements sophisticated mouse movement tracking to provide intelligent tooltip behavior:

Drag Detection:

• Checks for active drag operations or pointer capture
• Immediately hides tooltips during drag operations

Movement Analysis:

• Calculates distance moved since last position update
• Compares movement against MOUSE_MOVEMENT_THRESHOLD
• Cancels tooltip display during rapid movement

Tooltip Scheduling:

• Starts tooltip display timer when mouse settles over element
• Ensures only one tooltip operation is scheduled at a time
• Respects global tooltip delay settings

This creates a natural tooltip experience where tooltips appear when the user pauses over an element but don't interfere with active cursor movement or interactions.

// MouseMove is called continuously while cursor moves over element
 
// Movement threshold behavior:
// - Small movements (<2 pixels): Tooltip scheduling continues
// - Large movements (≥2 pixels): Tooltip canceled/hidden
 
// Example scenarios:
 
// Scenario 1: User slowly moves cursor into element
// Movement < 2px → Tooltip timer starts after settling
 
// Scenario 2: User quickly sweeps cursor across element
// Movement ≥ 2px → Tooltip display canceled
 
// Scenario 3: User pauses cursor over element
// No movement for TooltipShowDelay → Tooltip displays
 
// Integration with drag operations:
// - Any active drag → Tooltip immediately hidden
// - Pointer capture detected → No tooltip scheduling

OnPointerCaptured()

void GWG.WindowFramework.Manipulators.TooltipManipulator.OnPointerCaptured ( PointerCaptureEvent evt )

private

Parameters

evt	The pointer capture event data

This method responds to pointer capture events, which typically occur when drag operations begin (such as window dragging or resizing). When pointer capture is detected:

1. Sets the dragging state flag to suppress tooltip display
2. Immediately hides any currently visible tooltips

This ensures that tooltips don't interfere with drag operations or remain visible during interactions where they would be distracting or unhelpful.

// OnPointerCaptured is triggered automatically during drag operations
 
// Example scenario - Window dragging:
// 1. User clicks and drags window title bar
// 2. WindowFrameDragger captures pointer
// 3. OnPointerCaptured is triggered
// 4. _isDragging = true, tooltip hidden immediately
// 5. User can drag without tooltip interference
 
// Example scenario - Window resizing:
// 1. User clicks and drags resize handle
// 2. WindowFrameResizer captures pointer
// 3. OnPointerCaptured is triggered
// 4. Any visible tooltips are hidden

OnPointerCaptureOut()

void GWG.WindowFramework.Manipulators.TooltipManipulator.OnPointerCaptureOut ( PointerCaptureOutEvent evt )

private

Parameters

evt	The pointer capture out event data

This method responds to pointer capture release events, which occur when drag operations complete. The method resets the dragging state flag, allowing tooltip functionality to resume normal operation.

After this event, if the mouse cursor is still positioned over an element with tooltip content, normal tooltip timing and display logic will resume.

// OnPointerCaptureOut is triggered automatically when drag operations end
 
// Example scenario - End of window dragging:
// 1. User releases mouse button after dragging window
// 2. WindowFrameDragger releases pointer capture
// 3. OnPointerCaptureOut is triggered
// 4. _isDragging = false, tooltip functionality restored
// 5. If mouse is over tooltip element, normal timing resumes
 
// Normal tooltip behavior resumes:
// - Mouse movement detection active
// - Hover timing operational
// - Tooltip display possible again

PointerDown()

void GWG.WindowFramework.Manipulators.TooltipManipulator.PointerDown ( PointerDownEvent evt )

private

Parameters

evt	The pointer down event data

This method ensures that tooltips are immediately hidden when the user clicks on any UI element. This prevents tooltips from remaining visible during interactions and provides immediate visual feedback that user input has been received.

The immediate hiding behavior is important for maintaining responsive UI feel and preventing tooltip content from obscuring important interface elements during user interactions.

// PointerDown is triggered when user clicks any mouse button on the element
 
// Example interaction flows:
 
// Scenario 1: User clicks button while tooltip is visible
// 1. Tooltip is currently showing button description
// 2. User clicks button
// 3. PointerDown → HideTooltipImmediately()
// 4. Tooltip disappears immediately
// 5. Button action executes without tooltip interference
 
// Scenario 2: User clicks during tooltip delay
// 1. User hovers over element, tooltip timer active
// 2. User clicks before tooltip appears
// 3. PointerDown → Cancels pending tooltip, prevents display
// 4. User interaction proceeds cleanly

PointerEnter()

void GWG.WindowFramework.Manipulators.TooltipManipulator.PointerEnter ( PointerEnterEvent evt )

private

Parameters

evt	The pointer enter event data containing cursor position

This method initializes tooltip tracking when the cursor first enters the target element:

1. Sets the mouse-over-target flag to enable tooltip scheduling
2. Records the initial cursor position for movement tracking

After this event, the MouseMove event handler will begin monitoring cursor movement and scheduling tooltip display based on movement patterns and timing settings.

// PointerEnter is triggered when cursor moves into element bounds
 
// Event sequence:
// 1. Cursor moves from outside element to inside element
// 2. PointerEnter fires
// 3. _mouseIsOverTarget = true (enables tooltip logic)
// 4. _lastMousePosition updated for movement tracking
// 5. MouseMove events now trigger tooltip scheduling logic
 
// Example with button element:
var button = new Button { tooltip = "Click to save" };
// Cursor enters button area → PointerEnter → Tooltip tracking begins

PointerLeave()

void GWG.WindowFramework.Manipulators.TooltipManipulator.PointerLeave ( PointerLeaveEvent evt )

private

Parameters

evt	The pointer leave event data

This method performs comprehensive cleanup when the cursor leaves the target element:

State Management:

• Disables mouse-over-target tracking
• Cancels any scheduled tooltip operations
• Pauses active tooltip display timers

Tooltip Hiding Logic:

• If tooltip is not fully visible: Immediate hiding (CloseNow)
• If tooltip is fully visible: Graceful hiding with fade (Close)

This approach provides smooth user experience by using immediate hiding for tooltips that are still appearing while allowing visible tooltips to fade out gracefully.

// PointerLeave is triggered when cursor moves outside element bounds
 
// Cleanup sequence:
// 1. Cursor moves from inside element to outside element
// 2. PointerLeave fires
// 3. _mouseIsOverTarget = false (disables tooltip logic)
// 4. Any scheduled tooltip operations canceled
// 5. Current tooltip hidden appropriately
 
// Tooltip hiding behavior:
// - opacity < 1 (still fading in) → CloseNow() for immediate hide
// - opacity = 1 (fully visible) → Close() for graceful fade
 
// Example scenarios:
// - User quickly moves cursor through element → Immediate hide
// - User reads tooltip then moves away → Graceful fade

PointerUp()

void GWG.WindowFramework.Manipulators.TooltipManipulator.PointerUp ( PointerUpEvent evt )

private

Parameters

evt	The pointer up event data

This method ensures that the dragging state is properly reset when pointer interactions complete. While the primary drag state management occurs through pointer capture events, this provides an additional safety net to ensure tooltip functionality is restored after any interaction sequence.

This helps maintain consistent tooltip behavior even in complex interaction scenarios where pointer capture events might not fire as expected.

// PointerUp is triggered when user releases any mouse button
 
// Safety net behavior:
// - Primary drag detection uses pointer capture events
// - PointerUp provides backup state reset
// - Ensures tooltip functionality is restored after interactions
 
// Example scenario:
// 1. Complex drag operation with multiple manipulators
// 2. Pointer capture events might be handled by other components
// 3. PointerUp ensures dragging state is reset
// 4. Tooltip functionality restored for next interaction

RegisterCallbacksOnTarget()

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

protected

This method establishes comprehensive event handling for tooltip behavior by registering callbacks for all relevant interaction events:

Pointer Events:

• PointerDownEvent: Immediately hides tooltips when user begins interaction
• PointerUpEvent: Resets dragging state when interaction completes
• PointerEnterEvent: Begins tooltip timing when cursor enters element
• PointerLeaveEvent: Hides tooltips and cancels pending display when cursor exits

Mouse Events:

• MouseMoveEvent: Monitors cursor movement to manage tooltip display timing

Capture Events:

• PointerCaptureEvent: Detects drag operations and suppresses tooltips
• PointerCaptureOutEvent: Restores tooltip functionality when drag ends

The comprehensive event coverage ensures tooltips behave intelligently across all common user interaction patterns.

// RegisterCallbacksOnTarget is called automatically when manipulator is added
element.AddManipulator(new TooltipManipulator());
// ↑ Automatically registers all necessary event callbacks
 
// Events registered:
// - PointerDown → HideTooltipImmediately()
// - PointerUp → Reset drag state
// - PointerEnter → Start hover tracking
// - PointerLeave → Hide tooltip and cancel pending
// - MouseMove → Track movement and manage display timing
// - PointerCapture → Detect drag start
// - PointerCaptureOut → Detect drag end

UnregisterCallbacksFromTarget()

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

protected

This method ensures proper cleanup by removing all event callbacks that were registered during initialization. It prevents memory leaks and ensures that the manipulator doesn't continue processing events after removal.

The method mirrors RegisterCallbacksOnTarget() by unregistering every callback that was originally registered, maintaining perfect cleanup symmetry.

// UnregisterCallbacksFromTarget is called automatically when manipulator is removed
element.RemoveManipulator(existingTooltipManipulator);
// ↑ Automatically unregisters all event callbacks
 
// Also called automatically when element is destroyed
element.RemoveFromHierarchy();
// ↑ Triggers cleanup including callback unregistration
 
// All callbacks are properly removed:
// ✓ PointerDown, PointerUp, PointerEnter, PointerLeave
// ✓ MouseMove, PointerCapture, PointerCaptureOut

Member Data Documentation

_isDragging

bool GWG.WindowFramework.Manipulators.TooltipManipulator._isDragging

private

Set to true when pointer capture events indicate a drag operation has begun. Used to suppress tooltip display during drag operations, as tooltips would interfere with drag feedback and user interaction.

_lastMousePosition

Vector2 GWG.WindowFramework.Manipulators.TooltipManipulator._lastMousePosition

private

Used in conjunction with MOUSE_MOVEMENT_THRESHOLD to detect significant mouse movement. When movement exceeds the threshold, tooltip display is canceled to prevent tooltips from appearing during rapid cursor movement.

_mouseIsOverTarget

bool GWG.WindowFramework.Manipulators.TooltipManipulator._mouseIsOverTarget

private

This flag is updated by PointerEnter and PointerLeave events to maintain accurate state tracking. It's used to determine when tooltips should be scheduled for display and when they should be hidden.

_tooltipScheduled

bool GWG.WindowFramework.Manipulators.TooltipManipulator._tooltipScheduled

private

This flag prevents multiple tooltip display operations from being scheduled simultaneously. It's set to true when a tooltip display is queued and false when the operation completes or is canceled.

_tooltipTask

IVisualElementScheduledItem GWG.WindowFramework.Manipulators.TooltipManipulator._tooltipTask

private

This scheduled item can be paused or canceled when tooltip display needs to be interrupted due to user interaction changes. It's created when tooltip display is scheduled and cleared when the operation completes.

_windowFrameTooltip

readonly WindowFrameTooltip GWG.WindowFramework.Manipulators.TooltipManipulator._windowFrameTooltip

private

This reference is obtained from the WindowFrameController during construction and provides access to the centralized tooltip display system. If the WindowFrameController is not available, tooltip functionality is disabled.

MOUSE_MOVEMENT_THRESHOLD

const float GWG.WindowFramework.Manipulators.TooltipManipulator.MOUSE_MOVEMENT_THRESHOLD = 2f

staticprivate

This threshold prevents tooltips from being canceled by minor mouse movements such as hand tremor or slight adjustments. The value of 2 pixels provides a good balance between responsiveness and stability.

Property Documentation

TooltipShowDelay

float GWG.WindowFramework.Manipulators.TooltipManipulator.TooltipShowDelay

getprivate

The delay in seconds before tooltips are displayed, or 0.5 seconds as fallback if WindowFrameController is not available.

This property provides dynamic access to the current tooltip delay setting, allowing tooltips to respect user preferences and configuration changes. The delay is automatically converted from milliseconds (WindowFrameController format) to seconds (Unity scheduler format).

// The delay is automatically retrieved from WindowFrameController settings
// Example: If WindowFrameController.TooltipShowDelay = 2000 (2 seconds)
// Then TooltipShowDelay returns 2.0f
 
// Fallback behavior when WindowFrameController is unavailable
// Returns 0.5f (500 milliseconds) as a reasonable default