//////////////////////////////////////////////////////////////////////////////// // // Licensed to the Apache Software Foundation (ASF) under one or more // contributor license agreements. See the NOTICE file distributed with // this work for additional information regarding copyright ownership. // The ASF licenses this file to You under the Apache License, Version 2.0 // (the "License"); you may not use this file except in compliance with // the License. You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // //////////////////////////////////////////////////////////////////////////////// package mx.managers { import flash.display.DisplayObject; import flash.events.EventDispatcher; import mx.core.IToolTip; import mx.core.IUIComponent; import mx.core.Singleton; import mx.core.mx_internal; import mx.effects.IAbstractEffect; /** * The ToolTipManager lets you set basic ToolTip and error tip functionality, * such as display delay and the disabling of ToolTips. * * @see mx.controls.ToolTip * @see mx.validators.Validator * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public class ToolTipManager extends EventDispatcher { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Class variables // //-------------------------------------------------------------------------- /** * @private * Linker dependency on implementation class. */ private static var implClassDependency:ToolTipManagerImpl; /** * @private * Storage for the impl getter. * This gets initialized on first access, * not at static initialization time, in order to ensure * that the Singleton registry has already been initialized. */ private static var _impl:IToolTipManager2; /** * @private * The singleton instance of ToolTipManagerImpl which was * registered as implementing the IToolTipManager2 interface. */ private static function get impl():IToolTipManager2 { if (!_impl) { _impl = IToolTipManager2( Singleton.getInstance("mx.managers::IToolTipManager2")); } return _impl; } //-------------------------------------------------------------------------- // // Class properties // //-------------------------------------------------------------------------- //---------------------------------- // currentTarget //---------------------------------- /** * The UIComponent that is currently displaying a ToolTip, * or null if none is. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get currentTarget():DisplayObject { return impl.currentTarget; } /** * @private */ public static function set currentTarget(value:DisplayObject):void { impl.currentTarget = value; } //---------------------------------- // currentToolTip //---------------------------------- /** * The ToolTip object that is currently visible, * or null if none is shown. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get currentToolTip():IToolTip { return impl.currentToolTip; } /** * @private */ public static function set currentToolTip(value:IToolTip):void { impl.currentToolTip = value; } //---------------------------------- // enabled //---------------------------------- /** * If true, the ToolTipManager will automatically show * ToolTips when the user moves the mouse pointer over components. * If false, no ToolTips will be shown. * * @default true * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get enabled():Boolean { return impl.enabled; } /** * @private */ public static function set enabled(value:Boolean):void { impl.enabled = value; } //---------------------------------- // hideDelay //---------------------------------- /** * The amount of time, in milliseconds, that Flex waits * to hide the ToolTip after it appears. * Once Flex hides a ToolTip, the user must move the mouse * off the component and then back onto it to see the ToolTip again. * If you set hideDelay to Infinity, * Flex does not hide the ToolTip until the user triggers an event, * such as moving the mouse off of the component. * * @default 10000 * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get hideDelay():Number { return impl.hideDelay; } /** * @private */ public static function set hideDelay(value:Number):void { impl.hideDelay = value; } //---------------------------------- // hideEffect //---------------------------------- /** * The effect that plays when a ToolTip is hidden, * or null if the ToolTip should disappear with no effect. * * @default null * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get hideEffect():IAbstractEffect { return impl.hideEffect; } /** * @private */ public static function set hideEffect(value:IAbstractEffect):void { impl.hideEffect = value; } //---------------------------------- // scrubDelay //---------------------------------- /** * The amount of time, in milliseconds, that a user can take * when moving the mouse between controls before Flex again waits * for the duration of showDelay to display a ToolTip. * *

This setting is useful if the user moves quickly from one control * to another; after displaying the first ToolTip, Flex will display * the others immediately rather than waiting. * The shorter the setting for scrubDelay, the more * likely that the user must wait for an amount of time specified * by showDelay in order to see the next ToolTip. * A good use of this property is if you have several buttons on a * toolbar, and the user will quickly scan across them to see brief * descriptions of their functionality.

* * @default 100 * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get scrubDelay():Number { return impl.scrubDelay; } /** * @private */ public static function set scrubDelay(value:Number):void { impl.scrubDelay = value; } //---------------------------------- // showDelay //---------------------------------- /** * The amount of time, in milliseconds, that Flex waits * before displaying the ToolTip box once a user * moves the mouse over a component that has a ToolTip. * To make the ToolTip appear instantly, set showDelay to 0. * * @default 500 * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get showDelay():Number { return impl.showDelay; } /** * @private */ public static function set showDelay(value:Number):void { impl.showDelay = value; } //---------------------------------- // showEffect //---------------------------------- /** * The effect that plays when a ToolTip is shown, * or null if the ToolTip should appear with no effect. * * @default null * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get showEffect():IAbstractEffect { return impl.showEffect; } /** * @private */ public static function set showEffect(value:IAbstractEffect):void { impl.showEffect = value; } //---------------------------------- // toolTipClass //---------------------------------- /** * The class to use for creating ToolTips. * * @default mx.controls.ToolTip * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function get toolTipClass():Class { return impl.toolTipClass; } /** * @private */ public static function set toolTipClass(value:Class):void { impl.toolTipClass = value; } //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Registers a target UIComponent or UITextField, and the text * for its ToolTip, with the ToolTipManager. * This causes the ToolTipManager to display a ToolTip * when the mouse hovers over the target. * *

