Free rotate mode for selected objects.

(c) TIG 2010-2013
Permission to use, copy, modify, and distribute this software for
any purpose and without fee is hereby granted, provided that the above
copyright notice appear in all copies.
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

FreeRotate.rb >>> Plugins Folder

Usage:

Make a Selection.
Pick Menu > Plugins > Free Rotate
or type freerotate into Ruby Console
or click on Toolbar 'Free Rotate' [activated from View > Toolbars].
The Selection can consist of any entities - it is temporarily Grouped
during the Rotation.

You are then prompted to pick the 'Pivot' point.
Pick a point ]OR to set the Pivot-Point at the center of the Selection's
bounding-box press the Ctrl-key].
The Pivot-Point is marked with a Black dot.

You are next prompted to pick the 'Axis' point.
A line is drawn from the Pivot-Point as you move the cursor.
Normal inferencing applies.
Pick a point [OR if the Pivot is not the Selection's bounding-box center you
can set the Axis-Point at the center of the Selection's bounding-box by
pressing the Ctrl-key].
The Axis-Point is now marked with a Magenta dot.

Now a temporary gizmo 'globe' appears, centered on the Pivot-Point
with its North-Pole set vertically up.
You can snap to it OR any other object in the model.
As you move the cursor the Selection will Free-Rotate so that the Axis-Point
always points towards the cursor position.

The tool always starts in 'Free-Rotate' mode but you can toggle it to be in
'Axial-Rotate' mode at any stage by pressing the 'Tab' key - it's probably
easist to do this before picking the first two points.
'Tab' toggles between these two modes.
The 'Constrained' Axial-Rotate mode rotates the Selection around the Axis.
If you haven't already set the Pivot and/or Axis points before you go into
this mode you will be prompted to do so first.
In this mode the gizmo becomes a 'disk', centered on the Pivot-Point,
with its normal along the Axis.
You can snap to it or any other object in the model.
You are first prompted to pick a 'Handle' point.
Then pick a 'Snap' point - as you move the cursor the Selection will Rotate
around the Axis following the cursor.
Alternatively once the 'disk' has appeared you can type in an Angle into
the VCB in degrees [-/+ve note that positive angles are counterclockwise]
at any time when in the Axial-Rotate mode.
When you pick the Snap-Point or press for the entered Angle the
Selection with pause at that Rotation.
After typing an Angle you will need to re-pick a Handle-Point if you want to
then Axial-Rotate by picked points.
However, you can continue typing in other Angles [which are taken as relative
to the current postion] as desired.

Im either mode you can the press Enter or Double-Click to Confirm.

In either mode Esc will Exit the tool and Undo any changes.
Also in either mode if you start to use another Tool any changes are Undone.

The VCB-text gives you the current Mode and its Options...

TO RECAP...

Make a Selection

Start the Tool...

Optionally use 'Tab' to toggle between 'Free-Rotate' and 'Axial-Rotate'.

Pick-1 = Pivot-Point
Pick-2 = Axis-Point

Next...

When in 'Free-Rotate' mode [globe-gizmo]:-

Tab='Axial-Rotate'

LeftClick/Enter/DoubleClick=Confirm
i.e. Use the current Rotation and Exit the tool.

Esc/Exit=Cancel
i.e. to Abort and Undo all changes at any stage...
an 'Exit' occurs when you start to use another Tool.

When in 'Axial-Rotate' mode [disk-gizmo]:-

Tab='Free-Rotate'

Pick-3=Handle-Point
OR
Type 'Angle' +

Pick-4=Snap-Point
OR
Type 'Angle' +

If desired continue repeating Pick-3 & Pick-4 OR Type new 'Angle' etc...

Enter/Double_Click=Confirm
i.e. Use the current Rotation and Exit the tool.

Esc/Exit=Cancel
i.e. to Abort and Undo all changes at any stage...
an 'Exit' occurs when you start to use another Tool.

When the tool 'exits' the Selection is ungrouped and remains highlighted.
The changes will 'Undo' in one step.

1.1 20100825 First release.
1.2 20100826 Bug in empty selection trapped.
1.3 20100826 Encompassing 'globe' added.
2.0 20100828 New Ctrl/Alt/Tab Options for suspending & changing Pivot/Axes.
2.1 20100828 Glitch with Cursor colors during 'Tab' Options fixed.
Changed the Options to DownArrow/Ctrl/Tab: 'Alt' is plain flaky!
2.2 20100828 Globe defaults to 150% of selections bounds.
Tab-options rationalized.
2.3 20100829 Guide line added from Pivot to Axis Cursor during Tab-Option.
3.0 20109015 New 'Up-Arrow' option to rotate constrained around Axis added.
4.0 20100922 Radical overhaul of how the tool operates - see the notes...
FreeRotate Toolbar added, and Zip file with FreeRotate folder.
4.1 20100922 Typo fixed with Axis on XAXIS glitch.
'Tab' press for MAC key code adjusted to 9, 15 and 48.
Menu 'Windows > Instructor' help added...
[This is not working - open ../FreeRotate/index.html in your
web-browser till this is fixed...]
4.2 20100923 Glitch with 'Tab' [9] on MAC etc trapped with key-up not key-down.
4.3 20100927 Typo in code corrected in line#708: was not affecting results.
Gizmo Guides are displayed even when Guides are 'off' in Style.
4.4 20110307 Instructor now works.
4.5 20131210 Future-proofed.