Tooltips

Implements tooltips for an application.  Tooltips are displayed when the user hovers the mouse over associated display objects.

Summary
TooltipsImplements tooltips for an application.
Private constants
marginBase margin constant used to position text and tooltips.
tooltipDisplayObjectNameDisplay object name of a tooltip on the display list.
Private members
appRootReference to a sprite where tooltips and event handlers are attached.
itemsArray of registered display item name strings.
textsArray of tooltip text Label widgets with a one-to-one relationship with the items array for quick lookup on the same index.
posArray of tooltip Point positions for custom tooltip placement.
colorText color used for the tooltip label texts.
bgColorColor of the tooltip background.
autoRemoveDetermines if tooltips are automatically removed on mouse out events.
tipCurrently displayed tooltip sprite, null if none is shown.
enabledState variable determining if tooltips are displayed.
Constructor
TooltipsCreates a tooltip manager, use registerTip to add tooltips to display objects and updateTip to dynamically change and display them.
Public methods
registerTipRegisters a tooltip for a display object name.
updateTipUpdate an existing tooltip and display it.
removeTipRemoves any currently displayed tooltip from view.
enableAllow the tooltip manager to display tooltips.
disablePrevent the tooltip manager from displaying tooltips.
Private event handlers
onMouseOverDisplays a tooltip when the mouse is over a display object with a name matching a registered item name and tooltips are enabled.
onMouseOutRemoves any displayed tooltip when the mouse leaves a display object.
Private display methods
displayTipDisplays a tooltip label near a display object.
positionTipPositions a tooltip near a display object or at a custom position.
drawTipDraws a tooltip background.
addShadowAdds a drop shadow to a tooltip sprite.
WidgetInterface
activeSets the state of the widget to active or inactive.
activateActivates the widget, adds its event listeners
disactivateDisactivates the widget, removes its event listeners
disposeDispose of all resources used or referenced in the instance.
destructorRemoves used resources, references and graphics

Private constants

margin

private const margin: uint

Base margin constant used to position text and tooltips.

tooltipDisplayObjectName

private const tooltipDisplayObjectName: String

Display object name of a tooltip on the display list.

Private members

appRoot

private var appRoot: Sprite

Reference to a sprite where tooltips and event handlers are attached.  Normally the application background or main display object.

items

private var items: Array

Array of registered display item name strings.  Used as a lookup table to check if a/which tooltip should be displayed when the mouse hovers over a display object.

texts

private var texts: Array

Array of tooltip text Label widgets with a one-to-one relationship with the items array for quick lookup on the same index.

pos

private var pos: Array

Array of tooltip Point positions for custom tooltip placement.  The indexed value is null, when a tooltip is automatically placed.  It has a one-to-one relationship with the items array for quick lookup on the same index.

color

private var color: uint

Text color used for the tooltip label texts.

bgColor

private var bgColor: uint

Color of the tooltip background.  The color is modified slightly with a 0.8 transparency level.

autoRemove

private var autoRemove: Boolean

Determines if tooltips are automatically removed on mouse out events.  This is by default set to true.  But setting it to false through the automaticRemove constructor parameter can avoid tooltip flicker in for instance a game where tooltips might be following moving objects.  It is then up to the application to call removeTip at the appropriate times possibly in a mouse out event handler attached to the appRoot display object.

tip

private var tip: Sprite

Currently displayed tooltip sprite, null if none is shown.

enabled

private var enabled: Boolean

State variable determining if tooltips are displayed.

Constructor

Tooltips

public function Tooltips(owner: String,  
toplevel: Sprite,  
frontColor: uint,  
backColor: uint,  
automaticRemove: Boolean = true):void

Creates a tooltip manager, use registerTip to add tooltips to display objects and updateTip to dynamically change and display them.

There should only be one tooltip manager in an application or at least only one active to avoid excessive resource usage.

Parameters

ownername of registered owner; see WidgetSprite.register
toplevelmain application or background sprite; see appRoot.
frontColortooltip text color.
backColortooltip background color.
automaticRemovewhether tooltips are auto-removed (default true); see autoRemove.

Public methods

registerTip

public function registerTip(itemName: String,  
text: String,  
position: Point = null):Label

Registers a tooltip for a display object name.  Can be called multiple times for the same name to change the tooltip text or position.

Normally the name of a display object is unique so each object gets its own tooltip text.  However this is not required and multiple display objects can therefore all display the same tooltip.

The returned Label reference which has TextField as its base class can be used to set special text formatting properties on the tooltip label or the application may keep a reference to it to do custom tooltip text updates more efficiently than by calling this method repeatedly.

Parameters

itemNamedisplay object name used to identify when the tooltip is displayed
texttooltip text, can be multiline if ‘\n’ are embedded in the text
positioncustom tooltip placement (default null is automatic); see positionTip

Returns

Reference to the created tooltip Label widget.

See also

updateTip

updateTip

public function updateTip(item: DisplayObject,  
itemName: String,  
text: String,  
position: Point = null):void

Update an existing tooltip and display it.  Basically the same as registerTip except any displayed tooltip is removed and this tooltip is shown.  The tooltip may be shown very briefly if the mouse is not over the display object where the tooltip is shown.

Parameters

