List コントロールでは、アイテムを垂直方向に並べて表示します。List コントロールの機能は、HTML のフォームエレメントである SELECT に似ています。多くの場合、リストのすべてのアイテムにアクセスできるように垂直スクロールバーが表示されます。オプションの水平スクロールバーは、リストアイテムが水平方向に収まらない場合に、ユーザーがアイテムを表示するために使用します。ユーザーはリストからアイテムを選択できます。複数選択も可能です。

詳細については、『Adobe Flex リファレンスガイド』を参照してください。

次の図は、List コントロールです。

List コントロールのサイズ設定

horizontalScrollPolicy="on" に指定した場合、List コントロールのデフォルトの幅は変化しませんが、それでも表示される最も幅広なラベルが収まるだけの幅はあります。horizontalScrollPolicy="on" に設定して、List コントロールのピクセル幅を指定した場合は、次の例のように、measureWidthOfItems() メソッドを使用してスクロールバーの右端の位置がコンテンツの右端と合うことを確認できます。5 ピクセルを追加することで、テキストの右端の文字が正しく表示されるようになります。

<mx:List id="li2" 
    width="200" horizontalScrollPolicy="on"
    maxHorizontalScrollPosition="{li2.measureWidthOfItems() - li2.width +5}"
>

上記の行では、スクロールバーの右端の位置が、List コントロールの右端近くにある測定された最も長いリストアイテムの末尾になるようにしています。ただしこの方法を使用すると、アプリケーションの効率性が下がる場合があるため、明示的にサイズを設定したほうがよいこともあります。

リスト、および ListBase クラスのすべてのサブクラスは、スタイルまたはデータプロバイダが変化した際にサイズが決まります。

width プロパティの値を最も長いラベルの幅よりも小さくなるように設定して、horizontalScrollPolicy="off" に指定した場合、コントロールの幅を超えるラベルは切り取られます。

List コントロールの作成

List コントロールの定義には <mx:List> タグを使用します。MXML の他の場所（別のタグまたは ActionScript ブロック）のコンポーネントを参照する場合は、id 値を指定します。

List コントロールではリストデータプロバイダを使用します。詳しくは、データプロバイダおよびコレクションの使用を参照してください。

List コントロールのデータを指定するには、コントロールの dataProvider プロパティを使用します。ただし dataProvider は List コントロールのデフォルトのプロパティであるため、<mx:List> タグの <mx:dataProvider> 子タグを指定する必要はありません。静的な List コントロールを作成する最も簡単な方法では、単に <mx:String> タグをコントロールの本体内部に配置します。これは、Flex では次の例のように、複数のタグが自動的にストリングの配列として解釈されるからです。

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

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

この例で使用されるデータはインライン静的データなので、ArrayCollection オブジェクト内に明示的にラップする必要はありません。ただし、変化する可能性があるデータを扱う場合は、常にコレクションを明示的に指定するのが適切です。詳しくは、データプロバイダおよびコレクションの使用を参照してください。

List コントロールのアイテムのインデックスはゼロベースです。つまり、0、1、2、...、, n-1 の値で、n はアイテムの総数です。 アイテムの値はラベルテキストです。

通常、List コントロールに対するユーザーの操作はイベントを使用して処理します。次のコード例では、List コントロールに change イベントのハンドラを追加します。Flex は、ユーザーの操作によってコントロールの値が変化したときに mx.ListEvent.CHANGE イベントをブロードキャストします。

<?xml version="1.0"?>
<!-- dpcontrols/ListChangeEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            import flash.events.Event;

            public function changeEvt(event:Event):void {
                forChange.text=event.currentTarget.selectedItem.label + " " +
                event.currentTarget.selectedIndex;
            }
        ]]>
    </mx:Script>

    <mx:List width="35" change="changeEvt(event)"> 
        <mx:Object label="AL" data="Montgomery"/>
        <mx:Object label="AK" data="Juneau"/>
        <mx:Object label="AR" data="Little Rock"/>
    </mx:List>
    <mx:TextArea id="forChange" width="150"/>
</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

