TransformManager (AS3) – Interactively Scale/Rotate/Move DisplayObjects

• Version: 1.881, Updated 2010-03-07
• Compatibility: Flash Player 9 and later (ActionScript 3.0)

Description

TransformManager makes it easy to add interactive scaling/rotating/moving of DisplayObjects to your Flash or Flex application. It uses an intuitive interaction style that's similar to most modern drawing applications. When the user clicks on a managed DisplayObject, a selection box will be drawn around it along with 8 handles for scaling/rotating. When the mouse is placed just outside of any of the scaling handles, the cursor will change to indicate that they're in rotation mode. Just like most other applications, the user can hold down the SHIFT key to select multiple items, to constrain scaling proportions, or to limit the rotation to 45 degree increments.

(To see a Flex Example, click here.)

Features

• Select multiple items and scale/rotate/move them all simultaneously.
• Includes a "FlexTransformManager" class that makes it simple to integrate into Flex applications.
• Perform virtually any action (transformations, selections, etc.) through code.
• Depth management which allows you to programmatically push the selected items forward or backward in the stacking order
• Optionally set minScaleX, maxScaleX, minScaleY, and maxScaleY properties on each item
• Arrow keys move the selection (optional)
• You can set the scaleMode of any TransformItem to SCALE_WIDTH_AND_HEIGHT so that the width/height properties are altered instead of scaleX/scaleY. This can be helpful for text-related components because altering the width/height changes only the container's dimensions while retaining the text's size.
• There is a 10-pixel wide draggable edge around around the border that users can drag. This is particularly helpful with TextFields/TextAreas.
• Define bounds within which the DisplayObjects must stay, and TransformManager will not let the user scale/rotate/move them beyond those bounds
• Automatically bring the selected item(s) to the front in the stacking order
• The DELETE and BACKSPACE keys can be used to delete the selected DisplayObjects
• Lock certain kinds of transformations like rotation, scale, and/or movement
• Lock the proportions of the DisplayObjects so that users cannot distort them when scaling
• Scale from the DisplayObject's center or from its corners
• Listen for Events like SCALE, MOVE, ROTATE, SELECTION_CHANGE, DEPTH_CHANGE, CLICK_OFF, FINISH_INTERACTIVE_MOVE, FINISH_INTERACTIVE_SCALE, FINISH_INTERACTIVE_ROTATE, DOUBLE_CLICK, and DESTROY
• Set the selection box line color and handle thickness
• Cursor will automatically change to indicate scale or rotation mode
• Export transformational data for each item's scale, rotation, and position as well as the TranformManager's settings in XML format so that you can easily save it to a database (or wherever). Then apply it anytime to revert objects to a particular state.
• Optionally hide the center handle
• VERY easy to use. In fact, all it takes is one line of code to get it up and running with the default settings.

Notes / Limitations

• All DisplayObjects that are managed by a particular TransformManager instance must have the same parent (you can create multiple TransformManager instances if you want).
• Objects with their scaleMode set to SCALE_WIDTH_AND_HEIGHT (like TextFields) cannot be flipped (have negative scales), nor can they be skewed. Therefore, when one is part of a multi-selection, scaling will be disabled because it could skew the object (imagine if a TextField is at a 45 degree angle, and then you selected another item and scaled vertically - your TextField would end up getting skewed).
• Due to several bugs in the Flex framework (acknowledged by Adobe), TransformManager cannot accommodate scrollbars in its container, nor can TextFields be scaled disproportionately and scaleX/scaleY/width/height properties don't always report properly after updates are made with TransformManager (again, these are bugs in the Flex framework, NOT TransformManager). However, I created a "FlexTransformManager" class that extends Canvas and makes it easy to integrate into Flex applications. Just beware that the DisplayObjects in the FlexTransformManager will be contained within the bounds of the FlexTransformManager.
• Due to a limitation in the way Flash reports bounds, items that are extremely close or exactly on top of a boundary (if you define bounds) will be moved about 0.1 pixel away from the boundary when you select them. If an item fills the width and/or height of the bounds, it will be scaled down very slightly (about 0.2 pixels total) to move it away from the bounds and allow accurate collision detection.

As always, there's a 30-day money-back guarantee included. If you don't like the class and would prefer to forfeit your license and get a refund within 30 days, no problem.

Other links: License | Forums | AS2 version (NOT identical feature set)

Documentation

Click here for full ASDoc documentation

Important properties

