Class ToolManager

GoDiagram®
v10.0.8
by Northwoods Software®

This special Tool is responsible for managing all of the Diagram's mode-less tools, which you can access as the ToolManager.

Mode-less tools are tools that are present in one of the following lists: MouseDownTools, MouseMoveTools, or MouseUpTools. This ToolManager tool is normally the DefaultTool, so it is also usually the CurrentTool when the user is doing "nothing".

Inheritance
ToolManager
Namespace: Northwoods.Go.Tools
Assembly: Northwoods.GoDiagram.WinForms.dll
Syntax
public class ToolManager : Tool
Remarks

When this tool is running as the current tool, it handles mouse-down, mouse-move, and mouse-up events and the corresponding touch events. For each event it iterates over each of the tools in the corresponding list, calling the tool's CanStart() predicate. If that predicate returns true, it starts that tool by making it the diagram's current tool. It then activates the tool and passes on the event to the tool by calling the corresponding method (either DoMouseDown(), DoMouseMove(), or DoMouseUp()).

Because this tool is typically the one running as the diagram's current tool when the user isn't "doing" anything, this tool can also handle other events, such as mouse wheel events and keyboard commands.

Keyboard events are just passed on to the CommandHandler's DoKeyDown() or DoKeyUp() method.

This tool also is responsible for showing tooltips. Tooltip Adornments may be declared as any ToolTip, or as the ToolTip if the mouse or finger remains motionless in the background of the diagram. You can set ToolTipDuration to control how long the tooltip remains visible after being motionless.

This tool does not utilize any tool handles. This tool does not conduct any transactions. But of course some of the tools that the ToolManager starts can show tool handles and/or conduct their own transactions.

Constructors

ToolManager()

You do not normally need to create an instance of this tool because one already exists as the ToolManager, which you can modify.

The Name of this tool is "ToolManager".

Declaration
public ToolManager()
Remarks

The constructor produces a ToolManager that manages no tools. Call InitializeStandardTools() to create various tools, initialize the tool properties such as DraggingTool, and initialize the three mouse tool lists with those newly created tools.

Properties

ActionTool

Gets or sets the mode-less ActionTool, normally one of the MouseDownTools.

Declaration
public ActionTool ActionTool { get; set; }
Property Value
Type Description
ActionTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

ClickCreatingTool

Gets or sets the mode-less ClickCreatingTool, normally one of the MouseUpTools.

Declaration
public ClickCreatingTool ClickCreatingTool { get; set; }
Property Value
Type Description
ClickCreatingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

ClickSelectingTool

Gets or sets the mode-less ClickSelectingTool, normally one of the MouseUpTools.

Declaration
public ClickSelectingTool ClickSelectingTool { get; set; }
Property Value
Type Description
ClickSelectingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

ContextMenuTool

Gets or sets the mode-less ContextMenuTool, normally one of the MouseUpTools.

Declaration
public ContextMenuTool ContextMenuTool { get; set; }
Property Value
Type Description
ContextMenuTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

CurrentToolTip

This read-only property returns the currently showing tooltip, or null if there is none.

Declaration
public IShowHidable CurrentToolTip { get; }
Property Value
Type Description
IShowHidable

DraggingTool

Gets or sets the mode-less DraggingTool, normally one of the MouseMoveTools.

Declaration
public DraggingTool DraggingTool { get; set; }
Property Value
Type Description
DraggingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

DragSelectingTool

Gets or sets the mode-less DragSelectingTool, normally one of the MouseMoveTools.

Declaration
public DragSelectingTool DragSelectingTool { get; set; }
Property Value
Type Description
DragSelectingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

DragSize

Gets or sets the distance in view coordinates within which a mouse down-and-up is considered a click and beyond which a mouse movement is considered a drag.

Declaration
public Size DragSize { get; set; }
Property Value
Type Description
Size
Remarks

The default value is 2 pixels horizontally and vertically for mouse events, and increases by 6 pixels for touch events. This value is used by IsBeyondDragSize(Point?, Point?).