この例では、List コントロールの selectedItem プロパティおよび selectedIndex プロパティをイベントハンドラで使用しています。change イベントが発生するたびに、コントロールで選択されたアイテムのラベルとアイテムのインデックスで TextArea コントロールが更新されます。

イベントハンドラに渡されるオブジェクトの target プロパティには、List コントロールへの参照が設定されています。イベントの currentTarget プロパティを使用すると、コントロールのすべてのプロパティを参照できます。currentTarget.selectedItem フィールドには選択されたアイテムのコピーが設定されます。ストリングの配列を使用して List コントロールを作成した場合、currentTarget.selectedItem フィールドにはストリングが設定されます。オブジェクトの配列を使用して作成した場合は、currentTarget.selectedItem フィールドには選択されたアイテムに対応するオブジェクトが設定されます。したがって、この場合、currentTarget.selectedItem.label は選択されたアイテムのラベルフィールドを参照します。

ラベル関数の使用

List コントロールにラベル関数を渡して、コントロールに表示するテキストを決定するロジックを使用できます。ラベル関数には次のシグネチャが必要です。

labelFunction(item:Object):String

Label コントロールによって渡される item パラメータには、リストアイテムオブジェクトが含まれます。関数は List コントロールに表示されるストリングを返す必要があります。

次の例では、List コントロールにアイテムを表示するために、label フィールドおよび data フィールドの値を組み合わせる関数を使用しています。

<?xml version="1.0"?>
<!-- dpcontrols/ListLabelFunction.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
    <mx:Script><![CDATA[
        public function myLabelFunc(item:Object):String {
            return item.data + ", " + item.label; 
        }
    ]]></mx:Script>

    <mx:ArrayCollection id="myDP">
        <mx:source>
            <mx:Object label="AL" data="Montgomery"/>
            <mx:Object label="AK" data="Juneau"/>
            <mx:Object label="AR" data="Little Rock"/>
        </mx:source>
    </mx:ArrayCollection>       

    <mx:List dataProvider="{myDP}" labelFunction="myLabelFunc"/>
</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

この例を使用すると、次のような List コントロールが作成されます。

データヒントの表示

データヒントはツールヒントに似ていて、List コントロール内の行の上にマウスポインタを移動させるとテキストが表示されます。List コントロール内のテキストで長さがコントロールの幅を超えるものは、右側が切り取られるか、コントロールにスクロールバーがある場合はスクロールして表示することになります。データヒントを使用すると、マウスポインタをセルに移動させたときに、切り取られたテキストを含むテキスト全体が表示されるので、この問題を解決できます。データヒントは有効にすると、データが切り取られたフィールドにのみ表示されます。データヒントを表示するには、List コントロールの showDataTips プロパティを true に設定します。

showDataTips プロパティのデフォルトの動作では、ラベルのテキストが表示されます。ただし、dataTipField プロパティおよび dataTipFunction プロパティを使用して、データヒントの表示内容を変更することもできます。dataTipField プロパティの機能は labelField プロパティに似ています。このプロパティにはデータプロバイダのフィールド名を指定して、そのフィールドを列のセルのデータヒントとして使用します。dataTipFunction プロパティの機能は labelFunction プロパティに似ています。このプロパティには、リストアイテムに対して表示するデータヒントのストリングを指定します。

次の例では、List コントロールの showDataTips プロパティを設定しています。

<mx:List id="myList" dataProvider="{myDP}" width="220" height="200" showDataTips="true"/>

この例を使用すると、次のような List コントロールが作成されます。

スクロールヒントの表示

スクロールヒントは、ユーザーがリストをスクロールするのに合わせて、リストのどのアイテムを表示しているかという情報をユーザーに示すために使用します。このヒントはユーザーがスクロールしたときにのみ表示され、スクロールバーにマウスを合わせただけでは表示されません。スクロールヒントは、ライブスクロールが無効になっている（liveScrolling プロパティが false に設定されている）場合に、スクロールサムを離すまでスクロールが発生しないようにできるため便利です。showScrollTips プロパティのデフォルト値は false です。

