Palm OS Programmer's API Reference/14の変更点

• 追加された行はこのように表示されます。
• 削除された行はこのように表示されます。

{{div_begin}}
[[←　13 章に戻る|Palm OS Programmer's API Reference/13]]　[[↑トップへ|Palm OS Programmer's API Reference]]　[[15 章に進む　→|Palm OS Programmer's API Reference/15]]
{{div_end}}

{{div_begin style="margin-bottom:-10px"}}
!!!14 リスト
{{div_end}}

{{div_begin "style='position:absolute;right:0px;font-size:70%;margin-right:15px;margin-top:15px;width:250px;'"}}
*{{goto List Data Structures,リスト データ構造体}}
**{{goto ListAttrType,ListAttrType}}
**{{goto ListType,ListType}}
*{{goto List Resources,リスト リソース}}
*{{goto List Functions,リスト関数}}
**{{goto LstDrawList,LstDrawList}}
**{{goto LstEraseList,LstEraseList}}
**{{goto LstGetNumberOfItems,LstGetNumberOfItems}}
**{{goto LstGetSelection,LstGetSelection}}
**{{goto LstGetSelectionText,LstGetSelectionText}}
**{{goto LstGetTopItem,LstGetTopItem}}
**{{goto LstGetVisibleItems,LstGetVisibleItems}}
**{{goto LstHandleEvent,LstHandleEvent}}
**{{goto LstMakeItemVisible,LstMakeItemVisible}}
**{{goto LstNewList,LstNewList}}
**{{goto LstPopupList,LstPopupList}}
**{{goto LstScrollList,LstScrollList}}
**{{goto LstSetDrawFunction,LstSetDrawFunction}}
**{{goto LstSetHeight,LstSetHeight}}
**{{goto LstSetListChoices,LstSetListChoices}}
**{{goto LstSetPosition,LstSetPosition}}
**{{goto LstSetSelection,LstSetSelection}}
**{{goto LstSetTopItem,LstSetTopItem}}
*{{goto Application-Defined Functions,アプリケーション定義関数}}
**{{goto ListDrawDataFuncType,ListDrawDataFuncType}}
{{div_end}}

{{div_begin "style='position:relative;padding:0px;padding-right:5px;padding-left:10px;margin-right:250px;margin-top:20px;width:auto;border-right:dotted;border-right-width:2px;border-right-color:silver;'"}}
この章ではフィールド オブジェクトについて以下のことを説明します。
*{{goto List Data Structures,リスト データ構造体}}
*{{goto List Resources,リスト リソース}}
*{{goto List Functions,リスト関数}}
*{{goto Application-Defined Functions,アプリケーション定義関数}}

ヘッダファイル {{span style='color:blue;font-family:monospace;',List.h}} がこの章で説明する API を宣言しています。リストについての追加情報は ''Palm OS Programmer's Companion, vol. I'' の[[「リスト」|Palm OS Programmer's Companion Volume I/4-8]]を参照してください。

!!{{anchor List Data Structures}}リスト データ構造体 {{goto top,^TOP^}}

!{{anchor ListAttrType}}ListAttrType 構造体 {{goto top,^TOP^}}

'''目的'''

{{span style='color:blue;font-family:monospace;',ListAttrType}} ビット フィールドはリストの可視特性を定義します。

'''Prototype'''
 typedef struct {
 	UInt16 usable:1;
 	UInt16 enabled:1;
 	UInt16 visible:1;
 	UInt16 poppedUp:1;
 	UInt16 hasScrollBar:1.
 	UInt16 search:1;
 	UInt16 reserved:2;
 } ListAttrType;

'''フィールド'''
*{{span style='color:blue;font-family:monospace;',usable}}
**リストを使用可能にするためにセットします。セットされていないと、リストは現在のアプリケーション インターフェイスの一部として扱われず、画面にも表示されません。
*{{span style='color:blue;font-family:monospace;',enable}}
**使用しません。
*{{span style='color:blue;font-family:monospace;',visible}}
**リスト オブジェクトを描画するときにセットし、リスト オブジェクトが消去されるときにはクリアされます。
*{{span style='color:blue;font-family:monospace;',poppedUp}}
**選択肢がポップアップ ウィンドウに表示されるよう指示するためにセットします。この属性はセットされ、内部的にクリアされます。
*{{span style='color:blue;font-family:monospace;',hasScrollBar}}
**リストがスクロール バーを持つように指示するためにセットします。
*{{span style='color:blue;font-family:monospace;',search}}
**インクリメンタル サーチを可能にするためにセットします。インクリメンタル サーチが可能な場合、リストが表示されているときにユーザは 5 文字までの入力を行うことでリストをナビゲートすることができます。リストは、入力された文字に一致する最初のリスト アイテムが表示されるようにスクロールします。この機能はポップアップ リストに対してと、リストがソートされていてリスト マネージャがリスト アイテムを使用可能な（つまり、{{goto LstSetListChoices,LstSetListChoices()}} に {{span style='color:blue;font-family:monospace;',NULL}} を渡さない）場合にのみ機能します。
*{{span style='color:blue;font-family:monospace;',reserved}}
**システムが使用するために予約されています。