• constrainScale : Boolean To constrain items to only scaling proportionally, set this to true [default:false]
• scaleFromCenter : Boolean To force all items to use the center of the selection as the origin for scaling, set this to true [default:false]
• lockScale : Boolean Prevents scaling [default:false]
• lockRotation : Boolean Prevents rotating [default:false]
• lockPosition : Boolean Prevents moving [default:false]
• arrowKeysMove : Boolean When true, the arrow keys on the keyboard move the selected items when pressed [default: false]
• autoDeselect : Boolean When the user clicks anywhere OTHER than on one of the TransformItems, all are deselected [default:true]
• allowDelete : Boolean When the user presses the delete (or backspace) key, the selected item(s) will be deleted (except TextFields) [default:false]
• allowMultiSelect : Boolean To prevent users from being able to select multiple items, set this to false [default:true]
• bounds : Rectangle Defines the boundaries for movement/scaling/rotation. [default:null]
• lineColor : Number Controls the line color of the selection box and handles [default:0x3399FF]
• handleSize : Number Controls the handle size (in pixels) [default:8]
• handleFillColor : Number Controls the fill color of the handle [default:0xFFFFFF]
• paddingForRotation : Number Sets the amount of space outside each of the four corner scale handles that will trigger rotation mode [default:12]
• enabled : Boolean Allows you to enable or disable the TransformManager [default:true]
• forceSelectionToFront : Boolean When true, new selections are forced to the front of the display list of the container DisplayObjectContainer [default:false]
• selectedTargetObjects : Array An easy way to get an Array of all selected targetObjects
• selectedItems : Array Similar to selectedTargetObjects, but returns the TransformItem instances of the selected items
• items : Array All of the TransformItem instances that are controlled by this TransformManager (regardless of whether they're selected or not)
• targetObjects : Array All of the targetObjects (DisplayObjects) that are controlled by this TransformManager (regardless of whether they're selected or not)
• hideCenterHandle: Array If true, the center scale handle will be hidden.
• ignoredObjects : Array Sometimes you want TransformManager to ignore clicks on certain DisplayObjects, like buttons, color pickers, etc. Those items should populate the ignoreObjects Array. The DisplayObject CANNOT be a child of a targetObject.

Events

• TransformEvent.SELECTION_CHANGE (the TransformEvent's "items" Array contains any items affected by the selection change - either deselected or selected. to determine which items are selected after the Event, check the TransformManager instance's selectedItems Array)
• TransformEvent.MOVE
• TransformEvent.SCALE
• TransformEvent.ROTATE
• TransformEvent.FINISH_INTERACTIVE_MOVE
• TransformEvent.FINISH_INTERACTIVE_SCALE
• TransformEvent.FINISH_INTERACTIVE_ROTATE
• TransformEvent.CLICK_OFF (only called when autoDeselect is false, otherwise the DESELECT event is called)
• TransformEvent.DELETE
• TransformEvent.DOUBLE_CLICK
• TransformEvent.DEPTH_CHANGE
• TransformEvent.DESTROY

All TransformEvents have an "items" property which is an Array populated by the affected TransformItem instances. TransformEvents also have a "mouseEvent" property that will be populated if there was an associted MouseEvent (like CLICK_OFF)

EXAMPLES

To make two MovieClips (myClip1 and myClip2) transformable using the default settings:

To make the two MovieClips transformable, constrain their scaling to be proportional (even if the user is not holding down the shift key), call the onScale function everytime one of the objects is scaled, lock the rotation value of each MovieClip (preventing rotation), and allow the DELETE key to appear to delete the selected MovieClip from the stage:

To add myClip1 and myClip2 after a TransformManager has been created, set scale constraints so that myClip2 cannot be scaled below 0.5 or above 1, and then listen for when only myClip1 is selected:

Flex example

To make two Images (myImage1 and myImage2) transformable using the default settings:

Tip

• I want autoDeselect on, but I don't want items deselected when the user clicks on certain buttons or form elements. How can I accomplish that? You have several options. You could have TransformManager ignore particular DisplayObjects using the addIgnoredObject() method, or try this:
  1. Set autoDeselect to false
  2. Add a background Sprite (it could have a transparent fill so that it's invisible but still clickable)
  3. Add an Event.CLICK listener to that background Sprite that calls your TransformManage's deselectAll() function.

FAQ

• What if I want to save the state of a transformed object and then recreate (save and load) it to continue working with it? Can TransformManager accommodate that?
  Absolutely, that's precisely what the exportFullXML() and applyFullXML() methods are for. You need to handle loading the images/assets on your own, but it's easy to build a dynamic application around TransformManager. In fact, a huge number of TransformManager users do exactly that.
• If I purchase TransformManager, do I get access to the raw source code files or just a SWC?
  You get the raw source code. Feel free to tweak it if you want, (just don't redistribute it).
• What if I purchase TransformManager but don't like it? Can I get my money back?
  
  Of course. I always offer a 30-day money-back guarantee. If you'd like to forfeit your license and get your money back, just e-mail me and I'll promptly send you the refund.
• Do you offer discounted pricing for charitable/educational projects?
  
  Yes I do, depending on the project. Feel free to contact me about your request at info@greensock.com.
• What are the terms of the license? Is there a multi-user/corporate license available?
  
  If you would like to use TransformManager in a commercial appication or on a team with multiple developers, all you need to do is get the corporate Club GreenSock membership that corresponds to the number of developers in your organization (including freelancers, consultants, etc. who may get access to the code). See the licensing page for details and answers to frequently asked questions.
• Can I use TransformManager to transform dynamically-loaded assets?
  
  Absolutely. Just load your asset, make sure it is fully instantiated, and then use the addItem() method to add it to your TransformManager instance. Keep in mind that all of a TransformManager's items must share the same parent.
• Why do you charge for the code? Why not go open source like you did with TweenLite/TweenMax?
  
  I've learned the hard way that it takes a LOT of work to create, enhance, document, distribute, and support open source code. The vast majority of visitors to my blog just take the code and run. It becomes difficult to justify all the time I invest in the open source stuff. TransformManager caters to a very specific audience, and I think that $299 is actually quite a bargain considering the fact that it represents well over $30,000 worth of development time.
• Can I use TransformManager in Flex 3?
  
  Sure! In fact, I created a FlexTransformManager class to make it particularly easy to integrate into Flex applications. Please be aware of the limitations, though (see above). Many customers are using it successfully in Flex applications.
• I'm a "Shockingly Green" Club GreenSock member, so do I get a discount?
  
  Yes you do. "Shockingly Green" Club GreenSock members get a 15% discount. If you haven't received instructions from me yet about how to receive your discount, just e-mail me and I'll send you a special link.

Need Help?

Feel free to e-mail me a question. Or post your question on the forums.