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

{{div_begin style="margin-bottom:-10px"}}
!!!5 カテゴリ
{{div_end}}

{{div_begin "style='position:absolute;right:0px;font-size:70%;margin-right:15px;margin-top:15px;width:250px;'"}}
*{{goto Category Data Structures,カテゴリ データ構造体}}
**{{goto AppInfoPtr,AppInfoPtr}}
**{{goto AppInfoType,AppInfoType}}
*{{goto Category Constants,カテゴリ定数}}
*{{goto Category Functions,カテゴリ関数}}
**{{goto CategoryCreateList,CategoryCreateList}}
**{{goto CategoryCreateListV10,CategoryCreateListV10}}
**{{goto CategoryEdit,CategoryEdit}}
**{{goto CategoryEditV20,CategoryEditV20}}
**{{goto CategoryEditV10,CategoryEditV10}}
**{{goto CategoryFind,CategoryFind}}
**{{goto CategoryFreeList,CategoryFreeList}}
**{{goto CategoryFreeListV10,CategoryFreeListV10}}
**{{goto CategoryGetName,CategoryGetName}}
**{{goto CategoryGetNext,CategoryGetNext}}
**{{goto CategoryInitialize,CategoryInitialize}}
**{{goto CategorySelect,CategorySelect}}
**{{goto CategorySelectV10,CategorySelectV10}}
**{{goto CategorySetName,CategorySetName}}
**{{goto CategorySetTriggerLabel,CategorySetTriggerLabel}}
**{{goto CategoryTruncateName,CategoryTruncateName}}
{{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;'"}}
この章では、ヘッダ ファイル {{span style='color:blue;font-family:monospace;',Category.h}} で宣言されたカテゴリ API について説明します。以下のトピックについて説明します。

*{{goto Category Data Structures,カテゴリ データ構造体}}
*{{goto Category Constants,カテゴリ定数}}
*{{goto Category Functions,カテゴリ関数}}

カテゴリについての追加情報は、''Palm OS Programmer's Companion, vol. I'' の [[「カテゴリ」|Palm OS Programmer's Companion Volume I/4-9]] セクションを参照してください。


!!{{anchor Category Data Structures}}カテゴリ データ構造体 {{goto top,^TOP^}}


!{{anchor AppInfoPtr}}AppInfoPtr 型 {{goto top,^TOP^}}

'''目的'''

{{span style='color:blue;font-family:monospace;',AppInfoPrt}} は {{goto AppInfoType,AppInfoType}} 構造体へのポインタを定義します。

'''Prototype'''
 typedef AppInfoType *AppInfoPtr;

!{{anchor AppInfoType}}AppInfoType 型 {{goto top,^TOP^}}
//!AppInfoType構造体

'''目的'''

以下で示す {{span style='color:blue;font-family:monospace;',AppInfoType}} 構造体は、カテゴリ名をカテゴリ インデックスと固有のIDへマッピングします。この章で説明されるカテゴリ API を使うためには、データベースのアプリケーション情報ブロックは {{span style='color:blue;font-family:monospace;',AppInfoType}} 構造体であるか、その最初のフィールドに {{span style='color:blue;font-family:monospace;',AppInfoType}} 構造体を持たなくてはなりません。

'''Prototype'''
 typedef struct {
 	UInt16 renamedCategories;
 	Char categoryLabels [dmRecNumCategories] 
 [dmCategoryLength];
 	UInt8 categoryUniqIDs[dmRecNumCategories];
 	UInt8 lastUniqID;
 	UInt8 padding;
 } AppInfoType;

'''フィールド'''
*{{span style='color:blue;font-family:monospace;',renamedCategories}}
**{{goto CategorySetName,CategorySetName()}} によって、リネームされたカテゴリを示すビット フィールドとして使用されます。通常、Conduit によって消去されます。（訳者注: Conduit とは母艦とPalmとでデータを同期させる設定書類）
*{{span style='color:blue;font-family:monospace;',categoryLabels}}
**カテゴリ名を収納する文字列の配列。この配列の最大サイズは {{span style='color:blue;font-family:monospace;',dmRecNumCategorie}} であり、配列の各要素の最大長は {{span style='color:blue;font-family:monospace;',dmCategoryLength}} です。これらの定数は 2 つとも {{span style='color:blue;font-family:monospace;',DataMgr.h}} で定義されます。
*{{span style='color:blue;font-family:monospace;',categoryUniqIDs}}
**デスクトップ データベースとの同期をとるために使用される カテゴリ ID。デバイスによって、0 から 127 の範囲の固有の ID が生成されます。デスクトップ コンピュータによって、128 から 255 の範囲の固有の ID が生成されます。
*{{span style='color:blue;font-family:monospace;',lastUniqID}}
**ソートと固有の ID を割り当てるのに使用されます。