!{{anchor ListType}}ListType 構造体 {{goto top,^TOP^}}

'''目的'''

{{span style='color:blue;font-family:monospace;',ListType}} 構造体は以下のように定義されています。

//----
//{{span style='color:red;font-weight:bold;', WARNING!!!}} PalmSource 社（訳者注: 現 ACCESS 社）は、{{span style='color:blue;font-family:monospace;',ListType}} 構造体に対して下位互換をサポートまたは提供していません。決してこの構造体メンバに直接アクセスしないでください。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。
//----
::{{span style='color:red;font-weight:bold;', WARNING!!!}}
:::PalmSource 社（訳者注: 現 ACCESS 社）は、{{span style='color:blue;font-family:monospace;',ListType}} 構造体に対して下位互換をサポートまたは提供していません。決してこの構造体メンバに直接アクセスしないでください。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

'''Prototype'''
 typedef struct {
 	UInt16 id;
 	RectangleType bounds;
 	ListAttrType attr;
 	Char **itemsText;
 	Int16 numItems;
 	Int16 currentItem;
 	Int16 topItem;
 	FontID font;
 	UInt8 reserved;
 	WinHandle popupWin;
 	ListDrawDataFuncPtr drawItemCallback;
 } ListType;

'''フィールド'''
*{{span style='color:blue;font-family:monospace;',id}}
**ID 値。この値はアプリケーション開発者によって指定されます。この ID 値は {{goto lstEnterEvent,lstEnterEvent}} と {{goto lstSelectEvent,lstSelectEvent}} のイベント データのデータの一部として含まれます。
*{{span style='color:blue;font-family:monospace;',bounds}}
**リストの領域。ウィンドウに関係します。例えば、ID が {{span style='color:blue;font-family:monospace;',kObjectID}} のフォームにあるオブジェクトの領域にアクセスする場合、以下のようになります。
 { 
 RectangleType rect; 
 FormPtr formP = FrmGetActiveForm(); 
 FrmGetObjectBounds(formP,
 FrmGetObjectIndex(formP, kObjectID),
 &rect); 
 } 
*{{span style='color:blue;font-family:monospace;',attr}}
**リスト属性です。{{goto ListAttrType,ListAttrType}} を参照してください。
*{{span style='color:blue;font-family:monospace;',itemText}}
**選択肢のテキストを指す配列のポインタへのポインタです。{{goto LstGetSelectionText,LstGetSelectionText()}} を用いてアクセスします。例えば、ID が {{span style='color:blue;font-family:monospace;',kChoiceList}} のリストにある {{span style='color:blue;font-family:monospace;',itemNum}} によって指定される文字列にアクセスするには、以下のようにします。
 {
 Char *string;
 Int16 itemNum;
 ...
 string = LstGetSelectionText(GetObjectPtr(kChoicesList), itemNum);
 }
 where GetObjectPtr is the following:
 static void *GetObjectPtr(UInt16 rsrcID){
 FormPtr formP;
 formP = FrmGetActiveForm();
 return FrmGetObjectPtr(formP, FrmGetObjectIndex(formP, rsrcID));
 }
