### Hierarchy

- Tool
  - RotatingTool
    - RotateMultipleTool
    - SpotRotatingTool

The RotatingTool is used to interactively change the GraphObject.angle of a GraphObject by setting its GraphObject.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 Part.rotateObjectName.

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

You can control the point about which the object is rotated by setting Part.rotationSpot. The rotation spot can be computed dynamically by overriding computeRotationPoint. 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 Part.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 RotatingTool.handleArchetype. unless you specify a custom rotate Adornment by setting Part.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 Part.rotateObject 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

## Index

### Constructors

- constructor

### Properties

- adornedObject
- handle
- handleAngle
- handleArchetype
- handleDistance
- originalAngle
- rotationPoint
- snapAngleEpsilon
- snapAngleMultiple

### Methods

- canStart
- computeRotate
- computeRotationPoint
- doActivate
- doCancel
- doDeactivate
- doMouseMove
- doMouseUp
- rotate
- updateAdornments

## Constructors

### constructor

- new RotatingTool(): RotatingTool

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

  The Tool.name of this tool is "Rotating".

  #### Returns RotatingTool

## Properties

### adornedObject : GraphObject

- Gets the GraphObject that is being rotated. This may be the same object 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 : GraphObject

- This read-only property returns the GraphObject that is the tool handle being dragged by the user. This will be contained by an Adornment whose category is "RotatingTool". Its Adornment.adornedObject is the same as the adornedObject.

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

### handleAngle : number

- Gets or sets the spot to locate the Adornment for the rotation handle when it does not have a Placeholder. 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.

  since

    2.0

### handleArchetype : GraphObject

- Gets or sets a small GraphObject that is copied as a rotation handle for the selected part. 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 =
          $(go.Shape, "XLine",
            { width: 8, height: 8, stroke: "green", fill: "transparent" });

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

### handleDistance : number

- Gets or sets the spot to locate the Adornment at a particular distance from the adornedObject. 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.

  since

    2.0

### Read-only originalAngle : number

- This read-only property returns the angle that was the original value of the GraphObject.angle of the GraphObject that is being rotated. The value is invalid when this tool is not active.

  since

    1.1

### rotationPoint : Point

- Gets or sets the Point at which the axis of the rotation should be. doActivate saves here the value returned by the call to computeRotationPoint. The value is invalid when this tool is not active.

  since

    2.0

### snapAngleEpsilon : number

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

  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 : number

- Gets or sets the preferred angles for the selected object.

  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

### Override Virtual canStart

- canStart(): boolean

- 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.

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

  #### Returns boolean

### Virtual computeRotate

- computeRotate(newPoint: Point): number

- Compute the new angle given a point. 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.

  #### Parameters

  - ##### newPoint: Point

    in document coordinates.

  #### Returns number

  the new angle, in degrees.

### Virtual computeRotationPoint

- computeRotationPoint(obj: GraphObject): Point

- Compute the Point about which things should rotate. This is called when this tool is activated and sometimes when updating the Adornment. The value of the call is remembered as rotationPoint.

  #### Parameters

  - ##### obj: GraphObject

    the Part.rotateObject

  #### Returns Point

### Override doActivate

- doActivate(): void

- Capture the mouse, remember the original GraphObject.angle, and start a transaction.

  Normally when this method is called the value of handle will be null, resulting in a call to Tool.findToolHandleAt 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 Tool.findToolHandleAt, because the programmer has already set up which rotate handle they want the user to be rotating.

  #### Returns void

### Override doCancel

- doCancel(): void

- Restore the original GraphObject.angle of the adorned object.

  #### Returns void

### Override doDeactivate

- doDeactivate(): void

- Stop the current transaction, forget the handle and adornedObject, and release the mouse.

  #### Returns void

### Override doMouseMove

- doMouseMove(): void

- Call rotate with a new angle determined by the current mouse point. This determines the new angle by calling computeRotate.

  #### Returns void

### Override doMouseUp

- doMouseUp(): void

- Call rotate with an angle based on the most recent mouse point, commit the transaction, and raise the "PartRotated" DiagramEvent.

  #### Returns void

### Virtual rotate

- rotate(newangle: number): void

- Change the angle of the selected part's Part.rotateObject. This modifies its GraphObject.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.

  #### Parameters

  - ##### newangle: number

    in degrees.

  #### Returns void

### Override Virtual updateAdornments

- updateAdornments(part: Part): void

- 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 Part.canRotate() is true.

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

  #### Parameters

  - ##### part: Part

    the part.

  #### Returns void

Copyright © 1998-2021 by Northwoods Software Corporation.