This method is called by the setter * for the toolTip property in UIComponent and UITextField.

* * @param target The UIComponent or UITextField that owns the ToolTip. * * @param toolTip The text to display in the ToolTip. * If null, no ToolTip will be displayed when the mouse hovers * over the target. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ mx_internal static function registerToolTip(target:DisplayObject, oldToolTip:String, newToolTip:String):void { impl.registerToolTip(target, oldToolTip, newToolTip); } /** * Registers a target UIComponent, and the text * for its error tip, with the ToolTipManager. * This causes the ToolTipManager to display an error tip * when the mouse hovers over the target. * *

This method is called by the setter * for the errorString property in UIComponent.

* * @param target The UIComponent or UITextField that owns the ToolTip. * * @param toolTip The text to display in the ToolTip. * If null, no ToolTip will be displayed when the mouse hovers * over the target. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ mx_internal static function registerErrorString(target:DisplayObject, oldErrorString:String, newErrorString:String):void { impl.registerErrorString(target, oldErrorString, newErrorString); } /** * @private * Objects added to the SystemManager's ToolTip layer don't get * automatically measured or sized, so ToolTipManager has to * measure it and set its size. */ mx_internal static function sizeTip(toolTip:IToolTip):void { impl.sizeTip(toolTip); } /** * Creates an instance of the ToolTip class with the specified text * and displays it at the specified location in stage coordinates. * *

ToolTips appear in their own layer, on top of everything * except cursors.

* *

The standard way of using ToolTips is to let the ToolTipManager * automatically show and hide them as the user moves the mouse over * the objects that have the toolTip property set. * You can turn off this automatic ToolTip management by setting * the ToolTipManager's enabled property to * false.

* *

By contrast, this method—along with destroyToolTip()—gives * you programmatic control over ToolTips. * You can show them when and where you choose, * and you can even show more than one at once if you need to. * (The ToolTipManager never does this, because it is generally * confusing to the user).

* *

This method first creates a new instance of ToolTip and calls the * addChild() method to put it into the SystemManager's * toolTips layer. * If you are showing an error tip, it sets the appropriate styles. * Then it sets the text for the ToolTip, sizes the ToolTip based on * its text, and positions it where you specified.

* *

You must save the reference to the ToolTip that this method * returns so that you can pass it to the destroyToolTip() method.

* * @param text The text to display in the ToolTip instance. * * @param x The horizontal coordinate of the ToolTip in stage coordinates. * In case of multiple stages, the relevant stage is determined * from the context argument. * * @param y The vertical coordinate of the ToolTip in stage coordinates. * In case of multiple stages, the relevant stage is determined * from the context argument. * * @param errorTipBorderStyle The border style of an error tip. This method * argument can be null, "errorTipRight", "errorTipAbove", or "errorTipBelow". * If it is null, then the createToolTip() method creates a normal ToolTip. If it is * "errorTipRight", "errorTipAbove", or "errorTipBelow", then the createToolTip() * method creates an error tip, and this parameter determines where the arrow * of the error tip points to (the error's target). For example, if you pass "errorTipRight", Flex * positions the error tip (via the x and y arguments) to the * right of the error target; the arrow is on the left edge of the error tip. * * @param context Determines which StyleManager is used. Typically, you pass the object on * which the ToolTip appears, so that the ToolTip's StyleManager is the same one that is used by that object. * * @return The newly created ToolTip. * * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function createToolTip(text:String, x:Number, y:Number, errorTipBorderStyle:String = null, context:IUIComponent = null):IToolTip { return impl.createToolTip(text, x, y, errorTipBorderStyle, context); } /** * Destroys a specified ToolTip that was created by the createToolTip() method. * *

This method calls the removeChild() method to remove the specified * ToolTip from the SystemManager's ToolTips layer. * It will then be garbage-collected unless you keep a * reference to it.

* *

You should not call this method on the ToolTipManager's * currentToolTip.

* * @param toolTip The ToolTip instance to destroy. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public static function destroyToolTip(toolTip:IToolTip):void { return impl.destroyToolTip(toolTip); } } }