Class MouseControllerDispatcher

MouseControllerDispatcher coordinates mouse events among competing mouse controllers. Based on the position of the mouse and context of the control every registered controller's HitTest method is called to determine the best controller for the following mouse action. This controller will then receive mouse events.

Inheritance
System.Object
NonFinalizeDisposable
MouseControllerDispatcher
ScrollControllMouseControllerDispatcher
Implements
System.IDisposable
System.Collections.IEnumerable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Syncfusion.Windows.Forms
Assembly: Syncfusion.Shared.Base.dll
Syntax
public class MouseControllerDispatcher : NonFinalizeDisposable, IDisposable, IEnumerable
Remarks

Any Mouse Controller needs to implement the IMouseController interface.

In its implementation of MouseController.HitTest, the mouse controller should determine whether your controller wants to handle the mouse events based current context.

MouseControllerDispatcher will call HitTest for each Mouse Controller that has been registered with Add(IMouseController). The Mouse Controller that wins the vote will receive all Mouse hovering events like MouseHoverEnter, MouseHover and MouseHoverLeave as long as its HitTest method indicates that it wants to handle the mouse event. A MouseHoverLeave notification is guaranteed after MouseHoverEnter has been called.

When the user presses the mouse, a MouseDown will be sent to the controller. All subsequent mouse events will then go to that specific controller until the user releases the mouse or the mouse operations is cancelled. A call to either MouseUp or CancelMode is guaranteed after a controller MouseDown method was called.

Mouse controllers are registered by calling the Add method.

If the control that MouseControllerDispatcher should be associated with is derived from ScrollControl, you should use ScrollControllMouseControllerDispatcher because it will automatically hook itself up with mouse events from ScrollControl.

Otherwise if you want to attach MouseControllerDispatcher to a different type of Control, you need to delegate mouse events to MouseControllerDispatcher. MouseControllerDispatcher provides ProcessXYZ methods for every mouse event that should be forwarded. Simply call these methods from your mouse event handlers in your control.

Constructors

MouseControllerDispatcher(Control)

Initializes a new MouseControllerDispatcher object and associates it with the parent control.

Declaration
public MouseControllerDispatcher(Control owner)
Parameters
Type Name Description
System.Windows.Forms.Control owner

Properties

ActiveController

Returns a reference to the active mouse controller that is receiving MouseDown, MouseMove and MouseUp messages when the user has pressed a mouse button.

Declaration
public IMouseController ActiveController { get; }
Property Value
Type
IMouseController

AllowDoubleClickTimer

Property AllowDoubleClickTimer (bool).

Declaration
public bool AllowDoubleClickTimer { get; set; }
Property Value
Type
System.Boolean

DisplayCursor

Returns the cursor to be displayed.

Declaration
public Cursor DisplayCursor { get; }
Property Value
Type
System.Windows.Forms.Cursor

LastHitTestCode

Returns the last HitTest value returned that was non-zero. Check this property if you need to make decision on your mouse controller's HitTest.

Declaration
public int LastHitTestCode { get; }
Property Value
Type
System.Int32

MouseHoverController

Returns the controller that currently receives mouse hovering messages.

Declaration
protected IMouseController MouseHoverController { get; }
Property Value
Type
IMouseController

Owner

Returns a reference to the associated control.

Declaration
public Control Owner { get; }
Property Value
Type
System.Windows.Forms.Control

TrackMouse

Enables support for mouse tracking.

Declaration
public Rectangle TrackMouse { get; set; }
Property Value
Type
System.Drawing.Rectangle
Remarks

Specify the bounds where the mouse tracking should start. As soon as the user moves the mouse over the specified region, MouseControllerDispatcher will simulate a mouse down event. When the user presses any mouse button MouseControllerDispatcher will simulate a mouse up and resets the mouse tracking mode. After the initial click on a mouse button, mouse processing will work as usual.

note

Mouse tracking lets you easily simulate the behavior of windows combo boxes.

Examples

This example enables Mouse Tracking after the drop-down has been shown.

public override void DropDownContainerShowedDropDown(object sender, EventArgs e)
{
    this.ListControlPart.grid.MouseControllerDispatcher.TrackMouse =
        this.ListControlPart.grid.RangeInfoToRectangle(GridRangeInfo.Rows(
                this.ListControlPart.grid.TopRowIndex,
            this.ListControlPart.grid.RowCount));
}

Methods

Add(IMouseController)

Registers a mouse controller.

Declaration
public void Add(IMouseController controller)
Parameters
Type Name Description
IMouseController controller

Contains(IMouseController)

Indicates whether a mouse controller has previously been registered.

Declaration
public bool Contains(IMouseController controller)
Parameters
Type Name Description
IMouseController controller
Returns
Type
System.Boolean

Dispose(Boolean)

Resets the dispatcher and calls Dispose for any registered mouse controller and unregisters all mouse controllers.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing
Overrides

Find(String)

Search a mouse controller by comparing with the name returned from IMouseController.Name.