showScrollTips プロパティを設定すると、デフォルトでは、一番上の表示アイテムのインデックス番号が表示されます。scrollTipFunction プロパティを使用すると、スクロールヒントに表示する内容を指定できます。scrollTipFunction プロパティは、labelFunction プロパティと同じように動作します。このプロパティには、リストアイテムに対して表示するスクロールヒントのストリングを指定する関数を設定します。ただし、スクロールヒントの内容を取得するためにサーバーにアクセスすることは望ましくありません。

次の例では、HorizontalList コントロールの showScrollTips プロパティと scrollTipFunction プロパティを設定しています。このコントロールは、標準の List コントロールと同じプロパティとメソッドを多数共有しています。HorizontalList コントロールについて詳しくは、HorizontalList コントロールを参照してください。scrollTipFunction プロパティには、現在表示されているリストアイテムの description プロパティの値を取得する関数を指定しています。

<mx:HorizontalList id="list" dataProvider="{album.photo}" width="100%"
    itemRenderer="Thumbnail" columnWidth="108" height="100"
    selectionColor="#FFCC00" liveScrolling="false" showScrollTips="true"
    scrollTipFunction="scrollTipFunc"
    change="currentPhoto=album.photo[list.selectedIndex]"/>

このコードでは、次の HorizontalList コントロールが作成されます。

List コントロール行のテキストの垂直方向の整列

verticalAlign スタイルを使用すると、List のテキストの表示位置を行の垂直方向の上揃え、中央揃え、下揃えのいずれかに設定できます。デフォルト値は top です。値として、middle または bottom も設定できます。

次の例では、List コントロールの verticalAlign プロパティを bottom に設定します。

<mx:List id="myList" dataProvider="{myDP}" width="220" height="200" verticalAlign="bottom"/>

行の高さの調整と List のテキストの折り返し

variableRowHeight プロパティを使用すると、List コントロールの行の高さを内容に合わせて変えることができます。デフォルト値は false です。variableRowHeight プロパティを true に設定すると、rowHeight プロパティの設定が無効になり、rowCount プロパティは読み取り専用になります。

次の例では、List コントロールの variableRowHeight プロパティを true に設定します。

<mx:List id="myList" dataProvider="{myDP}" width="220" height="200" variableRowHeight="true"/>

wordWrap プロパティを variableRowHeight プロパティと組み合わせて使用すると、List の行の幅よりテキストが長い場合にテキストを折り返して複数行で表示できます。

次の例では、wordWrap プロパティおよび variableRowHeight プロパティを true に設定します。

<mx:List id="myList" dataProvider="{myDP}" width="220" height="200" variableRowHeight="true" wordWrap="true"/>

このコードでは、次の List コントロールが作成されます。

List コントロールの行の色の切り替え

alternatingItemColors スタイルプロパティを使用すると、List コントロールの各行の色を定義する配列を指定できます。配列には 2 色以上を指定する必要があります。配列で指定した色がすべて使用された後は、1 番目の色に戻って同じ配色が繰り返されます。

次の例では、明るい青を表す #66FFFF と灰色がかった青を表す #33CCCC の 2 項目で構成される配列を定義しています。したがって、List コントロールの行は、この 2 色を繰り返し使用して表示されます。3 色の配列を指定すれば、行は 3 色を繰り返し使用することになります。

<mx:List alternatingItemColors="[#66FFFF, #33CCCC]".../ > 

カスタムアイテムレンダラーの使用

アイテムレンダラーは、List コントロールのデータアイテムを表示するオブジェクトです。カスタムアイテムレンダラーを使用する最も簡単な方法は、itemRenderer プロパティの値として MXML コンポーネントを指定することです。アイテムレンダラーとして MXML コンポーネントを使用すると、複数のレベルのコンテナおよびコントロールを含めることができます。カスタムアイテムレンダラーとして ActionScript クラスを使用することもできます。カスタムアイテムレンダラーについて詳しくは、アイテムレンダラーとアイテムエディタの使用を参照してください。

次の例は itemRenderer プロパティを FancyCellRenderer という MXML コンポーネントに設定しています。また、MXML コンポーネントの高さがデフォルトの行の高さより大きくなるので、variableRowHeight プロパティを true に設定します。