'''コメント'''

アプリケーション情報ブロックをストレージ ヒープに割り当て、データベースのアプリケーション情報 ID をこの構造体のローカル ID にセットするために {{goto DmSetDatabaseInfo,DmSetDatabaseInfo()|Palm OS Programmer's API Reference/30}} 関数を使用してください。それから、カテゴリ名を保持している文字列のローカライズされたリストでそれ（訳者注: アプリケーション情報ブロックであろう）を初期化するために {{goto CategoryInitialize,CategoryInitialize()}} 関数を使用してください。


!!{{anchor Category Constants}}カテゴリ定数 {{goto top,^TOP^}}

以下のカテゴリ定数が定義されています。
, 定数, 値, 説明
, "{{span style='color:blue;font-family:monospace;',categoryHideEditCategory}}", 10000, 「カテゴリ編集」項目を抑制するのに使用されます。
, "{{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}}", 10001, デフォルトの「カテゴリ編集」項目を表示するのに使用されます。

//----
//'''NOTE:''' これらの定数はシステム リソース ID のように見えるかもしれませんが、そうではありません。「カテゴリ編集」項目にデフォルトではない文字列を使用するには、タイトル文字列のリソース ID を渡します。デフォルトまたは隠れた項目を使用したい場合は、これらの定数を渡します。パラメータとして使用される可能性のある他の値と衝突するのを防ぐため、これらの値はシステム リソース ID の範囲にします（10000以上）。
//----
::NOTE
:::これらの定数はシステム リソース ID のように見えるかもしれませんが、そうではありません。「カテゴリ編集」項目にデフォルトではない文字列を使用するには、タイトル文字列のリソース ID を渡します。デフォルトまたは隠れた項目を使用したい場合は、これらの定数を渡します。パラメータとして使用される可能性のある他の値と衝突するのを防ぐため、これらの値はシステム リソース ID の範囲にします（10000以上）。

'''互換性'''

{{span style='color:blue;font-family:monospace;',categoryHideEditCategory}} と {{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}} はどちらも {{goto 3.5 New Feature Set,3.5 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ定義されます。


!!{{anchor Category Functions}}カテゴリ関数 {{goto top,^TOP^}}


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

'''目的'''

ポップアップ リストをデータベースのカテゴリに実装します。

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

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

'''Prototype'''
 void CategoryCreateList (
 	DmOpenRef db,
 	ListType *listP,
 	UInt16 currentCategory,
 	Boolean showAll,
 	Boolean showUneditables,
 	UInt8 numUneditableCategories,
 	UInt32 editingStrID,
 	Boolean resizeList
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**調べたいカテゴリ情報を収めているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',← listP}}
**カテゴリを表示する {{goto ListType,ListType}} 構造体へのポインタ
*{{span style='color:blue;font-family:monospace;',→ currentCategory}}
**選択するカテゴリのインデックス。これは、{{span style='color:blue;font-family:monospace;',categoryLabels}} 配列のインデックスです。デフォルトでは「未分類」カテゴリを選択しています。
*{{span style='color:blue;font-family:monospace;',→ showAll}}
**「すべて」のリスト項目を含む場合は、{{span style='color:blue;font-family:monospace;',true}} です。
*{{span style='color:blue;font-family:monospace;',→ showUneditables}}
**編集不可のカテゴリを表示する場合は、{{span style='color:blue;font-family:monospace;',true}} です。
*{{span style='color:blue;font-family:monospace;',→ numUneditableCategories}}
**ユーザが編集できないカテゴリの数です。編集不可のカテゴリを {{span style='color:blue;font-family:monospace;',categoryLabels}} 配列の先頭に置くべきです。例えば、一般的に「未分類」カテゴリを編集不可である 0 の位置に置きます。この関数は編集不可のカテゴリをポップアップ リストの最後に表示します。
*{{span style='color:blue;font-family:monospace;',→ editingStrID}}
**「カテゴリ編集」リスト項目として使用する {{span style='color:blue;font-family:monospace;',tStr}} リソースのリソース ID です。デフォルト文字列（「カテゴリ編集」）を使用するためには、定数 {{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}} を渡します。ユーザにカテゴリ編集をさせたくない場合は、定数 {{span style='color:blue;font-family:monospace;',categoryHideEditCategory}} を渡します。
*{{span style='color:blue;font-family:monospace;',→ resizeList}}
**カテゴリ数のリストをリサイズする場合は、{{span style='color:blue;font-family:monospace;',true}} です。ポップアップには {{span style='color:blue;font-family:monospace;',true}} を、それ以外には {{span style='color:blue;font-family:monospace;',false}} をセットします。

'''返り値'''

返り値はありません。

'''コメント'''

「すべて」項目がリストの先頭にきます（{{span style='color:blue;font-family:monospace;',showAll}} パラメータが {{span style='color:blue;font-family:monospace;',true}} の場合）。データベースにある編集可能なカテゴリがそのあとに続き、編集不可のカテゴリはそのあとになります。カテゴリを編集するためのオプションは、リストの最後で、無くすこともできます。

この関数が直接呼び出されることはほとんどありません。そのかわり、たいていのアプリケーションはこの関数を呼び出す {{goto CategorySelect,CategorySelect()}} を使用し、それにより、ユーザがポップアップ リストにあるカテゴリを選択するのを完全に管理しています。

この関数は、{{span style='color:blue;font-family:monospace;',db}} パラメータの {{span style='color:blue;font-family:monospace;',appInfoID}} を取得し、それが示す {{goto AppInfoType,AppInfoType}} 構造体を読み、その情報を {{span style='color:blue;font-family:monospace;',listP}} が示すデータベースのカテゴリの名前を収めた配列を初期化するのに使用します。あらかじめ {{span style='color:blue;font-family:monospace;',listP}} によって示される構造体を配置しておかなくてはなりません。{{span style='color:blue;font-family:monospace;',CategoryCreateList}} はリストを表示しません。表示するには、{{goto LstPopupList,LstPopupList()|Palm OS Programmer's API Reference/14}} か {{goto LstDrawList,LstDrawList()|Palm OS Programmer's API Reference/14}} を使用してください。

{{span style='color:blue;font-family:monospace;',CategoryCreateList}} の呼び出しと {{goto CategoryFreeList,CategoryFreeList()}} の呼び出しとのバランスをとらなくてはなりません。{{span style='color:blue;font-family:monospace;',CategoryCreateList}} 関数はカテゴリ名のリソースをロックします。また、この関数は {{span style='color:blue;font-family:monospace;',listP}} が示す配列を配置します。{{span style='color:blue;font-family:monospace;',CategoryFreeList}} は、{{span style='color:blue;font-family:monospace;',CategoryCreateList}} によってロックされたすべてのリソースのロックを外し、{{span style='color:blue;font-family:monospace;',CategoryCreateList}} によって使用されていたすべてのメモリを解放します。

'''互換性'''

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

{{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}}, {{span style='color:blue;font-family:monospace;',categoryHideEditCategory}} 定数は、{{goto 3.5 New Feature Set,3.5 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ定義されます。それより前のバージョンでは、{{span style='color:blue;font-family:monospace;',editingStrID}} パラメータに 0 を渡すことで「カテゴリ編集」文字列を表示させなくする、または、渡すことでその項目をリストに含めることができます

'''参照'''

{{span style='color:blue;font-family:monospace;',CategoryCreateListV10()}}


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

'''目的'''

データベースのカテゴリを読み込み、カテゴリ リストをセットします。

'''定義する場所'''

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

'''Prototype'''
 void CategoryCreateListV10 (
 	DmOpenRef db,
 	ListType *lst,
 	UInt16 currentCategory,
 	Boolean showAll
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**調べたいカテゴリ情報を収めているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',← listP}}
**カテゴリを表示する {{goto ListType,ListType}} 構造体へのポインタ
*{{span style='color:blue;font-family:monospace;',→ currentCategory}}
**選択するカテゴリのインデックス。これは、{{span style='color:blue;font-family:monospace;',categoryLabels}} 配列のインデックスです。デフォルトでは「未分類」カテゴリを選択しています。
*{{span style='color:blue;font-family:monospace;',→ showAll}}
**「すべて」のリスト項目を含む場合は、{{span style='color:blue;font-family:monospace;',true}} です。

'''返り値'''

返り値はありません。

'''互換性'''

この関数は {{goto CategoryCreateList,CategoryCreateList()}} の Palm OS 1.0 バージョン に相当します。これは古い関数です。


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

'''目的'''

「カテゴリ編集」ダイアログのイベント ハンドラ

'''定義されている場所'''

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

'''Prototype'''
 Boolean CategoryEdit (
 	DmOpenRef db,
 	UInt16 *category,
 	UInt32 titleStrID,
 	UInt8 numUneditableCategories
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**編集するカテゴリを収めているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',← category}}
**この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。
*{{span style='color:blue;font-family:monospace;',→ titleStrID}}
**ダイアログのタイトルとして使用する {{span style='color:blue;font-family:monospace;',tSTR}} リソースのリソース ID です。デフォルトの文字列（「カテゴリ編集」）を使用するには、{{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}} 定数を渡します。
*{{span style='color:blue;font-family:monospace;',→ numUneditableCategories}}
**ユーザが編集できないカテゴリの数です。編集不可のカテゴリは {{span style='color:blue;font-family:monospace;',categoryLabels}} 配列の先頭に保存すべきです。例えば、通常は「未分類」カテゴリを編集不可の 0 の位置におきます。

//この関数は、編集不可のカテゴリをポップアップ リストの最後に表示します。

'''返り値'''

以下の条件のいずれかが成り立てば、{{span style='color:blue;font-family:monospace;',true}} を返します。
*現在のカテゴリがリネームされる
*現在のカテゴリが削除される
*現在のカテゴリが他のカテゴリとマージされる

'''コメント'''

この関数が直接呼び出されることはほとんどありません。ユーザがカテゴリ編集リスト項目を選択するときに、{{goto CategorySelec,CategorySelect()}} 関数がこの関数を呼び出します。

この関数は、カテゴリ編集ダイアログの表示とユーザ アクションの結果のハンドルの両方を行います。この関数は、{{goto AppInfoType,AppInfoType}} 構造体のカテゴリのリストを更新し、必要があればデータベース レコードを新しいカテゴリに再配置します。ユーザがカテゴリを削除すると、{{span style='color:blue;font-family:monospace;',CategoryEdit}} が、削除されたカテゴリに属していたすべてのレコードを未分類カテゴリに移動させます。あるカテゴリが、すでに存在しているカテゴリと同じ名前にリネームされると、この関数は古いカテゴリのすべてのレコードを新しいカテゴリに移動させます。

'''互換性'''

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

'''参照'''

{{goto CategoryEditV20,CategoryEditV20()}}, {{goto CategoryEditV10,CategoryEditV10()}}, {{goto DmMoveCategory,DmMoveCategory()}}


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

'''目的'''

「カテゴリ編集」ダイアログのイベント ハンドラ

'''定義されている場所'''

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

'''Prototype'''
 Boolean CategoryEditV20 (
 	DmOpenRef db,
 	UInt16 *category,
 	UInt32 titleStrID
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**編集するカテゴリを収めているオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',← category}}
**この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。
*{{span style='color:blue;font-family:monospace;',→ titleStrID}}
**ダイアログのタイトルとして使用される {{span style='color:blue;font-family:monospace;',tSTR}} リソースのリソース ID です。

'''返り値'''

以下の条件がいずれかが成り立てば、{{span style='color:blue;font-family:monospace;',true}} を返します。
*現在のカテゴリがリネームされる
*現在のカテゴリが削除される
*現在のカテゴリが他のカテゴリとマージされる

'''互換性'''

この関数は {{span style='color:blue;font-family:monospace;',CategoryEdit}} の Palm OS 2.0 バージョンに相当します。{{goto 2.0 New Feature Set,2.0 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ実装されます。これは古い関数です。

'''参照'''

{{goto CategoryEdit,CategoryEdit()}}, {{goto CategoryEditV10,CategoryEditV10()}}


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

'''目的'''

「カテゴリ編集」ダイアログのイベント ハンドラ

'''定義されている場所'''

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

'''Prototype'''
 Boolean CategoryEditV10 (
 	DmOpenRef db
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**編集するカテゴリを収めているオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',← category}}
**この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。

'''返り値'''

以下の条件がいずれかが成り立てば、{{span style='color:blue;font-family:monospace;',true}} を返します。
*現在のカテゴリがリネームされる
*現在のカテゴリが削除される
*現在のカテゴリが他のカテゴリとマージされる

'''互換性'''

この関数は {{span style='color:blue;font-family:monospace;',CategoryEdit}} の Palm OS 1.0 バージョンに相当します。これは古い関数です。

'''参照'''

{{goto CategoryEdit,CategoryEdit()}}, {{goto CategoryEditV20,CategoryEditV20()}}


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

'''目的'''

与えられた名前を持つカテゴリのインデックスを返します。

'''定義されている場所'''

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

'''Prototype'''
 UInt16 CategoryFind (
 	DmOpenRef db,
 	const Char *name
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**検索するオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',→ name}}
**カテゴリ名です。最初の使用されていないカテゴリを検索する場合、空の文字列を渡してください。

'''返り値'''

{{span style='color:blue;font-family:monospace;',categoryLabels}} 配列（{{goto AppInfoType,AppInfoType}} を参照してください）にあるカテゴリのエントリのインデックスを返します。カテゴリが存在しない場合は、{{span style='color:blue;font-family:monospace;',dmAllCategories}} を返します。


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

'''目的'''

{{goto CategoryCreateList,CategoryCreateList()}} によってロックまたは割り当てられたメモリをロック解除または解放します。

'''定義されている場所'''

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

'''Prototype'''
 void CategoryFreeList (
 	DmOpenRef db,
 	ListType *listP,
 	Boolean showAll,
 	UInt32 editingStrID
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**カテゴリを収めているオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',→ listP}}
**カテゴリ リストへのポインタ（{{goto ListType,ListType}} を参照してください）
*{{span style='color:blue;font-family:monospace;',→ showAll}}
**リストが「すべて」カテゴリを持つように作成されている場合、{{span style='color:blue;font-family:monospace;',true}} です。
*{{span style='color:blue;font-family:monospace;',→ editingStrID}}
**{{span style='color:blue;font-family:monospace;',editingStrID}} パラメータとして {{goto CategoryCreateList,CategoryCreateList()}} に渡したリソース ID です。この関数は、指定したリソースのロックを解除します。

'''返り値'''

返り値はありません。

'''コメント'''

{{goto CategoryCreateList,CategoryCreateList()}} を明示的に呼び出した場合にのみ、この関数を呼び出す必要があります。通常のアプリケーションは、リストの作成と削除の両方をハンドルする {{span style='color:blue;font-family:monospace;',CategorySelect}} を呼び出します。

この関数は、ポップアップ リストである {{span style='color:blue;font-family:monospace;',listP}} の項目の配列に存在する項目の解放と、{{span style='color:blue;font-family:monospace;',CategoryCreateList}} がロックしていたかもしれない他のリソースのロックの解除を行います。

この関数は、渡されたデータベースからカテゴリを削除'''しません'''し、{{span style='color:blue;font-family:monospace;',listP}} によって指定される {{span style='color:blue;font-family:monospace;',ListType}} 構造体を解放'''しません'''。（通常、リストはリストのフォームが解放されたときに解放されます。）

'''互換性'''

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

'''参照'''

{{goto CategoryFreeListV10,CategoryFreeListV10()}}


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

{{goto CategoryCreateListV10,CategoryCreateListV10()}} によってロックまたは割り当てられたメモリをロック解除または解放します。

'''定義されている場所'''

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

'''Prototype'''
 void CategoryFreeListV10 (
 	DmOpenRef db,
 	ListType *lst
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**カテゴリを収めているオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',→ listP}}
**カテゴリ リストへのポインタ（{{goto ListType,ListType}} を参照してください）

'''返り値'''

返り値はありません。

'''互換性'''

この関数は、{{span style='color:blue;font-family:monospace;',CategoryFreeList}} の Palm OS 1.0 バージョンに相当します。この関数は古い関数です。

'''参照'''

{{goto CategoryFreeList,CategoryFreeList()}}


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

'''目的'''

指定されたカテゴリの名前を返します。

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

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

'''Prototype'''
 void CategoryGetName (
 	DmOpenRef db,
 	UInt16 index,
 	Char *name
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ dbP}}
**カテゴリを収めているデータベース。
*{{span style='color:blue;font-family:monospace;',→ index}}
**カテゴリ インデックス。これは、{{goto AppInfoType,AppInfoType}} 構造体にある {{span style='color:blue;font-family:monospace;',categoryLabels}} 配列へのインデックスです。データベース レコードの属性ワードからこのインデックスを調べることができます。
*{{span style='color:blue;font-family:monospace;',← name}}
**カテゴリ名を保持するためのバッファ。バッファのサイズは {{span style='color:blue;font-family:monospace;',dmCategoryLength}} にすべきです。

'''返り値'''

カテゴリ名を、渡された {{span style='color:blue;font-family:monospace;',name}} バッファに保存します。

インデックスが範囲外の場合、致命的なエラー メッセージを表示するかもしれません。

'''コメント'''

与えられたデータベース レコードのカテゴリ名を調べるためにこの関数を使用することができます。与えられたレコードからカテゴリ インデックスを取得するために {{goto DmRecordInfo,DmRecordInfo()|Palm OS Programmer's API Reference/30}} を使用してください。以下に例を挙げます。

 DmOpenRef myDB;
 UInt16 record, attr, category;
 Char *name;
  
 DmRecordInfo(myDB, record, &attr, NULL, NULL);
 category = attr & dmRecAttrCategoryMask;
 CategoryGetName(myDB, category, name);

カテゴリの名前は、{{span style='color:blue;font-family:monospace;',name}} パラメータに渡した変数にコピーされます。

'''参照'''

{{goto CategorySetName,CategorySetName()}}


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

'''目的'''

与えられたカテゴリの後にある、次のカテゴリのインデックスを返します。

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

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

'''Prototype'''
 UInt16 CategoryGetNext (
 	DmOpenRef db,
 	UInt16 index
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**カテゴリを収めているオープンされたデータベース。
*{{span style='color:blue;font-family:monospace;',→ index}}
**カテゴリ インデックス

'''返り値'''

次のカテゴリのカテゴリ インデックス。

'''コメント'''

ユーザにカテゴリを順番に巡らせることを意図してこの関数を使用します。例えば、ビルト-イン アプリケーションは、ユーザが対応するハード-キー ボタンを押したとき、カテゴリを順番に巡らせます。（サンプルのアドレス帳アプリケーションの {{span style='color:blue;font-family:monospace;',ListViewNextCategory}} を参照してください。）カテゴリは、カテゴリが保存された順番と同じ順番で表示されるわけではないことに注意してください。

特定のカテゴリを探すため、または、カテゴリ リストを反復するためにこの関数を使用しないでください。

'''互換性'''

Palm OS 1.0 では、システムは {{span style='color:blue;font-family:monospace;',Unfiled}} を 1 つのカテゴリとして選択します。

Palm OS 2.0 以降では、システムは {{span style='color:blue;font-family:monospace;',Unfiled}} と空のレコードを持つカテゴリの両方をスキップします。


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

'''目的'''

カテゴリの名前、ID、それにフラグを初期化します。

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

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

'''Prototype'''
 void CategoryInitialize (
 	AppInfoPtr appInfoP,
 	UInt16 localizedAppInfoStrID
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ appInfoP}}
**ロックされたアプリケーション情報ブロックへのポインタ。{{goto AppInfoType,AppInfoType}} を参照してください。
*{{span style='color:blue;font-family:monospace;',→ localizedAppInfoStrID}}
**ローカライズされたカテゴリ名のリソース ID。これは {{span style='color:blue;font-family:monospace;',appInfoStringsRsc}} （'{{span style='color:blue;font-family:monospace;',tAIS}}'）型のリソースでなければなりません。

'''返り値'''

返り値はありません。

'''コメント'''

データベース作成時に、データベースのカテゴリをローカライズされた文字列のリストによって初期化するためにこの関数を呼び出します。

{{span style='color:blue;font-family:monospace;',CategoryInitialize}} は、データベースに関連する {{goto AppInfoType,AppInfoType}} 構造体を初期化します。この関数が構造体を作成するわけではありません。構造体を作成するためには、（{{goto DmNewHandle,DmNewHandle()|Palm OS Programmer's API Reference/30}} を使って）その構造体をストレージ ヒープに割り当て、{{goto DmSetDatabaseInfo,DmSetDatabaseInfo()|Palm OS Programmer's API Reference/30}} を使ってそれをデータベースに関連付ける必要があります。

'''互換性'''

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


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

'''目的'''

カテゴリの選択と編集を行います。

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

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

'''Prototype'''
 Boolean CategorySelect (
 	DmOpenRef db,
 	const FormType *frm,
 	UInt16 ctlID,
 	UInt16 lstID,
 	Boolean title,
 	UInt16 *categoryP,
 	Char *categoryName,
 	UInt8 numUneditableCategories,
 	UInt32 editingStrID
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**カテゴリを保持しているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',→ frm}}
**カテゴリ ポップアップ リストを保持しているフォーム
*{{span style='color:blue;font-family:monospace;',→ ctlID}}
**ポップアップ トリガの ID
*{{span style='color:blue;font-family:monospace;',→ lstID}}
**ポップアップ リストの ID
*{{span style='color:blue;font-family:monospace;',→ title}}
**「すべて」というリスト項目を持つ場合は {{span style='color:blue;font-family:monospace;',true}} です。（一般に、フォームのタイトル バーのトリガは「すべて」項目を持つべきです。フォーム以外のトリガは持つべきではありません（訳者注: 持つ必要が無い？）。）
*{{span style='color:blue;font-family:monospace;',←→ categoryP}}
**選択されたカテゴリのインデックス。これは、{{span style='color:blue;font-family:monospace;',categoryLabels}} 配列のインデックスです。
*{{span style='color:blue;font-family:monospace;',←→ categoryName}}
**選択されたカテゴリの名前
*{{span style='color:blue;font-family:monospace;',→ numUneditableCategories }}
**ユーザが編集できないカテゴリの数。編集不可のカテゴリは {{span style='color:blue;font-family:monospace;',categoryLabels}} 配列の先頭に保存すべきです。例えば、一般に「未分類」カテゴリを編集不可である位置 0 に置きます。この関数は、編集不可のカテゴリをポップアップ リストの最後に表示します。
*{{span style='color:blue;font-family:monospace;',→ editingStrID}}
**カテゴリ編集リスト項目として使用される {{span style='color:blue;font-family:monospace;',tSTR}} リソースのリソース ID
**ユーザにカテゴリの編集をさせたくない場合、{{span style='color:blue;font-family:monospace;',categoryHideEditCategory}} 定数を渡してください。

'''返り値'''

以下の条件のいずれかが成り立てば、{{span style='color:blue;font-family:monospace;',true}} を返します。

*現在のカテゴリがリネームされる
*現在のカテゴリが削除される
*現在のカテゴリが他のカテゴリとマージされる

'''コメント'''

ユーザがカテゴリ ポップアップ リストをタップしたとき、この関数を呼び出します。この関数は、ポップアップ リストの表示とユーザの選択の管理に係わるすべてをハンドルします -- {{goto CategoryCreateList,CategoryCreateList()}} を使ってポップアップ リストを作成する、ポップアップ リストを表示する、ユーザがカテゴリ編集項目を選択した場合は {{goto CategoryEdit,CategoryEdit()}} を呼び出す、トリガ ラベルをユーザが選択した項目にセットするために {{goto CategorySetTriggerLabel,CategorySetTriggerLabel()}} を使用する、それに、リスト項目配列を解放するために {{goto CategoryFreeList,CategoryFreeList()}} を呼び出す。アプリケーションには、この関数が返る際に {{span style='color:blue;font-family:monospace;',categoryP}} の値をチェックし、ディスプレイの更新する、または、レコードのカテゴリを新しい選択に変更する責任があります。

'''互換性'''

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

{{span style='color:blue;font-family:monospace;',categoryDefaultEditCategoryString}} と {{span style='color:blue;font-family:monospace;',categoryHideEditCategory}} 定数は、{{goto 3.5 New Feature Set,3.5 New Feature Set|Palm OS Programmer's API Reference/B-1}} が存在する場合にのみ定義されます。それより前のバージョンでは、{{span style='color:blue;font-family:monospace;',editingStrID}} パラメータに 0 を渡すことで「カテゴリ編集」文字列を表示させなくする、または、渡すことでその項目をリストに含めることができます

'''参照'''

{{goto CategorySelectV10,CategorySelectV10()}}


!{{anchor CategorySelectV10}}CategoryCreateListV10 関数 {{goto top,^TOP^}}

'''目的'''

カテゴリの選択と編集を行います。

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

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

'''Prototype'''
 Boolean CategorySelectV10 (
 	DmOpenRef db,
 	const FormType *frm,
 	UInt16 ctlID,
 	UInt16 lstID,
 	Boolean title,
 	UInt16 *categoryP,
 	Char *categoryName
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**カテゴリを保持しているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',→ frm}}
**カテゴリ ポップアップ リストを保持しているフォーム
*{{span style='color:blue;font-family:monospace;',→ ctlID}}
**ポップアップ トリガの ID
*{{span style='color:blue;font-family:monospace;',→ lstID}}
**ポップアップ リストの ID
*{{span style='color:blue;font-family:monospace;',→ title}}
**「すべて」というリスト項目を持つ場合は {{span style='color:blue;font-family:monospace;',true}} です。（一般に、フォームのタイトル バーのトリガは「すべて」項目を持つべきです。フォーム以外のトリガは持つべきではありません（訳者注: 持つ必要が無い？）。）
*{{span style='color:blue;font-family:monospace;',←→ categoryP}}
**選択されたカテゴリのインデックス。これは、{{span style='color:blue;font-family:monospace;',categoryLabels}} 配列のインデックスです。
*{{span style='color:blue;font-family:monospace;',←→ categoryName}}
**選択されたカテゴリの名前

'''返り値'''

以下の条件のいずれかが成り立てば、{{span style='color:blue;font-family:monospace;',true}} を返します。

*現在のカテゴリがリネームされる
*現在のカテゴリが削除される
*現在のカテゴリが他のカテゴリとマージされる

'''互換性'''

この関数は、{{goto CategorySelect,CategorySelect()}} の Palm OS 1.0 バージョンに相当します。これは古い関数です。


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

'''目的'''

{{goto AppInfoType,AppInfoType}} 構造体にあるカテゴリ名を変更、または、カテゴリを削除します。

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

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

'''Prototype'''
 void CategorySetName (
 	DmOpenRef db,
 	UInt16 index,
 	const Char *nameP
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',→ db}}
**変更するカテゴリを保持しているオープンされたデータベース
*{{span style='color:blue;font-family:monospace;',→ index}}
**リネームするカテゴリのインデックス
*{{span style='color:blue;font-family:monospace;',→ nameP}}
**新しいカテゴリ名（null で終了する）、または、カテゴリを削除する場合は {{span style='color:blue;font-family:monospace;',NULL}}

'''返り値'''

返り値はありません。

'''コメント'''

ユーザが新しいカテゴリを作成したとき、または、カテゴリ編集ダイアログに存在しているカテゴリをリネームしたとき、{{goto CategoryEdit,CategoryEdit()}} 関数がこの関数を呼び出します。アプリケーションがこの関数を直接呼び出す必要はありません。

'''互換性'''

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

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

'''目的'''

カテゴリ ポップアップ トリガによって表示されるラベルをセットします。

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

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

'''Prototype'''
 void CategorySetTriggerLabel (
 	ControlType *ctl,
 	Char *name
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',←→ ctl}}
**ラベルを張替えるコントロール オブジェクト（ポップアップ トリガ）へのポインタ
*{{span style='color:blue;font-family:monospace;',←→ name}}
**新しいカテゴリ名へのポインタ

'''返り値'''

返り値はありません。

'''コメント'''

{{span style='color:blue;font-family:monospace;',CategorySetTriggerLabel}} 関数は、カテゴリ名を最大長に切り詰めるために {{goto CategoryTruncateName,CategoryTruncateName()}} 関数を呼び出します。最大長の値は、デバイスにインストールされている ROM に依存します。

//----
//'''NOTE:''' この関数は {{span style='color:blue;font-family:monospace;',name}} パラメータを {{span style='color:blue;font-family:monospace;',CategoryTruncateName}} 関数に渡します。これが意味するのは、{{span style='color:blue;font-family:monospace;',name}} 値は変更可能でなければならないということです。{{span style='color:blue;font-family:monospace;',CategorySetTriggerLabel}} は渡された文字列をコピーしません、つまり、フォームがクローズされるまでその文字列が有効であり続けることを保証しなければならないということです。
//----
::NOTE
:::この関数は {{span style='color:blue;font-family:monospace;',name}} パラメータを {{span style='color:blue;font-family:monospace;',CategoryTruncateName}} 関数に渡します。これが意味するのは、{{span style='color:blue;font-family:monospace;',name}} 値は変更可能でなければならないということです。{{span style='color:blue;font-family:monospace;',CategorySetTriggerLabel}} は渡された文字列をコピーしません、つまり、フォームがクローズされるまでその文字列が有効であり続けることを保証しなければならないということです。


'''参照'''

{{goto CtlSetLabel,CtlSetLabel()|Palm OS Programmer's API Reference/7}}


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

'''目的'''

カテゴリ名を、表示できる長さになるよう、切り詰めます。カテゴリ名が {{span style='color:blue;font-family:monospace;',maxWidth}} よりも長い場合、切り詰められます。

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

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

'''Prototype'''
 void CategoryTruncateName (
 	Char *name,
 	UInt16 maxWidth
 )

'''パラメータ'''
*{{span style='color:blue;font-family:monospace;',←→ name}}
**切り詰めるカテゴリ名。返りには、切り詰められたカテゴリ名を保持しています。
*{{span style='color:blue;font-family:monospace;',→ maxWidth}}
**切り詰められたカテゴリ名（省略記号を含む）の最大サイズ（ピクセル単位）

'''返り値'''

返り値はありません。
{{div_end}}

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