Class RotatingTool

GoDiagram®
v10.0.8
by Northwoods Software®

The RotatingTool is used to interactively change the Angle of a GraphObject by setting its Angle property. You may want to save the angle to the model by using a TwoWay Binding on the "Angle" property of the GraphObject that is named by RotateElementName.

Inheritance

object

Tool

RotatingTool

RotateMultipleTool

Namespace: Northwoods.Go.Tools

Assembly: Northwoods.GoDiagram.WinForms.dll

Syntax

public class RotatingTool : Tool

Remarks

This tool allows the user to rotate the RotateElement of the selected Part. The Part must be Rotatable, which is false by default. Normally this works with Parts or Nodes; it does not make sense for whole Links or Paths, so if you want to rotate a label on a Link, make sure to name that label and refer to it as the RotateElementName.

You can control the point about which the object is rotated by setting RotationSpot. The rotation spot can be computed dynamically by overriding ComputeRotationPoint(GraphObject). The value of that method call is saved as RotationPoint.

You can limit the permitted angles by setting SnapAngleMultiple and SnapAngleEpsilon. For example, if you want to permit only angles that are multiples of 90 degrees, set SnapAngleMultiple to 90 and SnapAngleEpsilon to 45. Pressing the Shift key during rotation ignores these two properties.

This tool makes use of an Adornment that includes a rotation handle. It is shown when the selected Part is Rotatable. You can control its direction relative to the RotationPoint by setting HandleAngle to a multiple of 90 degrees, and its distance from the rotation point by setting HandleDistance. The rotate handle is normally a copy of HandleArchetype. unless you specify a custom rotate Adornment by setting RotateAdornmentTemplate.

This tool conducts a transaction while the tool is active. A successful rotation will result in a "PartRotated" DiagramEvent and a "Rotating" transaction.

For customizing the RotatingTool, see Introduction to the RotatingTool.

If you want to programmatically start a user's rotating of the RotateElement of an existing selected node, you can set the Handle property to the rotate handle and then start and activate the tool.

var node = ...;
myDiagram.Select(node);
var adorn = node.FindAdornment("Rotating");
var tool = myDiagram.ToolManager.RotatingTool;
// specify the rotation handle of the "Rotating" Adornment of the selected node
tool.Handle = adorn.Elt(0);
myDiagram.CurrentTool = tool;  // starts the RotatingTool
tool.DoActivate();             // activates the RotatingTool

Constructors

RotatingTool()

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

The Name of this tool is "Rotating".

Declaration

public RotatingTool()

Properties

AdornedElement

Gets the GraphObject that is being rotated.

Declaration

public GraphObject AdornedElement { get; set; }

Property Value

Type	Description
GraphObject

Remarks

This may be the same element as the selected Part or it may be contained within that Part.

This property is also settable, but should only be set when overriding functions in RotatingTool, and not during normal operation.

Handle

This read-only property returns the GraphObject that is the tool handle being dragged by the user.

Declaration

public GraphObject Handle { get; set; }

Property Value

Type	Description
GraphObject

Remarks

This will be contained by an Adornment whose category is "RotatingTool". Its AdornedElement is the same as the AdornedElement.

This property is also settable, but should only be set either within an override of DoActivate() or prior to calling DoActivate().

HandleAngle

Gets or sets the spot to locate the Adornment for the rotation handle when it does not have a Placeholder.

Declaration

public double HandleAngle { get; set; }

Property Value

Type	Description
double

Remarks

This assumes the Adornment's location will be at the center of the rotation handle.

By default this is zero degrees, which locates the Adornment so that it is placed to the right of an un-rotated object. You can set this to a multiple of 90 degrees to position the rotation handle differently with respect to the RotationPoint.

HandleArchetype

Gets or sets a small GraphObject that is copied as a rotation handle for the selected part.

Declaration

public GraphObject HandleArchetype { get; set; }

Property Value

Type	Description
GraphObject

Remarks

By default this is a Shape that is a small yellow circle. Setting this property does not raise any events.

Here is an example of changing the default handle to be green "X":

myDiagram.ToolManager.RotatingTool.HandleArchetype =
  new Shape("XLine") { Width = 8, Height = 8, Stroke = "green", Fill = "transparent" };

This property is ignored when a custom rotating Adornment is specified as the RotateAdornmentTemplate.

HandleDistance

Gets or sets the spot to locate the Adornment at a particular distance from the AdornedElement.

Declaration

public double HandleDistance { get; set; }

Property Value

Type	Description
double

Remarks

This assumes the Adornment's location will be at the center of the rotation handle.

By default this is 50, which locates the Adornment so that it is placed to the right of an un-rotated object.

OriginalAngle

This read-only property returns the angle that was the original value of the Angle of the GraphObject that is being rotated.

Declaration

public double OriginalAngle { get; }

Property Value