Declaration
public IMouseController Find(string name)
Parameters
Type Name Description
System.String name
Returns
Type
IMouseController

HitTest(Point)

HitTest loops through all controllers and call HitTest on each of them. Only one mouse controller can get voted to receive mouse messages.

Declaration
public int HitTest(Point point)
Parameters
Type Name Description
System.Drawing.Point point

The point in client coordinates to be hit tested.
Returns
Type Description
System.Int32

The result identifying the hit-test context.
Remarks

The current result of the vote gets passed to the next mouse controller. If a controller wants to handle mouse events, it can decide based on the existing vote if it has higher priority for it to handle mouse messages than the existing vote.

HitTest(Point, MouseButtons)

HitTest loops through all controllers and call HitTest on each of them. Only one mouse controller can get voted to receive mouse messages.

Declaration
public int HitTest(Point point, MouseButtons mouseButton)
Parameters
Type Name Description
System.Drawing.Point point

The point in client coordinates to be hit tested.
System.Windows.Forms.MouseButtons mouseButton

The mouse button that is pressed.
Returns
Type Description
System.Int32

The result identifying the hit-test context.

HitTest(Point, MouseButtons, out IMouseController)

HitTest loops through all controllers and call HitTest on each of them. Only one mouse controller can get voted to receive mouse messages.

Declaration
public int HitTest(Point point, MouseButtons mouseButton, out IMouseController controller)
Parameters
Type Name Description
System.Drawing.Point point

The point in client coordinates to be hit tested.
System.Windows.Forms.MouseButtons mouseButton

The mouse button that is pressed.
IMouseController controller

A placeholder where a reference to the winning IMouseController is returned.
Returns
Type Description
System.Int32

The result identifying the hit-test context.

HitTest(Point, MouseButtons, Int32, out IMouseController)

HitTest loops through all controllers and call HitTest on each of them. Only one mouse controller can get voted to receive mouse messages.

Declaration
public int HitTest(Point point, MouseButtons mouseButton, int clicks, out IMouseController controller)
Parameters
Type Name Description
System.Drawing.Point point

The point in client coordinates to be hit tested.
System.Windows.Forms.MouseButtons mouseButton

The mouse button that is pressed.
System.Int32 clicks

1 for single-click; 2 for double click.
IMouseController controller

A placeholder where a reference to the winning IMouseController is returned.
Returns
Type Description
System.Int32

The result identifying the hit-test context.

OnActiveControllerChanged(EventArgs)

Raises the ActiveControllerChanged event.

Declaration
protected virtual void OnActiveControllerChanged(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

A System.EventArgs that contains the event data.

OnTrackMouseChanged(EventArgs)

Raises the TrackMouseChanged event.

Declaration
protected virtual void OnTrackMouseChanged(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

A System.EventArgs that contains the event data.

ProcessCancelMode()

Call this method from your control's CancelMode handler.

Declaration
public void ProcessCancelMode()

ProcessMouseDown(MouseEventArgs)

Call this method from your control MouseDown handler.

Declaration
public void ProcessMouseDown(MouseEventArgs e)
Parameters
Type Name Description
System.Windows.Forms.MouseEventArgs e

ProcessMouseMove(MouseEventArgs)

Call this method from your control's MouseMove handler.

Declaration
public void ProcessMouseMove(MouseEventArgs e)
Parameters
Type Name Description
System.Windows.Forms.MouseEventArgs e

ProcessMouseUp(MouseEventArgs)

Call this method from your control's MouseUp handler.

Declaration
public void ProcessMouseUp(MouseEventArgs e)
Parameters
Type Name Description
System.Windows.Forms.MouseEventArgs e

Remove(IMouseController)

Removes a mouse controller.

Declaration
public void Remove(IMouseController controller)
Parameters
Type Name Description
IMouseController controller

ResetTrackMouse()

Resets support for mouse tracking.

Declaration
public void ResetTrackMouse()
Remarks

Call this method after a user interaction that should switch the control back into normal mouse behavior. For example, when the control gets the focus or when the user clicks a scrollbar.

SetMouseHoverController(IMouseController, EventArgs)

Sets the controller that will receive mouse hovering messages. If the controller is changed, MouseHoverLeave and MouseHoverEnter calls are made.

Declaration
protected void SetMouseHoverController(IMouseController value, EventArgs e)
Parameters
Type Name Description
IMouseController value
System.EventArgs e

ToString()

Declaration
public override string ToString()
Returns
Type
System.String
Overrides
System.Object.ToString()

Events

ActiveControllerChanged

Indicates that the active controller has changed.

Declaration
public event EventHandler ActiveControllerChanged
Event Type
Type
System.EventHandler
Remarks

Active controller is the controller that is receiving MouseDown, MouseMove and MouseUp messages when the user has pressed a mouse button.

TrackMouseChanged

Indicates that the value of the TrackMouse property has changed.

Declaration
public event EventHandler TrackMouseChanged
Event Type
Type
System.EventHandler

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type
System.Collections.IEnumerator

Implements

System.IDisposable
System.Collections.IEnumerable

Extension Methods