GestureBehavior

Gets or sets the ToolManager's touch pinching behavior. Allowed values are Zoom and Cancel and None.

Declaration
public GestureMode GestureBehavior { get; set; }
Property Value
Type Description
GestureMode
Remarks

The default value is Zoom.

If you want to control whether a single finger touch movement causes a pan (i.e. scroll) of the diagram's contents or scrolls the page, consider either disabling the PanningTool by setting its property IsEnabled to false or by setting Bubbles to true.

HoldDelay

Gets or sets the time between when the mouse stops moving and a hold event, in milliseconds.

Declaration
public double HoldDelay { get; set; }
Property Value
Type Description
double
Remarks

The default value is 850 milliseconds.

HoverDelay

Gets or sets the time between when the mouse stops moving and a hover event, in milliseconds.

Declaration
public double HoverDelay { get; set; }
Property Value
Type Description
double
Remarks

This value affects the delay before ToolTips are shown.

The default value is 850 milliseconds.

Set ToolTipDuration to control how long a tooltip will remain visible.

LinkingTool

Gets or sets the mode-less LinkingTool, normally one of the MouseMoveTools.

Declaration
public LinkingTool LinkingTool { get; set; }
Property Value
Type Description
LinkingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

LinkReshapingTool

Gets or sets the mode-less LinkReshapingTool, normally one of the MouseDownTools.

Declaration
public LinkReshapingTool LinkReshapingTool { get; set; }
Property Value
Type Description
LinkReshapingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

MouseDownTools

This read-only property returns the list of Tools that might be started upon a mouse or finger press event.

Declaration
public IList<Tool> MouseDownTools { get; }
Property Value
Type Description
IList<Tool>
Remarks

When the ToolManager handles a mouse-down or touch-down event in DoMouseDown(), it searches this list in order, starting the first tool for which CanStart() returns true.

This list may be modified, but it must not be modified while any tool is handling events.

InitializeStandardTools() installs the following tools, in order:

MouseMoveTools

This read-only property returns the list of Tools that might be started upon a mouse or finger move event.

Declaration
public IList<Tool> MouseMoveTools { get; }
Property Value
Type Description
IList<Tool>
Remarks

When the ToolManager handles a mouse-move or touch-move event in DoMouseMove(), it searches this list in order, starting the first tool for which CanStart() returns true.

This list may be modified, but it must not be modified while any tool is handling events.

InitializeStandardTools() installs the following tools, in order:

MouseUpTools

This read-only property returns the list of Tools that might be started upon a mouse or finger up event.

Declaration
public IList<Tool> MouseUpTools { get; }
Property Value
Type Description
IList<Tool>
Remarks

When the ToolManager handles a mouse-up or touch-up event in DoMouseUp(), it searches this list in order, starting the first tool for which CanStart() returns true.

This list may be modified, but it must not be modified while any tool is handling events.

InitializeStandardTools() installs the following tools, in order:

MouseWheelBehavior

Gets or sets the ToolManager's mouse wheel behavior. Allowed values are Scroll and Zoom and WheelNone.

Declaration
public WheelMode MouseWheelBehavior { get; set; }
Property Value
Type Description
WheelMode
Remarks

The default value is Scroll.

PanningTool

Gets or sets the mode-less PanningTool, normally one of the MouseMoveTools.

Declaration
public PanningTool PanningTool { get; set; }
Property Value
Type Description
PanningTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

RelinkingTool

Gets or sets the mode-less RelinkingTool, normally one of the MouseDownTools.

Declaration
public RelinkingTool RelinkingTool { get; set; }
Property Value
Type Description
RelinkingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

ResizingTool

Gets or sets the mode-less ResizingTool, normally one of the MouseDownTools.

Declaration
public ResizingTool ResizingTool { get; set; }
Property Value
Type Description
ResizingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

RotatingTool

Gets or sets the mode-less RotatingTool, normally one of the MouseDownTools.

