AS3 Tooltip

At last, I got around to porting my Tooltip Class to Actionscript  3.  Well, when I say “porting”, that’s not quite accurate: this is a complete rewrite.  As such, alot of property names in the options have been changed, some of the defaults are different, and there are a few more public methods.  So if you’ve been using the old AS2 Tooltip, don’t just copy and paste your code, first have a look at the Class, which is fully documented.

Download the Tooltip class

If you’re not familiar with the old AS2 Tooltip: this is a customizable static Singleton Class for generating and displaying Tooltips from anywhere in your code.   There are no assests for the library, since the tooltip is created and drawn dynamically, by invoking the static methods:

Tooltip.show(tooltip:String = “”, localOptions:Object = null, target:DisplayObject = null)
Tooltip.hide()

But now there’s another way to invoke the Tooltip:   DisplayObject instances can now subscribe and unsubscribe themselves from the tooltip for automatic handling:

Tooltip.subscribe(target:DisplayObject, tooltip:String = “”, options:Object = null)

This will register the ROLL_OVER, ROLL_OUT, MOUSE_DOWN, and CLICK events of your target with listeners in the Tooltip, to show and hide the passed tooltip string at the appropriate times.  This is great when your target’s tooltip string doesn’t need to change much, but if you do need to change it,  just call the subscribe() method again with the new arguments.   For example, if you have a custom button class with a String property called “tooltip”, you can use accessor methods to set or change the tooltip, and inside the accessor call Tooltip.subscribe().

And, of course, to unsubscribe:

Tooltip.unsubscribe(target:DisplayObject)

You may have noticed that there’s a third argument in the original Tooltip.show() method.    This is entirely optional, and it’s one of the ways to make sure that the Tooltip is registered with the stage. Since Actionscript3 limits stage access to DisplayObject instances that are already on it, you have to make sure that the stage reference is passed to the Tooltip at least once in the programme’s lifetime.  This is done by passing a DisplayObject instance that’s already registered with the stage, and you can chose one of several ways to do so:

1. Subscribe a target DisplayObject to the tooltip – this will automatically attach the tooltip to the Stage the moment the target becomes a child of the Stage (via an Event.ADDED_TO_STAGE listener).
2.  Pass an optional “target” parameter to the Tooltip.show() method.
3.  Call Tooltip.getInstance(target) once before using the Tooltip.

Formatting and Customisation:

All the Tooltip’s options can be customised both globally and locally.  For global customisation, use the static get/set options accessors to pass an object containing one or more options, or set them one at a time using the static setOption () method.

Tooltip.options = newOptions:Object
Tooltip.setOption(optionName:String, optionValue:*)

For local customisation of individual tooltips, pass an options object to the static Tooltip.show () method, or register local options with the subscribe(method). It’s not necessary to pass all the options – Each default option is applied unless overridden by a global option, which can in turn be overriden by a local option. So only pass the options you want to override with your object.

The text is rendered using html and styled with CSS (it’s no longer necessary or possible to switch html on or off).  The body text is wrapped with  XML <tooltip></tooltip> tags  and the main stylesheet uses the “tooltip” xml selector to format the text,  but additional selectors can be used to format various html entities, by passing a styleSheet property with the options.

The Tooltip uses a fadeIn/fadeOut animation by default, so fonts are also embedded by default – but only if the font corresponding to the fontFamily option is embedded in the Flash file.  The class checks for existance of the Font and switches the embed on or off accordingly. But you can always switch embedFonts off completely.

When a CSS-style comma separated list of fonts is used for fontFamily, the code uses the first located font and ingores all others. However, overriding or additional fonts in the styleSheet option are not checked by the code, so you need to make sure that all those fonts are embedded or turn off the automatic embedding using the embedFonts option.

By default, the Tooltip’s background is a rounded rectangle, with customisable corner rounding. The backgroundColor, lineColor, alpha transparacy, and dropShadow are all customisable using the options.   To use a different background, for example a Symbol in the library, you can pass a customBackground option.  This attaches a MovieClip or other DisplayObject from the library as the tooltip’s background property.   The custom background is then streched to the default dimensions (text width and height plus margins), but for extra control you can also access the Tooltip’s instance properties from within the background instance or anywhere else using:

Tooltip.getInstance().getDimensions();
Tooltip.getInstance.getLocalOptions();

For non-rectangular custom backgrounds, you may need to play around with margins. To set all the margins at once, use the margin property. To override specific margins, use marginLeft, marginRight, marginTop, or marginBottom.

For non standard implementations, if you want the tooltip displayed in a fixed spot on the stage (eg, for a status bar or speech bubble), you can use offsetX and offsetY together with fixedPosition – inn this case, the offset will be relative to the stage instead of the mouse. You can also use fixedWidth to prevent the tooltip from shrinking to fit a single line, and boundingRect to constrain it to an area other than the stage.
List of Tooltip Options:

delay:Number (default: 0.5 seconds) delay in seconds

width:Number (defalut: 200) maximum width of the tooltip rectangle (default: 200px)

alpha:Number (default: 0.8) Alpha transparency of the tooltip’s background

corner:Number (default: 10) The diameter for the rounded corner. For sharp corners pass 0)

margin:Number (default: 4) Overall margin

marginLeft:Number (default: Tooltip.MARGIN) Left margin. Defaults to the overall margin value

marginRight:Number (default: Tooltip.MARGIN) Left margin. Defaults to the overall margin value

marginTop:Number (default: Tooltip.MARGIN) Left margin. Defaults to the overall margin value

marginBottom:Number (default: Tooltip.MARGIN) Left margin. Defaults to the overall margin value

color:Color Text and line color, can also accept a string hex value (default 0x000000)

backgroundColor:int Background color of the tooltip (default: 0xFFFFDD – light yellow)

shadowColor:int (default: Tooltip.COLOR_TEXT) Drop shadow colour. By default duplicates the color property.

shadowType:int (default: Tooltip.SHADOW_HOLLOW), )

lineColor:Color (default: Tooltip.COLOR_TEXT) COLOR_TEXT uses same colour as the options.color. For no line use COLOR_NONE.

customBackground:DisplayObject (defult:null) If true overrides background and line colour settings and inserts a custom class as background. The mc is automatically stretched to fit the dimensions, but can use getDimensions() and getLocalOptions() methods of the Tooltip instance to adjust itself.

styleSheet:TextField.StyleSheet (default: null) Use to extend the default stylesheet.

fontFamily:String (default: “Verdana,Helvetica,_sans”) Can be a single font or a comma separated list of fonts (no spaces between commas allowed).

fontSize:Number Font size (default: 11)

fontWeight:String (default: “normal”)

leading:Number line spacing (default: 2)

textAlign:String (default: TextFormatAlign.LEFT)

embedFonts:Boolean (default: true) If true, will first check if the embedded font passed in the fontFamily option is available (if it’s a list of fonts, it will use the first available font in the list). If set to false, it will not embed the fonts regardles of availability.

followMouse:Boolean (default: true) If true the tooltip will follow mouse

duration:Number or Boolean (default:1) The duration of the fadeIn/fadeOut animation.

offsetX:Number (default 20) Horizontal distance from mouse.

offsetY:Number (default 25) Vertical distance from mouse.

fixedPosition:Boolean (default: false) – If true, the tooltip will appear in a fixed position on the stage, instead of at the mouse position. A fixed tooltip will not adjust to Stage dimensions or follow the mouse.

fixedWidth:Boolean (default: false) don’t adjust the width of a single line tooltip.

boundingRect:Object (default: Tooltip.STAGE_RECT) set the constraining bounds to other than the stage (x, y, width, height);

Usage Example:

 import com.neoarchaic.ui.Tooltip;
Tooltip.options = {width: 500, margin:10}
Tooltip.subscribe(this, “I’m a subscribed tooltip”, {backgroundColor:0x000000, color:”#FFFFFF”});
Tooltip.show(“I’m a tooltip. &lt;br/&gt;I’m 500 pixels wide and have a 10 pixel margin”);
Tooltip.show(“I’m a delayed tooltip.”, {delay: 2});
Tooltip.hide();
Tooltip.unsubscribe(this);

Download the Tooltip class

Do let me know if there are any problems with it, any ideas for improvement, and of course if you managed to use it successfully.