itema display object where the tooltip is displayed
itemNamedisplay object name used to identify when the tooltip is displayed
texttooltip text, can be multiline if ‘\n’ are embedded in the text
positioncustom tooltip placement (default null is automatic); see positionTip

See also

registerTip

removeTip

public function removeTip():void

Removes any currently displayed tooltip from view.  The tooltip is not deregistered and can be shown again if the user hovers the mouse over an associated item.

enable

public function enable():void

Allow the tooltip manager to display tooltips.  This is by default the case.  See: disable.

disable

public function disable():void

Prevent the tooltip manager from displaying tooltips.  Call enable to allow the display of tooltips again.

Private event handlers

onMouseOver

private function onMouseOver(event: MouseEvent):void

Displays a tooltip when the mouse is over a display object with a name matching a registered item name and tooltips are enabled.

Parameters

eventa mouse over event

onMouseOut

private function onMouseOut(event: MouseEvent):void

Removes any displayed tooltip when the mouse leaves a display object.  This method is only called if automatic removal of tooltips are enabled for the tooltip manager.

Parameters

eventa mouse out event

Private display methods

displayTip

private function displayTip(newItem: DisplayObject,
textLabel: Label):void

Displays a tooltip label near a display object.  The current implementation positions tooltips below the display object.

Parameters

newItema new display object for which to display a tooltip
textLabeltooltip text label to be shown

positionTip

private function positionTip(item: DisplayObject,
newTip: Sprite):void

Positions a tooltip near a display object or at a custom position.  A custom position can be given when calling registerTip or updateTip.

Parameters

itemthe display object for which to position the tooltip
newTipthe tooltip background sprite to be positioned.

drawTip

private function drawTip(g: Graphics,
w: Number,
h: Number):void

Draws a tooltip background.  The background is drawn as a partially transparent rounded rectangle with a margin surrounding the area of the given width and height.  A small rectangle is drawn to point up to a display object.

Parameters

ggraphics object where the background is drawn
wwidth of the label for which the background is drawn
hheight of the label for which the background is drawn

addShadow

private function addShadow(newTip: Sprite):void

Adds a drop shadow to a tooltip sprite.

Parameters

newTipa newly created tooltip sprite without a drop shadow

WidgetInterface

active

public function set active(state: Boolean):void

Sets the state of the widget to active or inactive.

Parameters

stateTrue to activate, false otherwise.

activate

private function activate():void

Activates the widget, adds its event listeners

disactivate

private function disactivate():void

Disactivates the widget, removes its event listeners

dispose

public function dispose():void

Dispose of all resources used or referenced in the instance.

destructor

private function destructor():void

Removes used resources, references and graphics

Widgets are required to implement this interface.
Base class for widgets to enable/disable event listeners and keep a global tab order of all widgets (provided they are created and registered in tab order.
private const margin: uint
Base margin constant used to position text and tooltips.
private const tooltipDisplayObjectName: String
Display object name of a tooltip on the display list.
private var appRoot: Sprite
Reference to a sprite where tooltips and event handlers are attached.
private var items: Array
Array of registered display item name strings.
private var texts: Array
Array of tooltip text Label widgets with a one-to-one relationship with the items array for quick lookup on the same index.
A static text label.
private var pos: Array
Array of tooltip Point positions for custom tooltip placement.
private var color: uint
Text color used for the tooltip label texts.
private var bgColor: uint
Color of the tooltip background.
private var autoRemove: Boolean
Determines if tooltips are automatically removed on mouse out events.
private var tip: Sprite
Currently displayed tooltip sprite, null if none is shown.
private var enabled: Boolean
State variable determining if tooltips are displayed.
public function Tooltips(owner: String,  
toplevel: Sprite,  
frontColor: uint,  
backColor: uint,  
automaticRemove: Boolean = true):void
Creates a tooltip manager, use registerTip to add tooltips to display objects and updateTip to dynamically change and display them.
public function registerTip(itemName: String,  
text: String,  
position: Point = null):Label
Registers a tooltip for a display object name.
public function updateTip(item: DisplayObject,  
itemName: String,  
text: String,  
position: Point = null):void
Update an existing tooltip and display it.
public function removeTip():void
Removes any currently displayed tooltip from view.
public function enable():void
Allow the tooltip manager to display tooltips.
public function disable():void
Prevent the tooltip manager from displaying tooltips.
private function onMouseOver(event: MouseEvent):void
Displays a tooltip when the mouse is over a display object with a name matching a registered item name and tooltips are enabled.
private function onMouseOut(event: MouseEvent):void
Removes any displayed tooltip when the mouse leaves a display object.
private function displayTip(newItem: DisplayObject,
textLabel: Label):void
Displays a tooltip label near a display object.
private function positionTip(item: DisplayObject,
newTip: Sprite):void
Positions a tooltip near a display object or at a custom position.
private function drawTip(g: Graphics,
w: Number,
h: Number):void
Draws a tooltip background.
private function addShadow(newTip: Sprite):void
Adds a drop shadow to a tooltip sprite.
public function set active(state: Boolean):void
Sets the state of the widget to active or inactive.
private function activate():void
Activates the widget, adds its event listeners
private function disactivate():void
Disactivates the widget, removes its event listeners
public function dispose():void
Dispose of all resources used or referenced in the instance.
private function destructor():void
Removes used resources, references and graphics
public function register(owner: String):void
Register the owner of a widget.
Close