このドキュメントでは、次のトピックについて説明します。
イメージリストコントロールは、リストビューコントロールやツリービューコントロールなどの特定のコントロールタイプに関連付けることができる、順序付けされたイメージのコンテナです。 イメージリストコントロールを使用すると、ディスクからイメージを毎回再ロードすることなく、コントロールの項目で効率的にイメージを再利用できます。 また、イメージはすべて互換性があります（同じサイズおよびカラー構成など）。
通常は、ADD アクションを使用してイメージリストコントロールを作成します。
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #IMGLST-1 TYPE = IMAGELIST PARENT = #DLG$WINDOW STYLE = 'LS' END-PARAMETERS GIVING *ERROR
イメージリストコントロールは、最大 2 つのイメージセットによって内部的に構成されます。その 1 つは大きいイメージ（通常は 32 x 32 ピクセル）で構成され、もう 1 つは小さいイメージ（通常は 16 x 16 ピクセル）で構成されます。
これらのどちらが内部的に作成されるかは、イメージリストコントロールの［大きいイメージ（L）］および［小さいイメージ（S）］の各 STYLE フラグによって決まります。 どちらのフラグも指定されていない場合、イメージリストコントロールの ITEM-W および ITEM-H の各属性値に基づいたイメージサイズで、単一のイメージセットが作成されます。 これらの両方の値がゼロの場合、小さいイメージが使用されます。
必要なイメージ（ビットマップまたはアイコン）ファイルに基づいて、イメージリストコントロールの子としてイメージコントロールを作成することにより、イメージリストにイメージを追加できます。
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #IMG-1 TYPE = IMAGE PARENT = #IMGLST-1 BITMAP-FILE-NAME = 'example.bmp' END-PARAMETERS GIVING *ERROR
デフォルトでは、SUCCESSOR 属性を使用して特定の位置に項目を挿入するよう指定されていない限り、イメージはリストの最後に追加されます。
イメージコントロールは、単一イメージコントロールと複数イメージコントロールの 2 つに分類できます。
単一イメージコントロールは、親イメージリストコントロールで使用されている各イメージセットに対し、単一のイメージを提供します。 つまり、イメージリストで大きいイメージと小さいイメージの両方を使用する場合、どちらに対してもこのイメージコントロールが使用されます。 単一イメージコントロールは、ビットマップまたはアイコンになります。
複数イメージコントロールは、その名前が示すとおり、親イメージリストコントロールに対し、（サイズごとに）複数のイメージを提供します。 複数イメージコントロールでは、アイコンではなくビットマップファイルを使用する必要があり、［合成イメージ（C）］STYLE フラグを設定して単一イメージコントロールと区別します。
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #IMG-1 TYPE = IMAGE PARENT = #IMGLST-1 STYLE = 'CsT' BITMAP-FILE-NAME = 'composite.bmp' END-PARAMETERS GIVING *ERROR
合成ビットマップ内のイメージ数は、親イメージリストコントロールで使用されている（最も小さい）イメージセット内のイメージの幅と高さ、およびビットマップのサイズから自動的に計算されます。 したがって、大きいイメージと小さいイメージの両方が使用されている場合、通常は、ビットマップの高さは 16 ピクセル、幅は 16 * N ピクセルになります。N はイメージコントロールに格納されているイメージ数です。 以下に、5 つのイメージが格納されている合成ビットマップの例を示します。
前のセクションの例では、［合成イメージ（C）］スタイルの他に［伸縮（S）］および［透過（T）］という 2 つのスタイルが指定されていました。 親イメージリストコントロール内でサイズの異なる複数のイメージセットを使用する場合、［伸縮（S）］スタイルを無条件に指定する必要があります。 例えば、大きいイメージも使用されている場合、以下のように、構成イメージに分割する前に、このスタイルフラグによって合成イメージが内部的に拡大／縮小されます。
［伸縮（S）］スタイルフラグを指定していない場合、以下のように、合成ビットマップは、分割前に拡大／縮小されずに背景色内に展開されることに注意してください。
この場合、5 つの大きいイメージは以下のように分割されます。
言うまでもなく、通常はこの結果は好ましくありません。
［透過（T）］スタイルフラグは、イメージが透過的にレンダリングされることを示します。ビットマップの背景色部分のピクセルはすべて描画されません。 背景色は、イメージコントロールの BACKGROUND-COLOUR-VALUE 属性および／または BACKGROUND-COLOUR-NAME 属性に必要な値を設定することにより、明示的に指定できます。 そうしない場合、つまり、上記の例のように背景色を指定しない場合は、ビットマップの最初（つまり、左上）のピクセルの色が背景色とみなされます。
当然ながら、［伸縮（S）］および［透過（T）］の各スタイルフラグは、非合成イメージに適用できます。
複数イメージコントロールのソースとして使用できない点の他にも（上記参照）、アイコンは 2 つの大きな点でビットマップと異なっています。 1 つ目は、単一のアイコン（.ICO）ファイルに、同じアイコンのサイズ違いのバージョンを複数格納できるという点です。 したがって、Natural で大きいイメージが必要とされ、ソースがアイコンファイルの場合、ファイル内の他のアイコンを拡大／縮小して作り出すのではなく、アイコンファイルに大きいアイコンが定義されていればそのアイコンが使用されます。 同様に、Natural で小さいイメージが必要とされ、ソースがアイコンファイルの場合、アイコンファイルに小さいアイコンが定義されていればそのアイコンが使用されます。 一方、ビットマップファイルには複数のイメージを格納できないため、イメージリストで大きいイメージと小さいイメージの両方が必要とされる場合、これらの 2 つのイメージのどちらかは（通常は大きいイメージ）、前のセクションで説明したように、もう 1 つのイメージから作り出す必要があります。
2 つ目は、アイコンには通常、イメージ内のどのピクセルを透過（つまり、描画しない）にするかを指定する、イメージマスクと呼ばれる白黒のビットマップが組み込まれているという点です。 これにより、Natural がイメージをアイコンファイルからロードするときに、イメージコントロールの
BACKGROUND-COLOUR-NAME 属性が DEFAULT に設定され（または指定されていない）、かつ、［伸縮（S）］スタイルフラグの指定なしで［透過（T）］スタイルフラグが指定されている場合、ビットマップからイメージをロードする場合に最初のピクセルと同じ色のピクセルがすべて透過的にレンダリングされるのとは異なり（上記参照）、アイコンの透過マスクが使用されます。
（デフォルト以外の）背景色が明示的に指定されている場合、アイコンまたはビットマップが使用されているかどうかにかかわらず、その色のすべてのピクセルが透過とみなされます。 この場合、アイコンの透過マスクは無視されます。アイコンが拡大／縮小される場合も同様です。
したがって、大きいイメージと小さいイメージの両方が必要な場合、単一の合成ビットマップに基づいた複数イメージコントロールではなく、大小それぞれのイメージが格納されている複数のアイコンファイルに基づいた単一イメージコントロールを使用することをお勧めします。 アイコン（.ICO）ファイルを個別に使用する長所は、小さいイメージと大きいイメージ（ファイル内に両方とも格納されていると想定）を使って異なる詳細レベルで表示できる点です。 主な短所は、通常、複数のアイコンファイルからイメージをロードするには、単一の合成ビットマップファイルからロードするより時間がかかることです。
イメージリストのイメージをコントロール（ツリービューコントロールやリストビューコントロールなど）で使用できるようにするには、まずイメージリストをコントロールに関連付ける必要があります。 この関連付けを実現するには、イメージリストコントロールのハンドルをホストコントロールの
IMAGE-LIST 属性に割り当てます。 次に例を示します。
#LV-1.IMAGE-LIST := #IMGLST-1
イメージリストの設定後は、イメージリストコントロールのイメージをコントロールの項目で使用できます。
特定の項目（リストビュー項目やツリービュー項目など）の親コントロールのイメージリストにある、特定のイメージを使用するには、以下の 2 つの方法のいずれかで使用するイメージを指定する必要があります。
項目の IMAGE 属性をイメージコントロールのハンドルに設定し、（必要に応じて）項目の IMAGE-INDEX 属性をイメージコントロール内の必要なイメージの相対オフセット（ゼロから始まる）に設定する。 イメージコントロールに含まれているイメージが 1 つのみの場合、イメージインデックスを指定する必要はありません。 指定するイメージは、項目のコンテナに割り当てられているイメージリストコントロールに属している必要があります。
項目の IMAGE-INDEX 属性をイメージリスト内のイメージの順序番号（1：最初のイメージリストコントロール、2：2 番目のイメージ、など）に設定する。 この場合、項目の IMAGE 属性は、指定しないか、またはデフォルト値の NULL-HANDLE に設定する必要があります。
最初の方法（相対インデックス）では、インデックスにラップアラウンドが使用されます。 したがって、イメージコントロールに N 個のイメージが含まれているとすると、イメージインデックス 0 はイメージコントロールの最初のイメージを指し、イメージインデックス N - 1 は最後のイメージを指します。そして、イメージインデックス N はまた最初のイメージを指す、のように続きます。 そのため、イメージコントロールにイメージが 1 つしか含まれていない場合、ラップアラウンドのために、イメージの相対インデックスは（指定しても）まったく効果がありません。常に最初（で唯一）のイメージが使用されます。
2 つ目の方法（絶対インデックス）では、イメージインデックスにラップアラウンドは使用されません。この場合、インデックスには 1 からイメージリスト内のイメージ数（この値を含む）までの範囲の値を指定する必要があります。 指定した値がこの範囲にない場合、その項目にイメージは表示されません。
IMAGE-INDEX 属性はイメージコントロールにも適用できることに注意してください。 この場合、この属性は読み取り専用で、親イメージリストコントロール内のイメージコントロールの最初のイメージのオフセット（ゼロから始まる）を返します。
相対インデックスを使用する長所には、指定したイメージへの参照が Natural によって追跡され（ダイアログエディタ内またはランタイム時）、イメージコントロールまたはイメージリストの位置に対する変更が自動的に反映される点があります。 ただし、実際には、イメージリストコントロールで単一の合成イメージ（つまり、複数イメージ）コントロールが使用され、かつ、ランタイム時にイメージが変更されないような場合は、絶対インデックスの使用がおそらく最も便利です。
1 つのイメージのバリエーションを複数提供できることが望ましい場合があります。 例えば、フォルダを表す項目に対して表示するイメージでは、フォルダがアクティブであることを示すためにイメージの変更が必要な場合があります。 フォルダのイメージとアクティブなフォルダのイメージを用意するのではなく、最初のフォルダのイメージのみを用意し、アクティブな状態を示すときは "アクティブな" シンボルのみを含む 2 つ目のイメージを最初のイメージに重ね合わせる方が便利です。 このようなイメージは、基本イメージと区別するためにオーバーレイイメージと呼ばれます。
オーバーレイイメージは、ホストコントロールの IMAGE-LIST 属性で指定されている、基本イメージの表示に使用するイメージリストと同じイメージリスト内に格納します。 したがって、オーバーレイイメージのサイズは基本イメージと同じですが、下にあるイメージが見えるように、常に透過的にレンダリングします。
項目でオーバーレイイメージを使用するには、項目の OVERLAY 属性および／または OVERLAY-INDEX 属性に値を指定する必要があります。 これらの属性は、それぞれ基本イメージの IMAGE 属性および IMAGE-INDEX 属性と同様に使用されます（上記参照）。
技術的な理由により、オーバーレイイメージとして使用するイメージは "事前登録" する必要があります。 Natural では、イメージリストコントロールの "O"（オーバーレイ）STYLE を設定すると、事前登録されます。 ただし、オーバーレイコントロールをスタティックに定義すると、このスタイルはダイアログエディタによって自動的に設定されます。 このスタイルの有無によって、基本イメージとオーバーレイイメージは区別されます。 したがって、OVERLAY 属性を指定すると、このスタイルを持つイメージコントロールのみを参照できます。一方、IMAGE 属性を指定すると、このスタイルを持たないイメージコントロールのみを参照できます。 絶対インデックス（上記参照）が使用されている場合、IMAGE-INDEX はオーバーレイイメージを参照できます（基本イメージとしては "誤用" です）。 ただし、同様に OVERLAY-INDEX 属性を使用して基本イメージを参照しようとすると、エラーになります（オーバーレイイメージは表示されません）。
イメージリストに定義できるオーバーレイイメージの数は、Windows によって制限が設定されています。 この制限数は現時点では 15 です。 合成オーバーレイイメージコントロールを使用する場合、合成ビットマップ内のサブイメージはこれとは別にカウントされます。
例として、以下のように、個別のオーバーレイイメージを含む合成イメージに基づいたイメージコントロールを作成します。
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #IMG-2 TYPE = IMAGE PARENT = #IMGLST-1 STYLE = 'COs' BITMAP-FILE-NAME = 'overlays.bmp' END-PARAMETERS GIVING *ERROR
その後、以下のコードを実行すると、（例えば）合成ビットマップの 2 番目のオーバーレイイメージを使用して、リストビュー項目を作成できます。
PROCESS GUI ACTION ADD WITH PARAMETERS TYPE = LISTVIEWITEM PARENT = #LV-1 STRING = 'Item with overlay' IMAGE = #IMG-1 IMAGE-INDEX = 3 OVERLAY = #IMG-2 OVERLAY-INDEX = 1 END-PARAMETERS GIVING *ERROR
上記の例のリストビュー項目では、基本イメージとして COMPOSITE.BMP の 4 番目のイメージが、オーバーレイイメージとして OVERLAYS.BMP の 2 番目のイメージが使用されます（すでに説明したとおり、イメージの相対インデックスはゼロから始まります）。 リストビュー項目は匿名で（つまり、明示的に HANDLE-VARIABLE 属性値を指定しないで）作成されることに注意してください。
使用中であっても、イメージコントロールを変更できます。 次に例を示します。
#IMG-1.BITMAP-FILE-NAME := 'new.bmp'
変更されたイメージコントロールのイメージを明示的に（つまり、相対インデックスを使用して）参照する各項目は、Natural によって追跡され、自動的に更新および再描画されます。 ただし、絶対インデックスが使用されている場合、変更されたイメージコントロールのイメージを暗黙的に参照していても、対応する項目は更新されません。
DELETE アクションを使用してイメージコントロール全体を削除することにより、イメージリストからイメージを削除できます。 次に例を示します。
PROCESS GUI ACTION DELETE WITH #IMG-1 GIVING *ERROR
削除されたイメージコントロールのイメージを明示的に（つまり、相対インデックスを使用して）参照している項目はすべて、イメージがないことを表すために自動的に更新および再描画されます。
ただし、絶対インデックスが使用されている場合、自動更新は行われません。 例えば、3 つの単一イメージコントロールを含むイメージリストコントロールと、これらの 3 つのイメージを絶対インデックスを使用して参照する項目があるとします。 2 番目のイメージコントロールを削除すると、2 番目のイメージを参照していた項目が 3 番目のイメージを参照するようになり、3 番目のイメージを参照していた項目は参照範囲から "はみでて"、何も参照しなくなります。 なお、これらの項目を含むコントロールでは、変更を反映するための再描画は自動的には行われません。
また、DELETE-CHILDREN アクションを使用してイメージリストのイメージを一度にすべて削除することもできます。
PROCESS GUI ACTION DELETE-CHILDREN WITH #IMGLST-1 GIVING *ERROR
これは、イメージリストの各イメージを個別に削除するのと同じことです。
合成イメージ（つまり、複数イメージ）コントロール内のイメージは個別に削除できないことに注意してください。
イメージリストコントロールは、使用中であっても、必要がなくなれば削除できます。 次に例を示します。
PROCESS GUI ACTION DELETE WITH #IMGLST-1 GIVING *ERROR
イメージリストコントロールを使用していたコントロールはすべて適切に更新されます。これらのコントロールの IMAGE-LIST 属性は自動的に NULL-HANDLE にリセットされます。
