Palm Programmer's Laboratory
Palm OS Programmer's API Reference/5
この章では、ヘッダ ファイル Category.h で宣言されたカテゴリ API について説明します。以下のトピックについて説明します。
カテゴリについての追加情報は、Palm OS Programmer's Companion, vol. I の 「カテゴリ」 セクションを参照してください。
カテゴリ データ構造体 ^TOP^
AppInfoPtr 型 ^TOP^
目的
AppInfoPrt は AppInfoType 構造体へのポインタを定義します。
Prototype
typedef AppInfoType *AppInfoPtr;
AppInfoType 型 ^TOP^
目的
以下で示す AppInfoType 構造体は、カテゴリ名をカテゴリ インデックスと固有のIDへマッピングします。この章で説明されるカテゴリ API を使うためには、データベースのアプリケーション情報ブロックは AppInfoType 構造体であるか、その最初のフィールドに AppInfoType 構造体を持たなくてはなりません。
Prototype
typedef struct { UInt16 renamedCategories; Char categoryLabels [dmRecNumCategories] [dmCategoryLength]; UInt8 categoryUniqIDs[dmRecNumCategories]; UInt8 lastUniqID; UInt8 padding; } AppInfoType;
フィールド
- renamedCategories
- CategorySetName() によって、リネームされたカテゴリを示すビット フィールドとして使用されます。通常、Conduit によって消去されます。(訳者注: Conduit とは母艦とPalmとでデータを同期させる設定書類)
- categoryLabels
- カテゴリ名を収納する文字列の配列。この配列の最大サイズは dmRecNumCategorie であり、配列の各要素の最大長は dmCategoryLength です。これらの定数は 2 つとも DataMgr.h で定義されます。
- categoryUniqIDs
- デスクトップ データベースとの同期をとるために使用される カテゴリ ID。デバイスによって、0 から 127 の範囲の固有の ID が生成されます。デスクトップ コンピュータによって、128 から 255 の範囲の固有の ID が生成されます。
- lastUniqID
- ソートと固有の ID を割り当てるのに使用されます。
コメント
アプリケーション情報ブロックをストレージ ヒープに割り当て、データベースのアプリケーション情報 ID をこの構造体のローカル ID にセットするために DmSetDatabaseInfo() 関数を使用してください。それから、カテゴリ名を保持している文字列のローカライズされたリストでそれ(訳者注: アプリケーション情報ブロックであろう)を初期化するために CategoryInitialize() 関数を使用してください。
カテゴリ定数 ^TOP^
以下のカテゴリ定数が定義されています。
定数 | 値 | 説明 |
---|---|---|
categoryHideEditCategory | 10000 | 「カテゴリ編集」項目を抑制するのに使用されます。 |
categoryDefaultEditCategoryString | 10001 | デフォルトの「カテゴリ編集」項目を表示するのに使用されます。 |
- NOTE
- これらの定数はシステム リソース ID のように見えるかもしれませんが、そうではありません。「カテゴリ編集」項目にデフォルトではない文字列を使用するには、タイトル文字列のリソース ID を渡します。デフォルトまたは隠れた項目を使用したい場合は、これらの定数を渡します。パラメータとして使用される可能性のある他の値と衝突するのを防ぐため、これらの値はシステム リソース ID の範囲にします(10000以上)。
互換性
categoryHideEditCategory と categoryDefaultEditCategoryString はどちらも 3.5 New Feature Set が存在する場合にのみ定義されます。
カテゴリ関数 ^TOP^
CategoryCreateList 関数 ^TOP^
目的
ポップアップ リストをデータベースのカテゴリに実装します。
宣言されている場所
Category.h
Prototype
void CategoryCreateList ( DmOpenRef db, ListType *listP, UInt16 currentCategory, Boolean showAll, Boolean showUneditables, UInt8 numUneditableCategories, UInt32 editingStrID, Boolean resizeList )
パラメータ
- → db
- 調べたいカテゴリ情報を収めているオープンされたデータベース
- ← listP
- カテゴリを表示する ListType 構造体へのポインタ
- → currentCategory
- 選択するカテゴリのインデックス。これは、categoryLabels 配列のインデックスです。デフォルトでは「未分類」カテゴリを選択しています。
- → showAll
- 「すべて」のリスト項目を含む場合は、true です。
- → showUneditables
- 編集不可のカテゴリを表示する場合は、true です。
- → numUneditableCategories
- ユーザが編集できないカテゴリの数です。編集不可のカテゴリを categoryLabels 配列の先頭に置くべきです。例えば、一般的に「未分類」カテゴリを編集不可である 0 の位置に置きます。この関数は編集不可のカテゴリをポップアップ リストの最後に表示します。
- → editingStrID
- 「カテゴリ編集」リスト項目として使用する tStr リソースのリソース ID です。デフォルト文字列(「カテゴリ編集」)を使用するためには、定数 categoryDefaultEditCategoryString を渡します。ユーザにカテゴリ編集をさせたくない場合は、定数 categoryHideEditCategory を渡します。
- → resizeList
- カテゴリ数のリストをリサイズする場合は、true です。ポップアップには true を、それ以外には false をセットします。
返り値
返り値はありません。
コメント
「すべて」項目がリストの先頭にきます(showAll パラメータが true の場合)。データベースにある編集可能なカテゴリがそのあとに続き、編集不可のカテゴリはそのあとになります。カテゴリを編集するためのオプションは、リストの最後で、無くすこともできます。
この関数が直接呼び出されることはほとんどありません。そのかわり、たいていのアプリケーションはこの関数を呼び出す CategorySelect() を使用し、それにより、ユーザがポップアップ リストにあるカテゴリを選択するのを完全に管理しています。
この関数は、db パラメータの appInfoID を取得し、それが示す AppInfoType 構造体を読み、その情報を listP が示すデータベースのカテゴリの名前を収めた配列を初期化するのに使用します。あらかじめ listP によって示される構造体を配置しておかなくてはなりません。CategoryCreateList はリストを表示しません。表示するには、LstPopupList() か LstDrawList() を使用してください。
CategoryCreateList の呼び出しと CategoryFreeList() の呼び出しとのバランスをとらなくてはなりません。CategoryCreateList 関数はカテゴリ名のリソースをロックします。また、この関数は listP が示す配列を配置します。CategoryFreeList は、CategoryCreateList によってロックされたすべてのリソースのロックを外し、CategoryCreateList によって使用されていたすべてのメモリを解放します。
互換性
2.0 New Feature Set が存在する場合にのみ実装されます。
categoryDefaultEditCategoryString, categoryHideEditCategory 定数は、3.5 New Feature Set が存在する場合にのみ定義されます。それより前のバージョンでは、editingStrID パラメータに 0 を渡すことで「カテゴリ編集」文字列を表示させなくする、または、渡すことでその項目をリストに含めることができます
参照
CategoryCreateListV10()
CategoryCreateListV10 関数 ^TOP^
目的
データベースのカテゴリを読み込み、カテゴリ リストをセットします。
定義する場所
Category.h
Prototype
void CategoryCreateListV10 ( DmOpenRef db, ListType *lst, UInt16 currentCategory, Boolean showAll )
パラメータ
- → db
- 調べたいカテゴリ情報を収めているオープンされたデータベース
- ← listP
- カテゴリを表示する ListType 構造体へのポインタ
- → currentCategory
- 選択するカテゴリのインデックス。これは、categoryLabels 配列のインデックスです。デフォルトでは「未分類」カテゴリを選択しています。
- → showAll
- 「すべて」のリスト項目を含む場合は、true です。
返り値
返り値はありません。
互換性
この関数は CategoryCreateList() の Palm OS 1.0 バージョン に相当します。これは古い関数です。
CategoryEdit 関数 ^TOP^
目的
「カテゴリ編集」ダイアログのイベント ハンドラ
定義されている場所
Category.h
Prototype
Boolean CategoryEdit ( DmOpenRef db, UInt16 *category, UInt32 titleStrID, UInt8 numUneditableCategories )
パラメータ
- → db
- 編集するカテゴリを収めているオープンされたデータベース
- ← category
- この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。
- → titleStrID
- ダイアログのタイトルとして使用する tSTR リソースのリソース ID です。デフォルトの文字列(「カテゴリ編集」)を使用するには、categoryDefaultEditCategoryString 定数を渡します。
- → numUneditableCategories
- ユーザが編集できないカテゴリの数です。編集不可のカテゴリは categoryLabels 配列の先頭に保存すべきです。例えば、通常は「未分類」カテゴリを編集不可の 0 の位置におきます。
返り値
以下の条件のいずれかが成り立てば、true を返します。
- 現在のカテゴリがリネームされる
- 現在のカテゴリが削除される
- 現在のカテゴリが他のカテゴリとマージされる
コメント
この関数が直接呼び出されることはほとんどありません。ユーザがカテゴリ編集リスト項目を選択するときに、CategorySelect() 関数がこの関数を呼び出します。
この関数は、カテゴリ編集ダイアログの表示とユーザ アクションの結果のハンドルの両方を行います。この関数は、AppInfoType 構造体のカテゴリのリストを更新し、必要があればデータベース レコードを新しいカテゴリに再配置します。ユーザがカテゴリを削除すると、CategoryEdit が、削除されたカテゴリに属していたすべてのレコードを未分類カテゴリに移動させます。あるカテゴリが、すでに存在しているカテゴリと同じ名前にリネームされると、この関数は古いカテゴリのすべてのレコードを新しいカテゴリに移動させます。
互換性
3.5 New Feature Set が存在する場合にのみ実装されます。
参照
CategoryEditV20(), CategoryEditV10(), DmMoveCategory()
CategoryEditV20 関数 ^TOP^
目的
「カテゴリ編集」ダイアログのイベント ハンドラ
定義されている場所
Category.h
Prototype
Boolean CategoryEditV20 ( DmOpenRef db, UInt16 *category, UInt32 titleStrID )
パラメータ
- → db
- 編集するカテゴリを収めているオープンされたデータベース。
- ← category
- この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。
- → titleStrID
- ダイアログのタイトルとして使用される tSTR リソースのリソース ID です。
返り値
以下の条件がいずれかが成り立てば、true を返します。
- 現在のカテゴリがリネームされる
- 現在のカテゴリが削除される
- 現在のカテゴリが他のカテゴリとマージされる
互換性
この関数は CategoryEdit の Palm OS 2.0 バージョンに相当します。2.0 New Feature Set が存在する場合にのみ実装されます。これは古い関数です。
参照
CategoryEdit(), CategoryEditV10()
CategoryEditV10 関数 ^TOP^
目的
「カテゴリ編集」ダイアログのイベント ハンドラ
定義されている場所
Category.h
Prototype
Boolean CategoryEditV10 ( DmOpenRef db )
パラメータ
- → db
- 編集するカテゴリを収めているオープンされたデータベース。
- ← category
- この返り値に、このダイアログがクローズされる前の最後に選択されていたカテゴリのインデックスが収められています。
返り値
以下の条件がいずれかが成り立てば、true を返します。
- 現在のカテゴリがリネームされる
- 現在のカテゴリが削除される
- 現在のカテゴリが他のカテゴリとマージされる
互換性
この関数は CategoryEdit の Palm OS 1.0 バージョンに相当します。これは古い関数です。
参照
CategoryEdit(), CategoryEditV20()
CategoryFind 関数 ^TOP^
目的
与えられた名前を持つカテゴリのインデックスを返します。
定義されている場所
Category.h
Prototype
UInt16 CategoryFind ( DmOpenRef db, const Char *name )
パラメータ
- → db
- 検索するオープンされたデータベース。
- → name
- カテゴリ名です。最初の使用されていないカテゴリを検索する場合、空の文字列を渡してください。
返り値
categoryLabels 配列(AppInfoType を参照してください)にあるカテゴリのエントリのインデックスを返します。カテゴリが存在しない場合は、dmAllCategories を返します。
CategoryFreeList 関数 ^TOP^
目的
CategoryCreateList() によってロックまたは割り当てられたメモリをロック解除または解放します。
定義されている場所
Category.h
Prototype
void CategoryFreeList ( DmOpenRef db, ListType *listP, Boolean showAll, UInt32 editingStrID )
パラメータ
- → db
- カテゴリを収めているオープンされたデータベース。
- → listP
- カテゴリ リストへのポインタ(ListType を参照してください)
- → showAll
- リストが「すべて」カテゴリを持つように作成されている場合、true です。
- → editingStrID
- editingStrID パラメータとして CategoryCreateList() に渡したリソース ID です。この関数は、指定したリソースのロックを解除します。
返り値
返り値はありません。
コメント
CategoryCreateList() を明示的に呼び出した場合にのみ、この関数を呼び出す必要があります。通常のアプリケーションは、リストの作成と削除の両方をハンドルする CategorySelect を呼び出します。
この関数は、ポップアップ リストである listP の項目の配列に存在する項目の解放と、CategoryCreateList がロックしていたかもしれない他のリソースのロックの解除を行います。
この関数は、渡されたデータベースからカテゴリを削除しませんし、listP によって指定される ListType 構造体を解放しません。(通常、リストはリストのフォームが解放されたときに解放されます。)
互換性
2.0 New Feature Set が存在する場合にのみ実装されます。
参照
CategoryFreeListV10 関数 ^TOP^
CategoryCreateListV10() によってロックまたは割り当てられたメモリをロック解除または解放します。
定義されている場所
Category.h
Prototype
void CategoryFreeListV10 ( DmOpenRef db, ListType *lst )
パラメータ
- → db
- カテゴリを収めているオープンされたデータベース。
- → listP
- カテゴリ リストへのポインタ(ListType を参照してください)
返り値
返り値はありません。
互換性
この関数は、CategoryFreeList の Palm OS 1.0 バージョンに相当します。この関数は古い関数です。
参照
CategoryGetName 関数 ^TOP^
目的
指定されたカテゴリの名前を返します。
宣言されている場所
Category.h
Prototype
void CategoryGetName ( DmOpenRef db, UInt16 index, Char *name )
パラメータ
- → dbP
- カテゴリを収めているデータベース。
- → index
- カテゴリ インデックス。これは、AppInfoType 構造体にある categoryLabels 配列へのインデックスです。データベース レコードの属性ワードからこのインデックスを調べることができます。
- ← name
- カテゴリ名を保持するためのバッファ。バッファのサイズは dmCategoryLength にすべきです。
返り値
カテゴリ名を、渡された name バッファに保存します。
インデックスが範囲外の場合、致命的なエラー メッセージを表示するかもしれません。
コメント
与えられたデータベース レコードのカテゴリ名を調べるためにこの関数を使用することができます。与えられたレコードからカテゴリ インデックスを取得するために DmRecordInfo() を使用してください。以下に例を挙げます。
DmOpenRef myDB; UInt16 record, attr, category; Char *name; DmRecordInfo(myDB, record, &attr, NULL, NULL); category = attr & dmRecAttrCategoryMask; CategoryGetName(myDB, category, name);
カテゴリの名前は、name パラメータに渡した変数にコピーされます。
参照
CategoryGetNext 関数 ^TOP^
目的
与えられたカテゴリの後にある、次のカテゴリのインデックスを返します。
宣言されている場所
Category.h
Prototype
UInt16 CategoryGetNext ( DmOpenRef db, UInt16 index )
パラメータ
- → db
- カテゴリを収めているオープンされたデータベース。
- → index
- カテゴリ インデックス
返り値
次のカテゴリのカテゴリ インデックス。
コメント
ユーザにカテゴリを順番に巡らせることを意図してこの関数を使用します。例えば、ビルト-イン アプリケーションは、ユーザが対応するハード-キー ボタンを押したとき、カテゴリを順番に巡らせます。(サンプルのアドレス帳アプリケーションの ListViewNextCategory を参照してください。)カテゴリは、カテゴリが保存された順番と同じ順番で表示されるわけではないことに注意してください。
特定のカテゴリを探すため、または、カテゴリ リストを反復するためにこの関数を使用しないでください。
互換性
Palm OS 1.0 では、システムは Unfiled を 1 つのカテゴリとして選択します。
Palm OS 2.0 以降では、システムは Unfiled と空のレコードを持つカテゴリの両方をスキップします。
CategoryInitialize 関数 ^TOP^
目的
カテゴリの名前、ID、それにフラグを初期化します。
宣言されている場所
Category.h
Prototype
void CategoryInitialize ( AppInfoPtr appInfoP, UInt16 localizedAppInfoStrID )
パラメータ
- → appInfoP
- ロックされたアプリケーション情報ブロックへのポインタ。AppInfoType を参照してください。
- → localizedAppInfoStrID
- ローカライズされたカテゴリ名のリソース ID。これは appInfoStringsRsc ('tAIS')型のリソースでなければなりません。
返り値
返り値はありません。
コメント
データベース作成時に、データベースのカテゴリをローカライズされた文字列のリストによって初期化するためにこの関数を呼び出します。
CategoryInitialize は、データベースに関連する AppInfoType 構造体を初期化します。この関数が構造体を作成するわけではありません。構造体を作成するためには、(DmNewHandle() を使って)その構造体をストレージ ヒープに割り当て、DmSetDatabaseInfo() を使ってそれをデータベースに関連付ける必要があります。
互換性
2.0 New Feature Set が存在する場合にのみ実装されます。
CategorySelect 関数 ^TOP^
目的
カテゴリの選択と編集を行います。
宣言されている場所
Category.h
Prototype
Boolean CategorySelect ( DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName, UInt8 numUneditableCategories, UInt32 editingStrID )
パラメータ
- → db
- カテゴリを保持しているオープンされたデータベース
- → frm
- カテゴリ ポップアップ リストを保持しているフォーム
- → ctlID
- ポップアップ トリガの ID
- → lstID
- ポップアップ リストの ID
- → title
- 「すべて」というリスト項目を持つ場合は true です。(一般に、フォームのタイトル バーのトリガは「すべて」項目を持つべきです。フォーム以外のトリガは持つべきではありません(訳者注: 持つ必要が無い?)。)
- ←→ categoryP
- 選択されたカテゴリのインデックス。これは、categoryLabels 配列のインデックスです。
- ←→ categoryName
- 選択されたカテゴリの名前
- → numUneditableCategories
- ユーザが編集できないカテゴリの数。編集不可のカテゴリは categoryLabels 配列の先頭に保存すべきです。例えば、一般に「未分類」カテゴリを編集不可である位置 0 に置きます。この関数は、編集不可のカテゴリをポップアップ リストの最後に表示します。
- → editingStrID
- カテゴリ編集リスト項目として使用される tSTR リソースのリソース ID
- ユーザにカテゴリの編集をさせたくない場合、categoryHideEditCategory 定数を渡してください。
返り値
以下の条件のいずれかが成り立てば、true を返します。
- 現在のカテゴリがリネームされる
- 現在のカテゴリが削除される
- 現在のカテゴリが他のカテゴリとマージされる
コメント
ユーザがカテゴリ ポップアップ リストをタップしたとき、この関数を呼び出します。この関数は、ポップアップ リストの表示とユーザの選択の管理に係わるすべてをハンドルします -- CategoryCreateList() を使ってポップアップ リストを作成する、ポップアップ リストを表示する、ユーザがカテゴリ編集項目を選択した場合は CategoryEdit() を呼び出す、トリガ ラベルをユーザが選択した項目にセットするために CategorySetTriggerLabel() を使用する、それに、リスト項目配列を解放するために CategoryFreeList() を呼び出す。アプリケーションには、この関数が返る際に categoryP の値をチェックし、ディスプレイの更新する、または、レコードのカテゴリを新しい選択に変更する責任があります。
互換性
2.0 New Feature Set が存在する場合にのみ実装されます。
categoryDefaultEditCategoryString と categoryHideEditCategory 定数は、3.5 New Feature Set が存在する場合にのみ定義されます。それより前のバージョンでは、editingStrID パラメータに 0 を渡すことで「カテゴリ編集」文字列を表示させなくする、または、渡すことでその項目をリストに含めることができます
参照
CategoryCreateListV10 関数 ^TOP^
目的
カテゴリの選択と編集を行います。
宣言されている場所
Category.h
Prototype
Boolean CategorySelectV10 ( DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName )
パラメータ
- → db
- カテゴリを保持しているオープンされたデータベース
- → frm
- カテゴリ ポップアップ リストを保持しているフォーム
- → ctlID
- ポップアップ トリガの ID
- → lstID
- ポップアップ リストの ID
- → title
- 「すべて」というリスト項目を持つ場合は true です。(一般に、フォームのタイトル バーのトリガは「すべて」項目を持つべきです。フォーム以外のトリガは持つべきではありません(訳者注: 持つ必要が無い?)。)
- ←→ categoryP
- 選択されたカテゴリのインデックス。これは、categoryLabels 配列のインデックスです。
- ←→ categoryName
- 選択されたカテゴリの名前
返り値
以下の条件のいずれかが成り立てば、true を返します。
- 現在のカテゴリがリネームされる
- 現在のカテゴリが削除される
- 現在のカテゴリが他のカテゴリとマージされる
互換性
この関数は、CategorySelect() の Palm OS 1.0 バージョンに相当します。これは古い関数です。
CategorySetName 関数 ^TOP^
目的
AppInfoType 構造体にあるカテゴリ名を変更、または、カテゴリを削除します。
宣言されている場所
Category.h
Prototype
void CategorySetName ( DmOpenRef db, UInt16 index, const Char *nameP )
パラメータ
- → db
- 変更するカテゴリを保持しているオープンされたデータベース
- → index
- リネームするカテゴリのインデックス
- → nameP
- 新しいカテゴリ名(null で終了する)、または、カテゴリを削除する場合は NULL
返り値
返り値はありません。
コメント
ユーザが新しいカテゴリを作成したとき、または、カテゴリ編集ダイアログに存在しているカテゴリをリネームしたとき、CategoryEdit() 関数がこの関数を呼び出します。アプリケーションがこの関数を直接呼び出す必要はありません。
互換性
2.0 New Feature Set が存在する場合にのみ実装されます。
CategorySetTriggerLabel 関数 ^TOP^
目的
カテゴリ ポップアップ トリガによって表示されるラベルをセットします。
宣言されている場所
Category.h
Prototype
void CategorySetTriggerLabel ( ControlType *ctl, Char *name )
パラメータ
- ←→ ctl
- ラベルを張替えるコントロール オブジェクト(ポップアップ トリガ)へのポインタ
- ←→ name
- 新しいカテゴリ名へのポインタ
返り値
返り値はありません。
コメント
CategorySetTriggerLabel 関数は、カテゴリ名を最大長に切り詰めるために CategoryTruncateName() 関数を呼び出します。最大長の値は、デバイスにインストールされている ROM に依存します。
- NOTE
- この関数は name パラメータを CategoryTruncateName 関数に渡します。これが意味するのは、name 値は変更可能でなければならないということです。CategorySetTriggerLabel は渡された文字列をコピーしません、つまり、フォームがクローズされるまでその文字列が有効であり続けることを保証しなければならないということです。
参照
CategoryTruncateName 関数 ^TOP^
目的
カテゴリ名を、表示できる長さになるよう、切り詰めます。カテゴリ名が maxWidth よりも長い場合、切り詰められます。
宣言されている場所
Category.h
Prototype
void CategoryTruncateName ( Char *name, UInt16 maxWidth )
パラメータ
- ←→ name
- 切り詰めるカテゴリ名。返りには、切り詰められたカテゴリ名を保持しています。
- → maxWidth
- 切り詰められたカテゴリ名(省略記号を含む)の最大サイズ(ピクセル単位)
返り値
返り値はありません。