Creating ToolTips

Every visual Flex component that extends the UIComponent class (which implements the IToolTipManagerClient interface) supports a toolTip property. This property is inherited from the UIComponent class. You set the value of the toolTip property to a text string, and when the mouse pointer hovers over that component, the text string appears. The following example sets the toolTip property text for a Button control:

<?xml version="1.0"?>
<!-- tooltips/BasicToolTip.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Button id="b1" label="Click Me" toolTip="This Button does nothing."/>

</mx:Application>
The executing SWF file for the previous example is shown below:

To set the value of a ToolTip in ActionScript, use the toolTip property of the component. The following example creates a new Button and sets the toolTip property of a Button control:

<?xml version="1.0"?>
<!-- tooltips/BasicToolTipActionScript.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:Script><![CDATA[
     public function createNewButton(event:MouseEvent):void {
        var myButton:Button = new Button();
        myButton.label = "Create Another Button";
        myButton.toolTip = "Click this new button to create another button.";
        myButton.addEventListener(MouseEvent.CLICK, createNewButton);
        addChild(myButton);
     }
  ]]></mx:Script>
  <mx:Button id="b1" label="Create Another Button" click="createNewButton(event);"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

If you do not define a ToolTip on the child of a container, the ToolTipManager displays the parent's ToolTip. For example, if you add a Button control to a Panel container that has a ToolTip, the user sees the Panel container's ToolTip text when the user moves the mouse pointer over the Panel. When the user moves the mouse pointer over the Button control, the Panel's ToolTip continues to be displayed. You can override the container's ToolTip text by setting the value of the child's toolTip property.

The following example shows the inheritance of ToolTip text:

<?xml version="1.0"?>
<!-- tooltips/ToolTipInheritance.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:VBox toolTip="VBOX">
     <mx:Button id="b1" label="Button 1" toolTip="BUTTON"/>
     <mx:Button id="b2" label="Button 2"/>
  </mx:VBox>
 
</mx:Application>
The executing SWF file for the previous example is shown below:

When the mouse pointer is over button b1, the ToolTip displays BUTTON. When the mouse pointer is over button b2 or anywhere in the VBox container except over button b1, the ToolTip displays VBOX.

The TabNavigator container uses the ToolTips that are on its children. If you add a ToolTip to a child view of a TabNavigator container, the ToolTip appears when the mouse is over the tab for that view, but not when the mouse is over the view itself. If you add a ToolTip to the TabNavigator container, the ToolTip appears when the mouse is over either the tab or the view, unless the ToolTip is overridden by the tab or the view. ToolTips in the following controls also behave this way:

There is no limit to the size of the ToolTip text, although long messages can be difficult to read. When the ToolTip text reaches the width of the ToolTip box, the text wraps to the next line. You can add line breaks in ToolTip text. In ActionScript, you use the \n escaped newline character. In MXML tags, you use the  XML entity.

The following examples show using the \n escaped newline character and the  entity:

<?xml version="1.0"?>
<!-- tooltips/ToolTipNewlines.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="doSomething(event)">
  <mx:Script><![CDATA[
     public function doSomething(event:Event):void {
        // Use the \n to force a line break in ActionScript.
        b1.toolTip = "Click this button \n to clear the form.";
     }
  ]]></mx:Script>
  <mx:Button id="b1" label="Clear" width="100"/>
  <!-- Use &#13; to force a line break in MXML tags. -->
  <mx:Button id="b2" label="Submit" width="100" toolTip="Click this button &#13; to submit the form."/>
</mx:Application>
The executing SWF file for the previous example is shown below:

You also have some flexibility in formatting the text of the ToolTip. You can apply styles and change other settings for all ToolTips in your application by using the ToolTip Cascading Style Sheets (CSS) type selector. The following sections describe how to set styles on the ToolTip text and box.

Setting styles in ToolTips

You can change the appearance of ToolTip text and the ToolTip box by using CSS syntax or the mx.styles.StyleManager class. Changes to ToolTip styles apply to all ToolTips in the current application.

The default styles for ToolTips are defined by the ToolTip type selector in the defaults.css file in the framework.swc file. You can use a type selector in the <mx:Style> tag to override the default styles of your ToolTips. The following example sets the styles of the ToolTip type selector using CSS syntax:

<?xml version="1.0"?>
<!-- tooltips/ToolTipStyles.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Style>
     ToolTip { 
        fontFamily: "Arial"; 
        fontSize: 19; 
        fontStyle: "italic"; 
        color: #FF6699; 
        backgroundColor: #33CC99;
     }
  </mx:Style>

  <mx:Button id="b1" label="Click Me" toolTip="This Button does nothing."/>

</mx:Application>
The executing SWF file for the previous example is shown below:

To use the StyleManager class to set ToolTip styles, apply a style to the ToolTip type selector with the setStyle() method, as the following example shows:

<?xml version="1.0"?>
<!-- tooltips/ToolTipStyleManager.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="setToolTipStyle()">

  <mx:Script><![CDATA[
     import mx.styles.StyleManager;
     private function setToolTipStyle():void {
        StyleManager.getStyleDeclaration("ToolTip").setStyle("fontStyle","italic");
        StyleManager.getStyleDeclaration("ToolTip").setStyle("fontSize","19");
        StyleManager.getStyleDeclaration("ToolTip").setStyle("fontFamily","Arial");
        StyleManager.getStyleDeclaration("ToolTip").setStyle("color","#FF6699");
        StyleManager.getStyleDeclaration("ToolTip").setStyle("backgroundColor","#33CC99");
     }
]]></mx:Script>

  <mx:Button id="b1" label="Click Me" toolTip="This Button does nothing."/>

</mx:Application>
The executing SWF file for the previous example is shown below:

ToolTips use inheritable styles that you set globally. For example, you can set the fontWeight of ToolTips with the StyleManager by setting it on the global selector, as the following example shows:

<?xml version="1.0"?>
<!-- tooltips/ToolTipGlobalStyles.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="setToolTipStyle()">

  <mx:Script><![CDATA[
     import mx.styles.StyleManager;
     private function setToolTipStyle():void {
        StyleManager.getStyleDeclaration("global").setStyle("fontWeight","bold");
     }
]]></mx:Script>

  <mx:Button id="b1" label="Click Me" toolTip="This Button does nothing."/>

</mx:Application>
The executing SWF file for the previous example is shown below:

Styles set on the Application object typically apply to all UI objects. However, ToolTips do not inherit styles set on the Application object.

If you set the fontWeight property on the global selector, your change affects the text of many controls in addition to ToolTips, so be careful when using the global selector.

For a complete list of styles supported by ToolTips, see the Adobe Flex Language Reference. For more information on using styles, see Using Styles and Themes.

You can reskin ToolTip controls to give them an entirely new appearance. You can do this by using the ToolTipBorder programmatic skin or reskin them graphically. For an example of programmatically reskinning a ToolTip control, see Reskinning ToolTips.

Setting the width of ToolTips

You can set the width of the ToolTip box by changing the maxWidth property of the mx.controls.ToolTip class. This property is static so when you set it, you are setting it for all ToolTip boxes. You cannot set it on an instance of a ToolTip.

The maxWidth property specifies the maximum width in pixels for new ToolTips boxes. For example, the following line changes the maximum width of the ToolTip box to 100 pixels:

<?xml version="1.0"?>
<!-- tooltips/SetMaxWidth.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()">
  <mx:Script><![CDATA[
     import mx.controls.ToolTip;

     public function init():void {
        ToolTip.maxWidth = 100;
     }     

     public function createNewButton(event:MouseEvent):void {       
        var myButton:Button = new Button();
        myButton.label = "Create Another Button";
        myButton.toolTip = "Click this new button to create another button.";
        myButton.addEventListener(MouseEvent.CLICK, createNewButton);
        addChild(myButton);

     }
  ]]></mx:Script>
  <mx:Button id="b1" 
    label="Create Another Button" 
    click="createNewButton(event);" 
    toolTip="Click this button to create a new one."
  />
</mx:Application>
The executing SWF file for the previous example is shown below:

Flex wraps the text of a ToolTip onto multiple lines to ensure that the width does not exceed this value. If the text in the ToolTip box is not as wide as the maxWidth property, Flex creates a box only wide enough for the text to fit.

The default value of maxWidth is 300. If the value of maxWidth exceeds the width of the application, Flex clips the text in the ToolTip box.

Using ToolTip events

ToolTips trigger many events during their life cycle. These events are of type ToolTipEvent.

In addition to the type and target properties, the ToolTipEvent object references the ToolTip in its toolTip property. With a reference to the ToolTip, you can then access the ToolTip text with the text property.

To use events of type ToolTipEvent in your <mx:Script> blocks, you must import mx.events.ToolTipEvent class.

The following example plays a sound in response to the TOOL_TIP_SHOW event:

<?xml version="1.0"?>
<!-- tooltips/ToolTipsWithSoundEffects.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="init()">
  <mx:Script><![CDATA[
     import mx.events.ToolTipEvent;
     import flash.media.Sound;

     [Embed(source="../assets/sound1.mp3")]
     private var beepSound:Class;
     private var myClip:Sound;

     public function playSound():void {
        myClip.play();
     }
     private function myListener(event:ToolTipEvent):void {
        playSound();
     }
     private function init():void {
        myLabel.addEventListener(ToolTipEvent.TOOL_TIP_SHOW, myListener);
        myClip = new beepSound();
     }
  ]]></mx:Script>
  <mx:Label id="myLabel" toolTip="ToolTip" text="Mouse Over Me"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

Using ToolTips with NavBar controls

NavBar and TabBar subclasses (such as ButtonBar, LinkBar, and ToggleButtonBar) support ToolTips in their data providers. The data provider array can contain a toolTip field that specifies the toolTip for the navigation items.

The following example creates ToolTips for each of the navigation items:

<?xml version="1.0"?> 
<!-- tooltips/NavItemToolTips.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:ButtonBar>
     <mx:Object label="OK" toolTip="OK Button ToolTip"/>
     <mx:Object label="Cancel" toolTip="Cancel Button ToolTip"/>
  </mx:ButtonBar>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can use ToolTips on child elements in a component's data provider. The component recognizes those ToolTips and displays them accordingly. In the following example, the ToolTips are propagated up to the LinkBar:

<?xml version="1.0"?>
<!-- tooltips/DataProviderToolTips.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:VBox>
     <!-- Create a LinkBar control to navigate the ViewStack. -->
     <mx:LinkBar dataProvider="{vs1}" borderStyle="solid"/>
   
     <!-- Define the ViewStack and the three child containers. -->
     <mx:ViewStack id="vs1" borderStyle="solid" width="100%" height="150">
        <mx:Canvas id="search" label="Search" toolTip="Search Screen">
           <mx:Label text="Search Screen"/>
        </mx:Canvas>
        <mx:Canvas id="custInfo" label="Customer" 
           toolTip="Customer Info Screen">
           <mx:Label text="Customer Info"/>
        </mx:Canvas>
        <mx:Canvas id="accountInfo" label="Account" 
           toolTip="Account Info Screen">
           <mx:Label text="Account Info"/>
        </mx:Canvas>
     </mx:ViewStack>
  </mx:VBox>
</mx:Application> 
The executing SWF file for the previous example is shown below:

You can also set the value of the NavBar's toolTipField property to point to the field in the data provider that provides a ToolTip. The data provider in the following example defines ToolTips in the myToolTip field:

<?xml version="1.0"?>
<!-- tooltips/ToolTipFieldExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:ButtonBar toolTipField="myToolTip">
     <mx:Object label="OK" myToolTip="OK Button TooTip"/>
     <mx:Object label="Cancel" myToolTip="Cancel Button ToolTip"/>
  </mx:ButtonBar>
</mx:Application>
The executing SWF file for the previous example is shown below:

Adobe Flex 3 Help

Creating ToolTips

Setting styles in ToolTips

Setting the width of ToolTips

Using ToolTip events

Using ToolTips with NavBar controls