<mx:List id="myList1" dataProvider="{myDP}" width="220" height="200" itemRenderer="FancyItemRenderer" variableRowHeight="true"/>

List コントロールへのアイコンの指定

次の例のように、各 List アイテムと一緒に表示するアイコンを指定できます。

<?xml version="1.0"?>
<!-- dpcontrols/ListIcon.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
   <mx:Script>
      <![CDATA[
         [Embed(source="assets/radioIcon.jpg")] 
         public var iconSymbol1:Class; 
         [Embed(source="assets/topIcon.jpg")] 
         public var iconSymbol2:Class; 
      ]]>
   </mx:Script>

   <mx:List iconField="myIcon"> 
      <mx:dataProvider>
         <mx:Array>
            <mx:Object label="AL" data="Montgomery" myIcon="iconSymbol1"/>
            <mx:Object label="AK" data="Juneau" myIcon="iconSymbol2"/>
            <mx:Object label="AR" data="Little Rock" myIcon="iconSymbol1"/>
         </mx:Array>     
      </mx:dataProvider>
   </mx:List>
</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

この例では、iconField プロパティを使用して、アイコンを格納する各アイテムのフィールドを指定しています。また、Embed メタデータを使用してアイコンを読み込んでから、List コントロール定義で参照しています。

iconFunction プロパティを使用して、アイコンを決定する関数を指定することもできます。この方法は、labelFunction プロパティを使用してラベルテキストを決定する関数を指定する方法とほぼ同じです。アイコン関数には次のシグネチャが必要です。

iconFunction(item:Object):Class

Label コントロールによって渡される item パラメータには、リストアイテムオブジェクトが含まれます。関数は List コントロールに表示されるアイコンのクラスを返す必要があります。

次の例で表示される List コントロールでは、iconFunction プロパティを使用して、リストの各アイテムに対して表示するアイコンを決定します。

<?xml version="1.0"?>
<!-- dpcontrols/ListIconFunction.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
   <mx:Script>
      <![CDATA[   
         // Embed icons.
         [Embed(source="assets/radioIcon.jpg")] 
         public var pavementSymbol:Class; 
         [Embed(source="assets/topIcon.jpg")] 
         public var normalSymbol:Class;   
      
         // Define data provider.
         private var myDP: Array;
         private function initList():void {
            myDP = [
               {Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
               {Artist:'Pavarotti', Album:'Twilight', Price:11.99},
               {Artist:'Other', Album:'Other', Price:5.99}];
   
            list1.dataProvider = myDP;
         }
   
         // Determine icon based on artist. Pavement gets a special icon. 
         private function myiconfunction(item:Object):Class{
            var type:String = item.Artist;
            if (type == "Pavement") {
               return pavementSymbol;
            } 
            return normalSymbol;       
         }
      ]]>
   </mx:Script>
   
   <mx:VBox >
      <mx:List id="list1" initialize="initList()" labelField="Artist" 
         iconFunction="myiconfunction" />
   </mx:VBox>
</mx:Application>
前の例で実行する SWF ファイルは以下のとおりです。

List コントロールのユーザー操作

ユーザーは、個々のリストアイテムを選択するにはアイテムをクリックします。複数のアイテムを選択するには Ctrl キーや Shift キーを押しながらアイテムをクリックします（複数選択を可能にするには、allowMultipleSelection プロパティを true に設定する必要があります）。

マウスやキーボードを使用してアイテムの選択操作が行われるたびに、change イベントがブロードキャストされます。マウスの操作では、マウスボタンを離すと List コントロールからイベントがブロードキャストされます。

allowDragSelection プロパティを true に設定した場合、ユーザーが 1 つまたは複数の行の上でマウスボタンを押し、そのマウスボタンを押したままマウスをコントロール外へドラッグして、マウスを上下に動かすと、コントロールが上下にスクロール表示されます。

List コントロールでは、一度に表示できるレコード数のアイテムを表示します。10 行の List コントロールに表示されるデータ内で PageDown キーを押すと、0 ～ 9、9 ～ 18、18 ～ 27 番目のレコードが順に表示されます。必ず 1 つのアイテムが前後のページで重複することになります。

List コントロールでは次のキーボード操作ができます。