Using the ToolTip Manager

来源：互联网发布：淘宝哪家店女装质量好编辑：程序博客网时间：2024/05/17 02:33

http://livedocs.adobe.com/flex/3/html/help.html?content=tooltips_4.html

The ToolTipManager class lets you set basic ToolTip functionality, such as display delay and the disabling of ToolTips. It is located in the mx.managers package. You must import this class when using the ToolTipManager. The ToolTipManager class also contains a reference to the current ToolTip in its currentToolTipproperty.

Enabling and disabling ToolTips

You can enable and disable ToolTips in your Flex applications. When you disable ToolTips, no ToolTip box appears when the user moves the mouse pointer over a visible component, regardless of whether that component's toolTip property is set.

You use the enabled property of the ToolTipManager to enable or disable ToolTips. You set this property to true to enable ToolTips or false to disable ToolTips. The default value is true.

The following example toggles ToolTips on and off when the user clicks the Toggle ToolTips button:

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script><![CDATA[

import mx.managers.ToolTipManager;

private function toggleToolTips():void {

if (ToolTipManager.enabled) {

ToolTipManager.enabled = false;

} else {

ToolTipManager.enabled = true;

}

]]></mx:Script>

<mx:Button id="b1"

label="Toggle ToolTips"

width="150"

click="toggleToolTips();"

toolTip="Click me to enable/disable tooltips."

</mx:Application>

The executing SWF file for the previous example is shown below:

Setting delay times

A delay time is a measurement of time that passes before something takes place. For example, after the user moves the mouse pointer over a component, there is a brief delay before the ToolTip appears. This gives someone who is not looking for ToolTip text enough time to move the mouse pointer away before seeing the pop-up.

The ToolTipManager lets you set the length of time that passes before the ToolTip box appears, and the length of time that a ToolTip remains on the screen when a mouse pointer hovers over the component. You can also set the delay between ToolTips.

You set the value of the ToolTipManager showDelay, hideDelay, and scrubDelay properties in your ActionScript code blocks. The following table describes the time delay properties of the ToolTipManager:

Property

Description

showDelay

The length of time, in milliseconds, that Flex waits before displaying the ToolTip box when a user moves the mouse pointer over a component that has a ToolTip.

To make the ToolTip appear instantly, set the showDelay property to 0.

The default value is 500 milliseconds, or half of a second.

hideDelay

The length of time, in milliseconds, that Flex waits to hide the ToolTip box after it appears. This amount of time only applies if the mouse pointer is over the target component. Otherwise the ToolTip disappears immediately when you move the mouse pointer away from the target component. After Flex hides a ToolTip box, the user must move the mouse pointer off the component and back onto it to see the ToolTip box again.

If you set the hideDelay property to 0, Flex does not display the ToolTip. Adobe recommends that you use the default value of 10,000 milliseconds, or 10 seconds.

If you set the hideDelay property to Infinity, Flex does not hide the ToolTip until the user triggers an event (such as moving the mouse pointer off the component). The following example sets the hideDelay property to Infinity:

ToolTipManager.hideDelay = Infinity;

scrubDelay

The length 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 box.

This setting is useful if the user moves quickly from one control to another; after displaying the first ToolTip, Flex displays the others immediately rather than waiting for the duration of the showDelay setting. The shorter the setting for scrubDelay, the more likely that the user must wait for an amount of time specified by the showDelay property 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.

The default value is 100.

The following example uses the Application control's initialize event to set the starting values for the ToolTipManager:

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp();">

<mx:Script><![CDATA[

import mx.managers.ToolTipManager;

private function initApp():void {

ToolTipManager.enabled = true;// Optional. Default value is true.

ToolTipManager.showDelay = 0;// Display immediately.

ToolTipManager.hideDelay = 3000; // Hide after 3 seconds of being viewed.

}

]]></mx:Script>

<mx:Button label="Click Me" toolTip="Click this Button to do something."/>

<mx:Button label="Click Me" toolTip="Click this Button to do something else."/>

<mx:Button label="Click Me" toolTip="Click this Button to do a third thing."/>

<mx:Button label="Click Me" toolTip="Click this Button to do the same thing."/>

</mx:Application>

The executing SWF file for the previous example is shown below:

Using effects with ToolTips

You can use a custom effect or one of the standard Flex effects with ToolTips. You set the showEffect or hideEffect property of the ToolTipManager to define the effect that is triggered whenever a ToolTip is displayed or is hidden.

The following example uses the Fade effect so that ToolTips fade in when the user moves the mouse pointer over a component with a ToolTip:

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="600" height="600" initialize="app_init();">

<mx:Script><![CDATA[

import mx.managers.ToolTipManager;

public function app_init():void {

ToolTipManager.showEffect = fadeIn;

}

]]></mx:Script>

<mx:Fade id="fadeIn" alphaFrom="0" alphaTo="1" duration="1000"/>

<mx:Button id="b1" label="Click Me" toolTip="This is a ToolTip that fades in."/>

</mx:Application>

The executing SWF file for the previous example is shown below:

By default, the font used in this example does not fade. You must use an embedded font to achieve the effect. For more information on using embedded fonts, see Using embedded fonts.

If you set a fade out effect for the hideEffect event, the user must wait with the mouse hovering over the component to trigger that effect; the hideToolTipevent is not triggered if the user moves the mouse pointer to a different component before the ToolTip object hides on its own.

For more information about using effects and defining custom effects, see Using Behaviors.

Using dynamic ToolTip text

You can use ToolTips for more than just displaying static help text to the user. You can also bind the ToolTip text to data or component text. This lets you use ToolTips as a part of the user interface, showing drill-down information, query results, or more helpful text that is customized to the user experience.

You bind the value of the ToolTip text to the value of another control's text using curly braces ({ }) syntax.

The following example inserts the value of the TextInput control into the Button control's ToolTip text when the user moves the mouse pointer over the Button control:

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:TextInput id="txtTo" width="300"/>

<mx:Button label="Send" toolTip="Send e-mail to {txtTo.text}"/>

</mx:Application>

The executing SWF file for the previous example is shown below:

In this example, if the user enters fred@fred.com in the TextInput box, and then moves the mouse pointer over the button, Flex displays the message "Send e-mail to fred@fred.com" in the ToolTip box.

Another approach to creating dynamic text for ToolTips is to intercept the ToolTip in its toolTipShow event handler and change the value of its text property. The following example registers the myToolTipChanger() method as a listener for the Button control's toolTipShow event. The code in that method changes the value of the ToolTipManager.currentToolTip.text property to a value that is not known until run time.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="initApp()">

<mx:Script><![CDATA[

import mx.managers.ToolTipManager;

import mx.controls.ToolTip;

import mx.events.ToolTipEvent;

public function initApp():void {

b1.addEventListener(ToolTipEvent.TOOL_TIP_SHOW, myToolTipChanger)

}

public function myToolTipChanger(event:ToolTipEvent):void {

// Pass the value of myName in to your application in some way.

// For example, as a flashVar variable.

ToolTipManager.currentToolTip.text = "Click the button, " +

Application.application.parameters.myName;

}

]]> </mx:Script>

<mx:Button id="b1" label="Click Me" toolTip="Click the button."/>

</mx:Application>

The executing SWF file for the previous example is shown below:

You can only create text for the current ToolTip in the toolTipShow event handler if the object had a ToolTip in the first place. For example, if the button in the previous example did not set a value for the toolTip property, no ToolTip would appear even after the myToolTipChanger() method was called.

For information about using the Application.application.parameters object, see Passing request data with flashVars properties.

Creating custom ToolTips

The ToolTipManager has two methods that let you programmatically use ToolTips. These methods are createToolTip() and destroyToolTip(), which you use to create and destroy new ToolTip objects. When you create a ToolTip object, you can customize it as you would any object, with access to its properties, styles, events, and effects.

This createToolTip() method has the following signature:

createToolTip(text:String, x:Number, y:Number, errorTipBorderStyle:String,
context:IUIComponent):IToolTip

The text parameter defines the contents of the ToolTip. The x and y parameters define the x and y coordinates of the ToolTip, relative to the application container. The errorTipBorderStyle parameter sets the location of the pointer on the error tip. This parameter is optional. If you specify this value in thecreateToolTip() method, Flex styles the ToolTip as an error tip. The following example shows the valid values and their resulting locations on the error tip:

The context parameter is not currently used.

The createToolTip() method returns a new ToolTip object that implements the IToolTip interface. You must often cast the return value of this method to a ToolTip, although it is more efficient if you do not do this. To cast, you can do one of the following:

Use the as keyword, as the following example shows:
myTip = ToolTipManager.createToolTip(s,10,10) as ToolTip;
Use the type(object) casting syntax, as the following example shows:
myTip = ToolTip(ToolTipManager.createToolTip(s,10,10));

These methods of casting differ only in the way they behave when a cast fails.

For more information about using error tips, see Using error tips.

Flex displays the ToolTip until you destroy it. In general, you should not display more than one ToolTip box at a time, because it is confusing to the user.

You can use the destroyToolTip() method to destroy the specified ToolTip object. The destroyToolTip() method has the following signature:

destroyToolTip(toolTip:IToolTip):void

The toolTip parameter is the ToolTip object that you want to destroy. This is the object returned by the createToolTip() method.

The following example creates a custom ToolTip when you move the mouse over a Panel container that contains three Button controls. Each Button control has its own ToolTip that appears when you mouse over that particular control. The big ToolTip disappears only when you move the mouse away from the Panel container.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script><![CDATA[

import mx.managers.ToolTipManager;

import mx.controls.ToolTip;

public var myTip:ToolTip;

private function createBigTip():void {

var s:String = "These buttons let you save, exit, or continue with the current operation."

myTip = ToolTipManager.createToolTip(s,10,10) as ToolTip;

myTip.setStyle("backgroundColor",0xFFCC00);

myTip.width = 150;

myTip.height = 200;

}

private function destroyBigTip():void {

ToolTipManager.destroyToolTip(myTip);

}

]]></mx:Script>

<mx:Style>

Panel {

paddingLeft: 5;

paddingRight: 5;

paddingTop: 5;

paddingBottom: 5;

}

</mx:Style>

<mx:Panel title="ToolTips" rollOver="createBigTip()" rollOut="destroyBigTip()">

<mx:Button label="OK" toolTip="Save your changes and exit."/>

<mx:Button label="Apply" toolTip="Apply changes and continue."/>

<mx:Button label="Cancel" toolTip="Cancel and exit."/>

</mx:Panel>

</mx:Application>

The executing SWF file for the previous example is shown below:

You can also create a custom ToolTip by extending an existing control, such as a Panel or VBox container, and implementing the IToolTip interface. The following example uses a Panel container as the base for a new implementation of the IToolTip interface:

<?xml version="1.0"?>

<mx:Panel xmlns:mx="http://www.adobe.com/2006/mxml"

implements="mx.core.IToolTip"

width="200"

alpha=".8"

borderThickness="2"

backgroundColor="0xCCCCCC"

dropShadowEnabled="true"

borderColor="black"

borderStyle="solid"

title="feh"

<mx:Script><![CDATA[

[Bindable]

public var bodyText:String = "";

// Implement required methods of the IToolTip interface; these

// methods are not used in this example, though.

public var _text:String;

public function get text():String {

return _text;

}

public function set text(value:String):void {

}

]]></mx:Script>

<mx:Text text="{bodyText}" percentWidth="100"/>

</mx:Panel>

In your application, you can create a custom ToolTip by intercepting the toolTipCreate event handler of the target component. In the event handler, you instantiate the new ToolTip and set its properties. You then point the toolTip property of the ToolTipEvent object to the new ToolTip.

In the following example, the first two buttons in the application use the custom PanelToolTip in the CustomToolTips package. The third button uses a default ToolTip to show you how the two are different. To run this example, store the PanelToolTip.mxml file in a subdirectory named CustomToolTips.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script><![CDATA[

import ToolTipComponents.PanelToolTip;

import mx.events.ToolTipEvent;

private function createCustomTip(title:String, body:String, event:ToolTipEvent):void {

var ptt:PanelToolTip = new PanelToolTip();

ptt.title = title;

ptt.bodyText = body;

event.toolTip = ptt;

}

]]></mx:Script>

<mx:Button id="b1"

label="Delete"

toolTip=" "

toolTipCreate="createCustomTip('DELETE','Click this button to delete the report.', event)"

<mx:Button id="b2"

label="Generate"

toolTip=" "

toolTipCreate="createCustomTip('GENERATE','Click this button to generate the report.', event)"

<mx:Button id="b3"

label="Stop"

toolTip="Click this button to stop the creation of the report. This button uses a standard ToolTip style."

</mx:Application>

The executing SWF file for the previous example is shown below:

Positioning custom ToolTips

When you use the ToolTipManager to create a custom ToolTip, you specify the coordinates of the ToolTip on the Stage. You do this by specifying the values of thex and y parameters of the new ToolTip in the createToolTip() method. These coordinates are relative to the Stage. For example, a value of 0,0 creates a ToolTip at the top-left corner of the application.

In some cases, you might not know the exact position that you want the ToolTip to be drawn in; instead, you want the location of the ToolTip to be relative to the target component (the component that has a ToolTip on it). In those cases, you can use the location of the target component to calculate the values of these coordinates. For example, if you want the ToolTip to appear to a component's right, you set the ToolTip's x position to be the x position of the component plus the component's width, plus some other value for an offset.

The following image shows the results of this formula:

You also set the value of the ToolTip's y position to be the same as the target component's y position to line the ToolTip and the component up horizontally.

One way to get the values you need to calculate the x position of the ToolTip is to use an event handler. Event objects passed to an event handler can give you the x position and the width of the target component.

The following example gets the value of the current target's x, y, and width properties in the focusIn event handler, and uses them to position the ToolTip. In this case, the current target is the TextInput control, and the ToolTip appears to its right with a 10-pixel offset.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalAlign="middle" horizontalAlign="center" height="100" width="300">

<mx:Script>

<![CDATA[

import mx.controls.ToolTip;

import mx.managers.ToolTipManager;

private var tip:ToolTip;

private var s:String;

private function showTip(event:Object):void {

s="My ToolTip";

// Position the ToolTip to the right of the current target.

tip = ToolTipManager.createToolTip(s,

event.currentTarget.x + event.currentTarget.width + 10,

event.currentTarget.y)

as ToolTip;

}

private function destroyTip(event:Object):void {

ToolTipManager.destroyToolTip(tip);

}

]]>

</mx:Script>

<mx:TextInput id="a"

width="100"

focusIn="showTip(event)"

focusOut="destroyTip(event)"

<mx:TextInput id="b"

width="100"

focusIn="showTip(event)"

focusOut="destroyTip(event)"

</mx:Application>

The executing SWF file for the previous example is shown below:

The previous example creates a ToolTip on a target component that is not inside any containers. However, in many cases, your components will be inside layout containers such as a VBox or an HBox. Under these circumstances, the coordinates you access in the event handler will be relative to the container and not the main application. But the ToolTipManager expects global coordinates when positioning the ToolTip. This will position ToolTips in unexpected locations.

To avoid this, you can use the contentToGlobal() method to convert the coordinates in the event handler from local to global. All components that subclass UIComponent have this method. It takes a single Point that is relative to the target's enclosing container as an argument and returns a Point that is relative to the Stage.

The following example calls the TextInput control's contentToGlobal() method to convert the control's coordinates from those that are relative to the VBox container to global coordinates.

<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" verticalAlign="middle" horizontalAlign="center" height="250" width="400">

<mx:Script>

<![CDATA[

import mx.controls.ToolTip;

import mx.managers.ToolTipManager;

private var tip:ToolTip;

private var s:String;

private function showTipA(event:Object):void {

s="My Tip A";

tip = ToolTipManager.createToolTip(s,

event.currentTarget.x + event.currentTarget.width + 10,

event.currentTarget.y

) as ToolTip;

}

private function showTipB(event:Object):void {

s="My Tip B";

var pt:Point = new Point(

event.currentTarget.x,

event.currentTarget.y);

// Call this method to convert the object's

// coordinates inside its container to the stage's

// global coordinates.

pt = event.currentTarget.contentToGlobal(pt);

tip = ToolTipManager.createToolTip(s,

pt.x + event.currentTarget.width + 10,

pt.y

) as ToolTip;

}

private function destroyTip(event:Object):void {

ToolTipManager.destroyToolTip(tip);

}

]]>

</mx:Script>

<!-- The event handler for this ToolTip does not use any special

logic to account for whether the ToolTip is inside a container.

But this ToolTip is not inside a container so it positions itself

normally. -->

<mx:TextInput id="a"

text="Good ToolTip placement"

width="175"

focusIn="showTipA(event)"

focusOut="destroyTip(event)"

<mx:VBox >

<!-- The event handler for this ToolTip accounts for the control

being inside a container and positions the ToolTip using the

contentToGlobal() method. -->

<mx:TextInput id="b"

text="Good ToolTip placement"

width="175"

focusIn="showTipB(event)"

focusOut="destroyTip(event)"

<!-- The event handler for this ToolTip does not use any special

logic to account for whether the ToolTip is inside a container.

As a result, it positions itself using coordinates that are relative

to the container, but that are not converted to global coordinates. -->

<mx:TextInput id="c"

text="Bad ToolTip placement"

width="175"

focusIn="showTipA(event)"

focusOut="destroyTip(event)"

</mx:VBox>

</mx:Application>

The executing SWF file for the previous example is shown below: