ToolTipManager クラスを使用すると、ツールヒントの基本的な機能（表示の遅延時間やツールヒントの無効化など）を設定できます。設定は、mx.managers パッケージに格納されます。ToolTipManager を使用するときは、このクラスを読み込む必要があります。また、ToolTipManager クラスの currentToolTip プロパティには、現在のツールヒントへの参照が含まれます。

ツールヒントの有効化と無効化

Flex アプリケーションのツールヒントは有効または無効にすることができます。ツールヒントを無効にすると、コンポーネントの toolTip プロパティが設定されているかどうかにかかわらず、可視コンポーネントの上にマウスポインタを重ねてもツールヒントボックスが表示されなくなります。

ツールヒントを有効または無効にするには、ToolTipManager の enabled プロパティを使用します。このプロパティを true に設定するとツールヒントが有効になり、false に設定するとツールヒントが無効になります。デフォルト値は true です。

次の例では、ユーザーが「Toggle ToolTips」ボタンをクリックしたときにツールヒントのオンとオフを切り替えます。

<?xml version="1.0"?>
<!-- tooltips/ToggleToolTips.mxml -->
<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>
前の例で実行する SWF ファイルは以下のとおりです。

遅延時間の設定

「遅延時間」とは、何かが発生するまでの経過時間を表す指標です。例えば、コンポーネント上にマウスポインタを移動すると、少し遅れてツールヒントが表示されます。ツールヒントを必要としないユーザーは、この間にマウスポインタを別の場所に移動して、テキストがポップアップ表示されるのを防ぐことができます。

ToolTipManager を使用すると、ツールヒントボックスが表示されるまでの時間や、マウスポインタをコンポーネント上に重ねたときにツールヒントを画面上に表示し続ける時間を設定できます。また、ツールヒント間の遅延を設定することもできます。

ToolTipManager の showDelay プロパティ、hideDelay プロパティおよび scrubDelay プロパティの値は、ActionScript のコードブロックで設定します。次の表は、遅延時間に関する ToolTipManager のプロパティとその説明です。

次の例では、Application コントロールの initialize イベントを使用して、ToolTipManager の初期値を設定します。

<?xml version="1.0"?>
<!-- tooltips/ToolTipTiming.mxml -->
<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 another thing"/>
  <mx:Button label="Click Me" toolTip="Click this Button to do the same thing"/>

</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

ツールヒントにおけるエフェクトの使用

ツールヒントには、Flex の標準エフェクトのほか、カスタムエフェクトを使用することもできます。ツールヒントが表示または非表示になったときにトリガされるエフェクトを定義するには、ToolTipManager の showEffect プロパティまたは hideEffect プロパティを設定します。

次の例では、フェードエフェクトを使用し、ユーザーがツールヒントのあるコンポーネントの上にマウスポインタを重ねたときにツールヒントがフェードインするようにします。

<?xml version="1.0"?>
<!-- tooltips/FadeInToolTips.mxml -->
<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."/>

</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

デフォルトでは、この例で使用されているフォントはフェードしません。エフェクトを実現するには、埋め込みフォントを使用する必要があります。埋め込みフォントの使用の詳細については、埋め込みフォントの使用を参照してください。

hideEffect イベントにフェードアウトエフェクトを設定した場合、ユーザーがそのエフェクトをトリガするには、マウスをコンポーネント上に重ねた状態で待機する必要があります。つまり、hideToolTip イベントは、ToolTip オブジェクトが非表示になる前にマウスポインタを別のコンポーネントに移動すると、トリガされません。

エフェクトの使用とカスタムエフェクトの定義の詳細については、ビヘイビアの使用を参照してください。

ダイナミックツールヒントテキストの使用

ツールヒントは、ユーザーに静的ヘルプテキストを表示するだけではありません。ツールヒントテキストをデータやコンポーネントのテキストにバインドすることもできます。これにより、ツールヒントをユーザーインターフェイスの一部として使用することが可能となり、ドリルダウン情報やクエリ結果など、ユーザーの操作に合わせてカスタマイズした、より有用なテキストを表示できます。

ツールヒントテキストの値を別のコントロールのテキストにバインドするには、中カッコ（{}）シンタックスを使用します。

次の例では、ユーザーがマウスポインタを Button コントロール上に重ねたときに、TextInput コントロールの値を Button コントロールのツールヒントテキストに挿入しています。

<?xml version="1.0"?>
<!-- tooltips/BoundToolTipText.mxml -->
<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>
前の例で実行する SWF ファイルは以下のとおりです。

この例では、ユーザーが TextInput ボックスに「fred@fred.com」と入力し、その後マウスポインタをボタンの上に重ねると、ツールヒントボックスに「Send e-mail to fred@fred.com」というメッセージが表示されます。

ツールヒントのダイナミックテキストを作成する別の方法として、toolTipShow イベントハンドラでツールヒントを取得して、text プロパティの値を変更する方法があります。次の例では、Button コントロールの toolTipShow イベントのリスナーとして、myToolTipChanger() メソッドを登録します。そのメソッドの中で、ToolTipManager.currentToolTip.text プロパティの値を実行時までわからない値に設定しています。

<?xml version="1.0"?>
<!-- tooltips/DynamicToolTipText.mxml -->
<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 {
        // Append ?myName=fred to your request string or pass the value of 
        // myName in to your application some other way.
        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>
前の例で実行する SWF ファイルは以下のとおりです。

toolTipShow イベントハンドラで現在のツールヒントのテキストを作成できるのは、初期状態でオブジェクトにツールヒントが設定されている場合のみです。例えば、上の例のボタンで toolTip プロパティの値が設定されていない場合、myToolTipChanger() メソッドが呼び出されてもツールヒントは表示されません。

Application.application.parameters オブジェクトの使用の詳細については、flashVars プロパティを使用した要求データの受け渡しを参照してください。

カスタムツールヒントの作成

ToolTipManager には、ツールヒントをプログラムから使用するためのメソッドが 2 つあります。createToolTip() メソッドは新しい ToolTip オブジェクトを作成し、destroyToolTip() メソッドは ToolTip オブジェクトを破棄します。ToolTip オブジェクトを作成する場合は、その他のオブジェクトと同様に、プロパティ、スタイル、イベントおよびエフェクトにアクセスしてカスタマイズできます。

createToolTip() メソッドのシグネチャを次に示します。

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

text パラメータは、ツールヒントの内容を定義します。x パラメータおよび y パラメータは、ツールヒントの x 座標および y 座標をアプリケーションコンテナに対して相対的に定義します。errorTipBorderStyle パラメータは、エラーヒントのポインタの位置を設定します。このパラメータはオプションです。createToolTip() メソッドでこの値を指定した場合、そのツールヒントはエラーヒントのスタイルになります。次の例は、エラーヒントの有効な値とポインタの位置を示します。

context パラメータは現在は使用されていません。

createToolTip() メソッドは、IToolTip インターフェイスを実装する新規 ToolTip オブジェクトを返します。このメソッドの戻り値をツールヒントにキャストしない方が効率的ですが、頻繁にキャストする必要があります。このキャストは次のいずれかの方法で行います。

• 次の例に示すように、as キーワードを使用します。

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

• 次の例に示すように、type(object) のキャストシンタックスを使用します。

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

これらのキャスト方法で異なるのは、キャストに失敗したときの動作のみです。

エラーヒントの使用の詳細については、エラーヒントの使用を参照してください。

ツールヒントは破棄されるまで表示されます。通常、一度に複数のツールヒントを表示するとユーザーが混乱するため、一度に表示するツールヒントは 1 つにしてください。

destroyToolTip() メソッドを使用すると、指定した ToolTip オブジェクトを破棄できます。destroyToolTip() メソッドのシグネチャを次に示します。

destroyToolTip(toolTip:IToolTip):void

toolTip パラメータは、破棄する ToolTip オブジェクトです。これは、createToolTip() メソッドによって返されたオブジェクトです。

次の例では、3 つの Button コントロールのある Panel コンテナにマウスポインタを重ねたときに表示されるカスタムツールヒントを作成します。各 Button コントロールには、マウスポインタをその特定のコントロールに重ねたときに表示されるそれぞれのツールヒントがあります。大きなツールヒントは、マウスポインタを Panel コンテナから離した場合のみ非表示になります。

<?xml version="1.0"?>
<!-- tooltips/CreatingToolTips.mxml -->
<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:Panel 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>
前の例で実行する SWF ファイルは以下のとおりです。

カスタムツールヒントは、IToolTip インターフェイスを実装する既存のコントロール（Panel コンテナや VBox コンテナなど）を拡張して作成することもできます。次の例では、IToolTip インターフェイスの新しい実装の基礎として Panel コンテナを使用します。

<?xml version="1.0"?>
<!-- tooltips/ToolTipComponents/PanelToolTip.mxml -->
<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"
>
    <mx:Script><![CDATA[
        [Bindable]
        public var bodyText:String = "heh";
    
        //  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>

アプリケーション内でカスタムツールヒントを作成するには、ターゲットコンポーネントの toolTipCreate イベントハンドラを受け取ります。イベントハンドラで、新しいツールヒントをインスタンス化し、そのプロパティを設定します。続いて、ToolTipEvent オブジェクトの toolTip プロパティを新しいツールヒントに指定します。

次の例では、アプリケーションの最初の 2 つのボタンが、CustomToolTips パッケージのカスタム PanelToolTip に使用されます。3 番目のボタンは、デフォルトのツールヒントを使用して 2 つのボタンの違いを示します。この例を実行するには、PanelToolTip.mxml ファイルを CustomToolTips という名前のサブディレクトリに保存します。

<?xml version="1.0"?>
<!-- tooltips/MainCustomApp.mxml -->
<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>
前の例で実行する SWF ファイルは以下のとおりです。

カスタムツールヒントの配置

ToolTipManager を使用してカスタムツールヒントを作成する場合、ツールヒントのステージ上の座標を指定できます。これを行うには、createToolTip() メソッドで新しいツールヒントの x パラメータと y パラメータの値を指定します。これらの座標はステージを基準とします。例えば、0,0 という値では、アプリケーションの左上隅にツールヒントが作成されます。

ツールヒントを配置する正確な座標は分からないけれども、ターゲットコンポーネント（ツールヒントの表示対象となるコンポーネント）を基準としてツールヒントを配置する必要があることがあります。このような場合、ターゲットコンポーネントの座標を使用して、これらの座標の値を計算できます。例えば、ツールヒントをコンポーネントの右に表示する場合、コンポーネントの x 座標、コンポーネントの幅、およびその他のオフセット値を加算した値に、ツールヒントの x 座標を設定します。

次の図は、この式の結果を示しています。

また、ツールヒントとターゲットコンポーネントを水平方向に並べて表示するには、ツールヒントの y 座標の値を、ターゲットコンポーネントの y 座標の値と同じ値に設定します。

ツールヒントの x 座標の計算に必要な値を取得する方法の 1 つに、イベントハンドラを使用する方法があります。イベントハンドラに渡されるイベントオブジェクトにより、ターゲットコンポーネントの x 座標と幅を取得できます。

次の例では、focusIn イベントハンドラを使用して現在のターゲットの x、y および width の各プロパティの値を取得し、それらの値を使用してツールヒントを配置しています。この場合、現在のターゲットは TextInput コントロールで、ツールヒントはそのコントロールから右に 10 ピクセルの位置に表示されます。

<?xml version="1.0"?>
<!-- tooltips/PlacingToolTips.mxml -->
<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>
前の例で実行する SWF ファイルは以下のとおりです。

上記の例では、コンテナの内側にないターゲットコンポーネント上にツールヒントが作成されます。ただし、多くの場合、コンポーネントは VBox や HBox などのレイアウトコンテナの内側にあります。このような環境では、イベントハンドラでアクセスする座標は、メインアプリケーションではなくコンテナが基準となります。ただし、ツールヒントを配置する場合、ToolTipManager はグローバル座標を必要とします。このため、ツールヒントは予期しない場所に配置されます。

これを回避するには、イベントハンドラで contentToGlobal() メソッドを使用して、座標をローカルからグローバルに変換します。このメソッドは、UIComponent のサブクラスのすべてのコンポーネントに含まれます。このメソッドは、ターゲットを囲むコンテナを基準とした単一の Point を引数として受け取り、ステージを基準とした Point を返します。

次の例では、TextInput コントロールの contentToGlobal() メソッドを呼び出して、コントロールの座標を VBox コンテナを基準とした座標からグローバル座標に変換しています。

<?xml version="1.0"?>
<!-- tooltips/PlacingToolTipsInContainers.mxml -->
<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>

    <!-- A ToolTip at the top level. -->
    <!-- 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 >
        <!-- A ToolTip inside a container. -->
        <!-- 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)"
        />  

        <!-- A ToolTip inside a container. -->
        <!-- 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>
前の例で実行する SWF ファイルは以下のとおりです。