Type	Description
double

Remarks

The value is invalid when this tool is not active.

RotationPoint

Gets or sets the Point at which the axis of the rotation should be.

Declaration

public Point RotationPoint { get; set; }

Property Value

Type	Description
Point

Remarks

DoActivate() saves here the value returned by the call to ComputeRotationPoint(GraphObject). The value is invalid when this tool is not active.

SnapAngleEpsilon

Gets or sets the the closeness to a desired angle at which the angle is "snapped to".

Declaration

public double SnapAngleEpsilon { get; set; }

Property Value

Type	Description
double

Remarks

The default value is 2 degrees, meaning that any angle within 2 degrees of a multiple of the SnapAngleMultiple automatically snaps to that multiple. Values are limited to half of the SnapAngleMultiple; such values restrict user selected angles only to exact multiples of SnapAngleMultiple -- no other angles between them. Setting this property does not raise any events.

SnapAngleMultiple

Gets or sets the preferred angles for the selected object.

Declaration

public double SnapAngleMultiple { get; set; }

Property Value

Type	Description
double

Remarks

The default value is 45 degrees, meaning that angles that are multiples of 45 degrees are automatically preferred, if the actual angle is close to that multiple. The closeness is determined by the SnapAngleEpsilon property. A value of zero for SnapAngleMultiple results in no snapping at all. Setting this property does not raise any events.

Methods

CanStart()

This tool may run when there is a mouse-down event on a rotate handle, the diagram is not read-only and it allows rotation, the left mouse button is being used, and this tool's adornment's rotate handle is at the current mouse point.

Declaration

public override bool CanStart()

Returns

Type	Description
bool

Overrides

Tool.CanStart()

Remarks

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

ComputeRotate(Point)

Compute the new angle given a point.

Declaration

public virtual double ComputeRotate(Point newPoint)

Parameters

Type	Name	Description
Point	newPoint	in document coordinates.

Returns

Type	Description
double	the new angle, in degrees.

Remarks

If the Shift key is pressed, this method ignores the SnapAngleMultiple and SnapAngleEpsilon.

If the angle is close (by SnapAngleEpsilon degrees) to a multiple of SnapAngleMultiple degrees, make it exactly that multiple.

This method is called by both DoMouseMove() and DoMouseUp().

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

ComputeRotationPoint(GraphObject)

Compute the Point about which things should rotate.

Declaration

public Point ComputeRotationPoint(GraphObject obj)

Parameters

Type	Name	Description
GraphObject	obj	the RotateElement

Returns

Type	Description
Point

Remarks

This is called when this tool is activated and sometimes when updating the Adornment. The value of the call is remembered as RotationPoint.

DoActivate()

Capture the mouse, remember the original Angle, and start a transaction.

Declaration

public override void DoActivate()

Overrides

Tool.DoActivate()

Remarks

Normally when this method is called the value of Handle will be null, resulting in a call to FindToolHandleAt(Point, string) to find a "Rotating" tool handle, which is then remembered as the value of Handle. If when this method is called the value of Handle is already set, then there is no need to call FindToolHandleAt(Point, string), because the programmer has already set up which rotate handle they want the user to be rotating.

DoCancel()

Restore the original Angle of the adorned object.

Declaration

public override void DoCancel()

Overrides

Tool.DoCancel()

DoDeactivate()

Stop the current transaction, forget the Handle and AdornedElement, and release the mouse.

Declaration

public override void DoDeactivate()

Overrides

Tool.DoDeactivate()

DoMouseMove()

Call Rotate(double) with a new angle determined by the current mouse point.

Declaration

public override void DoMouseMove()

Overrides

Tool.DoMouseMove()

Remarks

This determines the new angle by calling ComputeRotate(Point).

DoMouseUp()

Call Rotate(double) with an angle based on the most recent mouse point, commit the transaction, and raise the "PartRotated" DiagramEvent.

Declaration

public override void DoMouseUp()

Overrides

Tool.DoMouseUp()

Rotate(double)

Change the angle of the selected part's RotateElement.

Declaration

public virtual void Rotate(double newangle)

Parameters

Type	Name	Description
double	newangle	in degrees.

Remarks

This modifies its Angle.

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

StopTransaction()

This calls the base StopTransaction() method, and if the result is true, attempts to optimize the transaction by removing all changes except the first and last by calling Optimize().

Declaration

public override bool StopTransaction()

Returns

Type	Description
bool	the result of the call to rollback or commit the transaction.

Overrides

Tool.StopTransaction()

Remarks

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

UpdateAdornments(Part)

Show an Adornment with a rotate handle at a point to the side of the adorned object if the part is selected and visible and if CanRotate()() is true.

Declaration

public override void UpdateAdornments(Part part)

Parameters

Type	Name	Description
Part	part

Overrides

Tool.UpdateAdornments(Part)

Remarks

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