**リスト アイテムを描くのにコールバック ルーチンを使用する場合、{{goto LstSetListChoices,LstSetListChoices()}} に渡す {{span style='color:blue;font-family:monospace;',itemsText}} ポインタがコールバック ルーチンに渡されるということに注意してください。コールバック ルーチンに {{span style='color:blue;font-family:monospace;',itemsText}} を使用する Tips は {{goto ListDrawDataFuncType,ListDrawDataFuncType()}} のコメントを参照してください。
*{{span style='color:blue;font-family:monospace;',numItems}}
**リストの選択肢の数。{{goto LstGetNumberOfItems,LstGetNumberOfItems()}} を用いてアクセスします。
*{{span style='color:blue;font-family:monospace;',currentItem}}
**現在選択されているリスト選択肢（0 = 最初の選択肢）。{{goto LstGetSelection,LstGetSelection()}} を用いてアクセスします。
*{{span style='color:blue;font-family:monospace;',topItem}}
**リスト中で表示されている最初の選択肢。{{goto LstSetTopItem,LstSetTopItem()}} を用いてセットします。
*{{span style='color:blue;font-family:monospace;',font}}
**リスト テキスト文字列を描くのに使用されるフォントの ID。
*{{span style='color:blue;font-family:monospace;',reserved}}
**将来使用するために予約されています。
*{{span style='color:blue;font-family:monospace;',popupWin}}
**{{goto LstPopupList,LstPopupList()}} を呼び出すことでリストが表示されるときに作成されるウィンドウのハンドル
*{{span style='color:blue;font-family:monospace;',drawItemCallback}}
**アイテムを描くのに使用される関数。{{span style='color:blue;font-family:monospace;',NULL}} の場合、代わりにデフォルトの描画ルーチンが使用されます。{{goto LstSetDrawFunction,LstSetDrawFunction()}} を用いてこのフィールドをセットします。{{goto Application-Defined Functions,アプリケーション定義関数}} を参照してください。


!!{{anchor List Resources}}リスト リソース {{goto top,^TOP^}}

リスト リソース（tLST）とポップアップ トリガ リソース（tPUT）はアクティブなリストを表すために一緒に使用されます。詳細は、''Palm OS User Interface Guidelines'' を参照してください。


!!{{anchor List Functions}}リスト関数 {{goto top,^TOP^}}

!{{anchor LstDrawList}}LstDrawList 関数 {{goto top,^TOP^}}

'''目的'''

リスト オブジェクトの可視属性を {{span style='color:blue;font-family:monospace;',true}} にセットし、リスト オブジェクトが使用可能であればそれを描きます。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstDrawList (
 	ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

返り値はありません。

'''コメント'''

表示できる分よりも多くの選択肢がある場合、この関数は現在の選択が可視であることを保証します。現在の選択はハイライトされます。この関数は現在の選択が可視であることを保証しないということに注意してください（訳者注: 前文と矛盾している？前文の条件を満たさない場合はということか？）。可視であることを保証するためには、{{goto LstMakeItemVisible,LstMakeItemVisible()}} 関数を呼び出してください。

リストが無効になっている場合、グレイ-アウトで表示されます。リストが空の場合、何も表示されません。使用可能ではない場合、何も表示されません。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstPopupList,LstPopupList()}}, {{goto LstEraseList,LstEraseList()}}


!{{anchor LstEraseList}}LstEraseList 関数 {{goto top,^TOP^}}

'''目的'''

リスト オブジェクトを消去します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstEraseList (
 	ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

返り値はありません。

'''コメント'''

{{span style='color:blue;font-family:monospace;',visible}} 属性は、この関数によって、{{span style='color:blue;font-family:monospace;',false}} にセットされます。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstDrawList,LstDrawList()}}


!{{anchor LstGetNumberOfItems}}LstGetNumberOfItems 関数 {{goto top,^TOP^}}

'''目的'''

リストにあるアイテム数を返します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Int16 LstGetNumberOfItems (
 	const ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

リストにあるアイテムの数を返します。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstSetListChoices,LstSetListChoices()}}


!{{anchor LstGetSelection}}LstGetSelection 関数 {{goto top,^TOP^}}

'''目的'''

リスト中で現在選択されている選択肢を返します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Int16 LstGetSelection (
 	const ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

リスト選択肢で現在選択されているアイテム番号を返します。リスト選択肢は 0 から始まる連続した番号を付けられています。アイテムが選択されていない場合、{{span style='color:blue;font-family:monospace;',noListSelection}} を返します。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstSetListChoices,LstSetListChoices()}}, {{goto LstSetSelection,LstSetSelection()}}, {{goto LstGetSelectionText,LstGetSelectionText()}}


!{{anchor LstGetSelectionText}}LstGetSelectionText 関数 {{goto top,^TOP^}}

'''目的'''

リスト中の指定されたアイテムのテキストへのポインタを返します。指定されたアイテムが無い場合、{{span style='color:blue;font-family:monospace;',NULL}} を返します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Char *LstGetSelectionText (
 	const ListType *listP,
 	Int16 itemNum
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ itemNum}}
**選択するアイテム（0 = リストの最初のアイテム）

'''返り値'''

現在の選択のテキストへのポインタを返します。選択が範囲外の場合、{{span style='color:blue;font-family:monospace;',NULL}} を返します。