Declaration
public RotatingTool RotatingTool { get; set; }
Property Value
Type Description
RotatingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

TextEditingTool

Gets or sets the mode-less TextEditingTool, normally one of the MouseUpTools.

Declaration
public TextEditingTool TextEditingTool { get; set; }
Property Value
Type Description
TextEditingTool
Remarks

You can disable this tool by setting its IsEnabled property to false.

ToolTipDuration

Gets or sets how long a tool tip is visible.

Declaration
public double ToolTipDuration { get; set; }
Property Value
Type Description
double
Remarks

The default value is 5000 milliseconds.

This is used by ShowToolTip(IShowHidable, GraphObject) to determine how long to wait before calling HideToolTip().

Set HoverDelay to control how long the mouse should stay stationary before it shows a tooltip.

Methods

DoKeyDown()

This just calls DoKeyDown() on the diagram's CommandHandler.

Declaration
public override void DoKeyDown()
Overrides
Remarks

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoKeyUp()

This just calls DoKeyUp() on the diagram's CommandHandler.

Declaration
public override void DoKeyUp()
Overrides
Remarks

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseDown()

Iterate over the MouseDownTools list and start the first tool for which its CanStart() predicate returns true.

Declaration
public override void DoMouseDown()
Overrides
Remarks

Starting a tool replaces the CurrentTool with the new tool. Successfully doing so also activates the new tool by calling DoActivate() and passes on the mouse-down event to it by calling DoMouseDown().

Not finding any startable tools causes this tool manager to activate, thereby enabling the mouse-move and mouse-up behaviors and starts detection of a mouse-hold event after HoldDelay milliseconds.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseHover()

Implement the standard behavior for mouse hover and mouse hold events, called by DoWaitAfter(InputEvent) when the mouse has not moved for a period of time.

Declaration
public virtual void DoMouseHover()
Remarks

If there has been no mouse down, the timer is set for HoverDelay milliseconds. If it executes, it calls any MouseHover function on the object at the mouse or on any of its containing panels, or it calls any MouseHover function for a background mouse-hover event.

If there had been a mouse down, the timer is set for HoldDelay milliseconds. If it executes, it calls any MouseHold function on the object at the mouse or on any of its containing panels, or it calls any MouseHold function for a background mouse-held-down event.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseMove()

Iterate over the MouseMoveTools list and start the first tool for which its CanStart() predicate returns true.

Declaration
public override void DoMouseMove()
Overrides
Remarks

Starting a tool replaces the CurrentTool with the new tool. Successfully doing so also activates the new tool by calling DoActivate() and passes on the mouse-move event to it by calling DoMouseMove().

If no tool is found and activated, this:

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseUp()

Iterate over the MouseUpTools list and start the first tool for which its CanStart() predicate returns true.

Declaration
public override void DoMouseUp()
Overrides
Remarks

Starting a tool replaces the CurrentTool with the new tool. Successfully doing so also activates the new tool by calling DoActivate() and passes on the mouse-up event to it by calling DoMouseUp().

If no startable tool is found it deactivates this tool manager, to get ready for a mouse-down and ignore mouse-move and mouse-up events.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoMouseWheel()

The diagram will call this method as the mouse wheel is rotated.

Declaration
public override void DoMouseWheel()
Overrides
Remarks

By default this just calls StandardMouseWheel(). This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoToolTip()

Implement the standard behavior for tooltips, called by DoWaitAfter(InputEvent) when the mouse has not moved for a period of time.

Declaration
public virtual void DoToolTip()
Remarks

This looks for a GraphObject at the latest mouse point. If it finds an object, it checks for a ToolTip. If it has none, this method searches up the visual tree for a containing Panel that does have a tooltip.

If it didn't find any object, this looks for a ToolTip.

If it eventually finds a tooltip, this calls ShowToolTip(IShowHidable, GraphObject). Otherwise this calls HideToolTip().

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

DoWaitAfter(InputEvent)