'''コメント'''

この関数の返り値は {{goto ListType,ListType}} 内部へのポインタであり、コピーではありません。この関数は、文字列の配列と {{goto LstSetListChoices,LstSetListChoices()}} の総計が提供されている場合にのみ、使用可能です。アプリケーションがリスト テキストを動的に生成するコールバック関数を使用している場合、この関数は {{span style='color:blue;font-family:monospace;',NULL}} を返します。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}


!{{anchor LstGetTopItem}}LstGetTopItem 関数 {{goto top,^TOP^}}

'''目的'''

最上段の可視のアイテムを返します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Int16 LstGetTopItem (
 	const ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

最初の可視のアイテムのアイテム番号を返します。

'''互換性'''

{{goto 4.0 New Feature Set,4.0 New Feature Set|Palm OS Programmer's API Reference/B}} が存在する場合にのみ、実装されます。
{{goto 4.0 New Feature Set,4.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。

'''参照'''

{{goto LstGetSelection,LstGetSelection()}}, {{goto LstSetTopItem,LstSetTopItem()}}


!{{anchor LstGetVisibleItems}}LstGetVisibleItems 関数 {{goto top,^TOP^}}

'''目的'''

可視のアイテムの数を返します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Int16 LstGetVisibleItems (
 	const ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

可視のアイテム数

'''互換性'''

{{goto 2.0 New Feature Set,2.0 New Feature Set|Palm OS Programmer's API Reference/B}} が存在する場合にのみ、実装されます。
{{goto 2.0 New Feature Set,2.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。


!{{anchor LstHandleEvent}}LstHandleEvent 関数 {{goto top,^TOP^}}

'''目的'''

指定されたリストのイベントをハンドルします。ハンドルするには、リスト オブジェクトの {{span style='color:blue;font-family:monospace;',usable}} と {{span style='color:blue;font-family:monospace;',visible}} 属性が {{span style='color:blue;font-family:monospace;',true}} にセットされていなくてはなりません。このルーチンは 2 種類のイベント {{goto penDownEvent,penDownEvent|Palm OS Programmer's API Reference/2}} と {{goto lstEnterEvent,lstEnterEvent|Palm OS Programmer's API Reference/2}} をハンドルします。コメントを参照してください。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Boolean LstHandleEvent (
 	ListType *listP,
 	const EventType *eventP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ eventP}}
**{{span style='color:blue;font-family:monospace;',EventType}} 構造体へのポインタ
'''返り値'''

イベントがハンドルされた場合は、{{span style='color:blue;font-family:monospace;',true}} を返します。以下の場合では、結果として {{span style='color:blue;font-family:monospace;',true}} を返します。

*リストの領域内での {{span style='color:blue;font-family:monospace;',penDownEvent}}
*リスト データ構造体のリスト ID と一致するリスト ID を持つ {{span style='color:blue;font-family:monospace;',lstEnterEvent}}

'''コメント'''

このルーチンが {{span style='color:blue;font-family:monospace;',penDownEvent}} を受け取ると、このルーチンはペンの位置がリスト オブジェクトの領域内かどうかチェックします。領域内であれば、このルーチンはペンが領域外に出るまでペンを追跡します。ペンがリストの領域内に入ってくると、{{span style='color:blue;font-family:monospace;',lstEnterEvent}} がイベント キューに追加され、このルーチンは終了します。

このルーチンが {{span style='color:blue;font-family:monospace;',lstEnterEvent}} を受け取ると、イベント レコードのリスト ID が指定されたリストの ID と一致するかどうかチェックします。一致する場合、このルーチンはリストの選択肢を保持しているポップアップ ウィンドウを作成し、表示してから終了します。

リストのポップアップ ウィンドウが表示されている間に {{span style='color:blue;font-family:monospace;',penDownEent}} を受け取り、かつ、ペンの位置が領域外の場合、そのウィンドウは消されます。ペンの位置がウィンドウの領域内の場合、このルーチンはペンが領域外にでるまでペンを追跡します。
ペンがリスト オブジェクトの領域外に出ると、{{span style='color:blue;font-family:monospace;',lstEnterEvent}} がイベント キューに追加されます。


!{{anchor LstMakeItemVisible}}LstMakeItemVisible 関数 {{goto top,^TOP^}}

'''目的'''

アイテムを可視に、できれば最上段に、します。アイテムがすでに可視の場合、変更されません。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstMakeItemVisible (
 	ListType *listP,
 	Int16 itemNum
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ itemNum}}
**選択するアイテム（0 = リストの最初のアイテム）

'''返り値'''

返り値はありません。

'''コメント'''

この関数はリストの再描画は行いません。再描画するためには、{{goto LstDrawList,LstDrawList()}} を呼び出してください。


!{{anchor LstNewList}}LstNewList 関数 {{goto top,^TOP^}}

'''目的'''

新しいリスト オブジェクトを動的に作成し、それを指定されたフォームにインストールします。この関数は、新しいポップアップ トリガとそれに関連するリストを作成するのに使用できます。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Err LstNewList (
 	void **formPP,
 	UInt16 id,
 	Coord x,
 	Coord y,
 	Coord width,
 	Coord height,
 	FontID font,
 	Int16 visibleItems,
 	Int16 triggerId
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',←→ formPP}}
**新しいリストがインストールされるフォームへのポインタへのポインタ。この値はハンドルではありません。つまり、この関数が返った後に、古い {{span style='color:blue;font-family:monospace;',formPP}} 値が有効である必要はありません。その後の呼び出しでは、この関数によって常に新しい {{span style='color:blue;font-family:monospace;',formPP}} 値が返されます。
*{{span style='color:blue;font-family:monospace;',→ id}}
**開発者によって指定されたリストの記号的な ID。規約では、この ID はリソース ID と一致しているべきです（義務ではありません）。
*{{span style='color:blue;font-family:monospace;',→ x}}
**作成されるリストの領域の左上端の、リストが現れるウィンドウに関連する、水平座標
*{{span style='color:blue;font-family:monospace;',→ y}}
**作成されるリストの領域の左上端の、リストが現れるウィンドウに関連する、垂直座標
*{{span style='color:blue;font-family:monospace;',→ width}}
**ピクセルで表されるリストの幅。有効値は 1 - 160。
*{{span style='color:blue;font-family:monospace;',→ height}}
**ピクセルで表されるリストの高さ。有効値は 1 - 160。
*{{span style='color:blue;font-family:monospace;',→ visibleItems}}
**同時に表示することができるリスト アイテムの数
*{{span style='color:blue;font-family:monospace;',→ triggerId}}
**新しいリストに関連するポップアップ トリガの記号的な ID （この ID は開発者によって指定されます）。{{span style='color:blue;font-family:monospace;',triggerId}} に対して 0 以外の値を指定すると、この関数はリストとそれに関連するポップアップ トリガの両方を作成します。リストがポップアップ リストではない場合、{{span style='color:blue;font-family:monospace;',triggerId}} に対して 0 を渡してください。

'''返り値'''

エラーが無い場合は、0 を返します。

'''互換性'''

{{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B}} が存在する場合にのみ、実装されます。
{{goto 3.0 New Feature Set,3.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。

'''参照'''

{{goto LstDrawList,LstDrawList()}}, {{goto FrmRemoveObject,FrmRemoveObject()|Palm OS Programmer's API Reference/11}}


!{{anchor LstPopupList}}LstPopupList 関数 {{goto top,^TOP^}}

'''目的'''

リストのアイテムを保持している様式の（原文: modal）ウィンドウを表示します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Int16 LstPopupList (
 	ListType *listP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ

'''返り値'''

選択されたリスト アイテムを返します。選択されたアイテムが無い場合は、-1 を返します。

'''コメント'''

前のアクティブ ウィンドウを保存します。新しいポップアップ ウィンドを作成し、削除します。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}


!{{anchor LstScrollList}}LstScrollList 関数 {{goto top,^TOP^}}

'''目的'''

リストを上または下に何度かスクロールさせます。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 Boolean LstScrollList (
 	ListType *listP,
 	WinDirectionType direction,
 	Int16 itemCount
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ direction}}
**スクロールの方向
*{{span style='color:blue;font-family:monospace;',→ itemCount}}
**指示した方向にスクロールするアイテム（訳者注: スクロールする回数のことか？）

'''返り値'''

リストが実際にスクロールされれば {{span style='color:blue;font-family:monospace;',true}} を返します。そうでなければ、{{span style='color:blue;font-family:monospace;',false}} を返します。リストの終わりを越えるスクロールが要求されると {{span style='color:blue;font-family:monospace;',false}} を返すかもしれません。

'''互換性'''

{{goto 2.0 New Feature Set,2.0 New Feature Set|Palm OS Programmer's API Reference/B}} が存在する場合にのみ、実装されます。
{{goto 2.0 New Feature Set,2.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ、実装されます。


!{{anchor LstSetDrawFunction}}LstSetDrawFunction 関数 {{goto top,^TOP^}}

'''目的'''

アイテムのテキスト文字列を描く代わりに各アイテムを描く関数をセットします。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetDrawFunction (
 	ListType *listP,
 	ListDrawDataFuncPtr func
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ func}}
**アイテムを描く関数へのポインタ

'''返り値'''

返り値はありません。

'''コメント'''

この関数は、縮められたリストが下方向にスクロールされ過ぎるのを防ぐため、{{span style='color:blue;font-family:monospace;',topItem}} を調節する機能も持っています。この関数はカスタム描画機能性のために使用されます。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstGlueGetDrawFunction,LstGlueGetDrawFunction()}}, {{goto LstSetListChoices,LstSetListChoices()}}, {{goto ListDrawDataFuncType,ListDrawDataFuncType()}}


!{{anchor LstSetHeight}}LstSetHeight 関数 {{goto top,^TOP^}}

'''目的'''

リスト中の可視のアイテムの数をセットします。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetHeight (
 	ListType *listP,
 	Int16 visibleItems
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ visibleItems}}
**一度に可視となる選択肢の数

'''返り値'''

返り値はありません。

'''コメント'''

この関数は、リストがすでに描画されている場合、リストの再描画を行いません。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}


!{{anchor LstSetListChoices}}LstSetListChoices 関数 {{goto top,^TOP^}}

'''目的'''

この関数に渡されたテキスト文字列ポインタの配列にリストのアイテムをセットします。この関数は古いリスト アイテムを消去します。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetListChoices (
 	ListType *listP,
 	Char **itemsText,
 	Int16 numItems
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ itemText}}
**テキスト文字列の配列へのポインタ。この文字列の配列を作成する 1 つの方法は、{{goto SysFormPointerArrayToStrings,SysFormPointerArrayToStrings()}} を参照してください。
*{{span style='color:blue;font-family:monospace;',→ numItems}}
**リストの選択肢の数

'''返り値'''

返り値はありません。

'''コメント'''

この関数を呼び出したときにリストが表示されている場合、リスト（の表示）を更新するために {{span style='color:blue;font-family:monospace;',LstDrawList}} 関数を呼び出す必要があります。

//----
//'''NOTE::''' この関数は {{span style='color:blue;font-family:monospace;',itemsText}} 配列にある文字列をコピーするわけではありません。このことが意味するのは、この関数をリストに対して実行した後はその配列が移動されたり、割り当てを解除されたりしないことを保障しなくてはならないということです。
//----
::NOTE:
:::この関数は {{span style='color:blue;font-family:monospace;',itemsText}} 配列にある文字列をコピーするわけではありません。このことが意味するのは、この関数をリストに対して実行した後はその配列が移動されたり、割り当てを解除されたりしないことを保障しなくてはならないということです。

リストのアイテムを描画するためにコールバック ルーチンを使用する場合、単に {{span style='color:blue;font-family:monospace;',itemsText}} ポインタをコールバック ルーチンに渡すだけで済み、{{span style='color:blue;font-family:monospace;',itemsText}} ポインタに対してリスト マネージャ コードを使用する必要はありません。コールバック ルーチンに対して {{span style='color:blue;font-family:monospace;',itemsText}} パラメータを使用する Tips については、{{goto ListDrawDataFuncType,ListDrawDataFuncType()}} のコメントを参照してください。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstGlueGetItemsText,LstGlueGetItemsText()}}, {{goto LstSetSelection,LstSetSelection()}}, {{goto LstSetTopItem,LstSetTopItem()}}, {{goto LstDrawList,LstDrawList()}}, {[goto LstSetHeight,LstSetHeight()}}, {{goto LstSetDrawFunction,LstSetDrawFunction()}}


!{{anchor LstSetPosition}}LstSetPosition 関数 {{goto top,^TOP^}}

'''目的'''

リストの位置をセットします。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetPosition (
 	ListType *listP,
 	Coord x,
 	Coord y
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ x}}
**左端
*{{span style='color:blue;font-family:monospace;',→ y}}
**上端

'''返り値'''

返り値はありません。

'''コメント'''

リストは再描画されません。リストが可視のときに、この関数を呼び出してはいけません。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}


!{{anchor LstSetSelection}}LstSetSelection 関数 {{goto top,^TOP^}}

'''目的'''

リストの選択をセットします。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetSelection (
 	ListType *listP,
 	Int16 itemNum
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ itemNum}}
**選択されるアイテム（0 = リストの最初のアイテム, {{span style='color:blue;font-family:monospace;',noListSelection}} = 選択無し）

'''返り値'''

返り値はありません。

'''コメント'''

古い選択は、あったとしても、選択が解除されます。リストが可視の場合、選択されたアイテムは視覚的に更新されます。リストは、必要があれば、リスト オブジェクトが可視で使用可能な限り、選択されたアイテムに向けてスクロールされます。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{goto LstSetTopItem,LstSetTopItem()}}


!{{anchor LstSetTopItem}}LstSetTopItem 関数 {{goto top,^TOP^}}

'''目的'''

アイテムを可視にします。アイテムが、リストの最後にある場合、最上段のアイテムにはなれません。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void LstSetTopItem (
 	ListType *listP,
 	Int16 itemNum
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ listP}}
**リスト オブジェクト（{{goto ListType,ListType}}）へのポインタ
*{{span style='color:blue;font-family:monospace;',→ itemNum}}
**選択されるアイテム（0 = リストの最初のアイテム）。この値は有効なアイテム番号でなくてはなりません。

'''返り値'''

返り値はありません。

'''コメント'''

ディスプレイの更新は行いません。

//----
//'''NOTE::''' {{span style='color:blue;font-family:monospace;',itemNum}} に指定する値は 0 から アイテムの最大番号までの範囲でなければなりません。
//----
::NOTE:
:::{{span style='color:blue;font-family:monospace;',itemNum}} に指定する値は 0 から アイテムの最大番号までの範囲でなければなりません。

'''参照'''

{{goto FrmGetObjectPtr,FrmGetObjectPtr()|Palm OS Programmer's API Reference/11}}, {{span style='color:blue;font-family:monospace;',LstGlueGetTopItem}}, {{goto LstSetSelection,LstSetSelection()}}, {{goto LstGetTopItem,LstGetTopItem()}}, {{goto LstMakeItemVisible,LstMakeItemVisible()}}, {{goto LstDrawList,LstDrawList()}}, {{goto LstEraseList,LstEraseList()}}


!!{{anchor Application-Defined Functions}}アプリケーション定義関数 {{goto top,^TOP^}}

リストのアイテムに対して特別な描画を行う必要がある場合、リスト描画コールバック関数をセットするために {{goto LstSetDrawFunction,LstSetDrawFunction()}} を呼び出します。{{goto ListDrawDataFuncType,ListDrawDataFuncType()}} セクションでは、リスト アイテムの描画のために提供されるコールバック関数のプロトタイプについて説明しています。

!{{anchor ListDrawDataFuncType}}ListDrawDataFuncType 関数 {{goto top,^TOP^}}

'''目的'''

コールバック関数は、リストのアイテムを描画するために提供されるものです。この関数は、Palm OS がリストの要素を仰臥する必要があるときにいつでも呼び出されます。コールバック関数の宣言は、ここで示すプロトタイプと一致していなくてはなりません。

'''宣言されている場所'''

{{span style='color:blue;font-family:monospace;',List.h}}

'''Prototype'''
 void ListDrawDataFuncType(
 	Int16 itemNum,
 	RectangleType *bounds,
 	Char **itemsText
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ itemNum}}
**描画するアイテムの数
*{{span style='color:blue;font-family:monospace;',→ bounds}}
**ウィンドウに関連するリストの領域
*{{span style='color:blue;font-family:monospace;',→ itemsText}}
**リスト アイテムのテキストへのポインタ配列へのポインタ。これは、{{goto LstSetListChoices,LstSetListChoices()}} を呼び出したと域に提供されるポインタです。

'''返り値'''

返り値はありません。

'''コメント'''

コールバック関数をリストに対して登録するために {{goto LstSetDrawFunction,LstSetDrawFunction)}} を呼び出します。これが意味するのは、リスト アイテムを描画するために、各アイテムのテキスト文字列を表示するビルド-イン関数ではなく、登録した関数が呼び出されるということです。

コールバック関数は、リストのアイテムが描画される必要があればいつでも、呼び出されます。コールバック関数が呼び出されたとき、{{span style='color:blue;font-family:monospace;',itemNum}} パラメータの値が、関数が描くべきアイテムを指定します。{{span style='color:blue;font-family:monospace;',LstSetListChoices}} に提供される {{span style='color:blue;font-family:monospace;',itemsText}} パラメータは、実際に文字列のリストを指している必要はありません: {{span style='color:blue;font-family:monospace;',NULL}} または 描画関数に有用な何かを指すポインタを渡すこともできます。しかしながら、{{span style='color:blue;font-family:monospace;',LstSetListChoices}} を呼び出す際に文字列のリストを指すポインタ以外のものを渡す場合、{{goto LstGetSelectionText,LstGetSelectionText()}} が決して呼び出されないということを保障しなくてはならないことに注意してください。なぜなら、{{goto LstGetSelectionText,LstGetSelectionText()}} は {{span style='color:blue;font-family:monospace;',itemsText}} ポインタがテキスト アイテムの配列を指していると仮定しているからです。特に、リストがポップアップ トリガに関連している場合、{{goto FrmHandleEvent,FrmHandleEvent()|Palm OS Programmer's API Reference/11}} が {{span style='color:blue;font-family:monospace;',popSelectEvent}} をハンドルする機会を得る前に、アプリケーション コードが自身で {{span style='color:blue;font-family:monospace;',popSelectEvent}} をハンドルしなくてはなりません。なぜなら、{{span style='color:blue;font-family:monospace;',FrmHandleEvent}} は {{span style='color:blue;font-family:monospace;',LstGetSelectionText}} を呼び出すからです。

//----
//{{span style='color:red;font-weight:bold;',WARNING!}} リストがポップアップ リストの場合、そのリストを所有しているフォームは、そのリストがウィンドウに表示されている間、アクティブになりません。これが意味するのは、{{goto FrmGetActiveForm,FrmGetActiveForm()|Palm OS Programmer's API Reference/11}} を呼び出すことができないということです。代わりに、描画に必要となる情報にアクセスするために {{span style='color:blue;font-family:monospace;',itemsText}} ポインタを使用します。フォームにアクセスしなけらばならない場合、{{goto FrmGetFormPtr,FrmGetFormPtr()|Palm OS Programmer's API Reference/11}} 関数を使用してください。
//----
::{{span style='color:red;font-weight:bold;',WARNING!}}
:::リストがポップアップ リストの場合、そのリストを所有しているフォームは、そのリストがウィンドウに表示されている間、アクティブになりません。これが意味するのは、{{goto FrmGetActiveForm,FrmGetActiveForm()|Palm OS Programmer's API Reference/11}} を呼び出すことができないということです。代わりに、描画に必要となる情報にアクセスするために {{span style='color:blue;font-family:monospace;',itemsText}} ポインタを使用します。フォームにアクセスしなけらばならない場合、{{goto FrmGetFormPtr,FrmGetFormPtr()|Palm OS Programmer's API Reference/11}} 関数を使用してください。

リスト オブジェクトは、アイテムを描画する際にどの色を使用するか、と、選択されたアイテムと選択されていないアイテムをどのように描画するかを管理するということに注意してください。ほぼすべての状況で、描画関数がこれらの詳細について関知する必要はありません。

しかしながら、アイテムが選択されているかどうか調べる必要がある場合、描画関数を呼び出すのに先立って、システムがペン カラーを 2 つの色のどちらの色にしたかという事実を信頼することができます。

*アイテムが選択されている場合、前景色は {{span style='color:blue;font-family:monospace;',UIObjectSelectedForeground}} です。
*アイテムが選択されていない場合、前景色は {{span style='color:blue;font-family:monospace;',UIObjectForeground}} です。

リスト アイテムに影響を与えるこの前景色を、前景色の前の値を返す {{goto WinSetForeColor,WinSetForeColor()|Palm OS Programmer's API Reference/59}} を呼び出すことで調べられます。前景色を以前の色にリセットするために、忘れずにもう一度 {{span style='color:blue;font-family:monospace;',WinSetForeColor}} を呼び出してください。例えば、以下のようにします。

 itemColor = WinSetForeColor(myColor)
 WinSetForeColor(itemColor)
 selectColor = UiColorGetTableEntryIndex(
                    UIObjectSelectedForeground)
 if itemColor == selectColor
 ...

'''参照'''

{{goto LstSetDrawFunction,LstSetDrawFunction()}}, {{goto UIColorGetTableEntryIndex,UIColorGetTableEntryIndex()|Palm OS Programmer's API Reference/21}}, {{goto WinSetForeColor,WinSetForeColor()|Palm OS Programmer's API Reference/59}}
{{div_end}}

{{div_begin "style='border-top:solid;border-top-width:1px;border-top-color:silver;'"}}
[[←　13 章に戻る|Palm OS Programmer's API Reference/13]]　[[↑トップへ|Palm OS Programmer's API Reference]]　[[15 章に進む　→|Palm OS Programmer's API Reference/15]]
{{div_end}}