Implement the standard behavior for when the mouse has not moved for a period of time. This is due to an expired timer started by calling StandardWaitAfter(double, InputEvent).

Declaration
public override void DoWaitAfter(InputEvent ievent)
Parameters
Type Name Description
InputEvent ievent

The input event that caused StandardWaitAfter(double, InputEvent). In this override, if it is a touch input event and the LastInput is not handled (Handled set to false), then this method will simulate a right click.

Overrides
Remarks

This calls DoMouseHover() and, if not mouse-down, DoToolTip(). Afterwards, if the event that called StandardWaitAfter(double, InputEvent) was a touch event, this simulates a right click, enabling context menu functionality and other actions on touch devices.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

FindTool(string)

Find a mouse tool of a given name.

Declaration
public virtual Tool FindTool(string name)
Parameters
Type Name Description
string name

the type of tool, such as "Dragging" or "ClickSelecting".

Returns
Type Description
Tool

a Tool whose Name exactly matches the given name, or null if no such tool is found in any of the three lists.

Remarks

This searches the MouseDownTools, MouseMoveTools, and MouseUpTools lists.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

HideToolTip()

Hide any tooltip.

Declaration
public virtual void HideToolTip()
Remarks

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

InitializeStandardTools()

Initialize the three mouse tool lists with instances of the standard tools.

Declaration
public virtual void InitializeStandardTools()
Remarks

This adds new instances of tools to the following three mouse tool lists: MouseDownTools, MouseMoveTools, or MouseUpTools. This also sets the various tool properties of this ToolManager to those newly created tools. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

PositionToolTip(Adornment, GraphObject)

This is called by ShowToolTip(IShowHidable, GraphObject) to position the part within the viewport.

Declaration
public virtual void PositionToolTip(Adornment tooltip, GraphObject obj)
Parameters
Type Name Description
Adornment tooltip
GraphObject obj

The GraphObject getting the tooltip, or null if the tooltip is for the diagram background.

Remarks

It normally goes just below the cursor. But if the mouse is too close to the right edge or the bottom edge of the viewport, it is positioned left and/or above the cursor.

This method only operates if the tooltip, an Adornment, does not have a Placeholder. When there is a Placeholder in the tooltip, that Adornment is automatically positioned so that the Placeholder is positioned at the adorned object, the second argument to this method.

This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

If you override this method to position the tooltip, the tooltip has already been measured but not arranged, so you can use its MeasuredBounds width and height but not its ActualBounds.

ReplaceTool(string, Tool)

Replace a mouse tool of a given name with a new tool, or remove an existing tool (if the newtool is null).

Declaration
public virtual Tool ReplaceTool(string name, Tool newtool)
Parameters
Type Name Description
string name

the type of tool, such as "Dragging" or "ClickSelecting".

Tool newtool

If null, any tool that the search finds will just be removed from the list in which it was found.

Returns
Type Description
Tool

the old tool that was replaced by the new one; this is null if none was found and the new tool was not added to any mouse tool list

Remarks

This searches the MouseDownTools, MouseMoveTools, and MouseUpTools lists. The new tool is inserted into the same list in which the same-named tool is found, at the same position as the old tool. However, if no existing tool with the given name is present, this does not add the new tool to any list, since it cannot know where it should be added.

Please read the Introduction page on Extensions for how to override methods and how to call this base method.

ShowToolTip(IShowHidable, GraphObject)

Show a tooltip. This is called by DoToolTip() once that method has found a tooltip to display.

Declaration
public virtual void ShowToolTip(IShowHidable tooltip, GraphObject obj)
Parameters
Type Name Description
IShowHidable tooltip
GraphObject obj

The GraphObject getting the tooltip; this is null if the tooltip is being shown for the diagram background.

Remarks

This calls PositionToolTip(Adornment, GraphObject) to make it easier to customize how the tooltip is positioned relative to the object with the tooltip.

This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Introduction page on Extensions for how to override methods and how to call this base method.