Palm OS Programmer's API Reference/15

←　14 章に戻る　↑トップへ　16 章に進む　→

15 メニュー

• メニュー データ構造体
  • MenuBarAttrType
  • MenuCmdBarButtonType
  • MenuCmdBarResultType
  • MenuCmdBarType
  • MenuBarPtr
  • MenuBarType
  • MenuItemType
  • MenuPullDownPtr
  • MenuPullDownType
• メニュー定数
• メニュー リソース
• メニュー関数
  • MenuAddItem
  • MenuCmdBarAddButton
  • MenuCmdBarDisplay
  • MenuCmdBarGetButtonData
  • MenuDispose
  • MenuDrawMenu
  • MenuEraseStatus
  • MenuGetActiveMenu
  • MenuHandleEvent
  • MenuHideItem
  • MenuInit
  • MenuSetActiveMenu
  • MenuSetActiveMenuRscID
  • MenuShowItem

この章では、ヘッダ ファイル Menu.h で定義されている、メニュー API について説明します。以下のことについて説明します。

• メニュー データ構造体
• メニュー定数
• メニュー リソース
• メニュー関数

メニューについての追加情報は、Palm OS Programmer's Companion, vol. I の「メニュー」を参照してください。

メニュー データ構造体 ^TOP^

MenuBarAttrType 構造体 ^TOP^

目的

MenuBarAttrType ビット フィールドはメニュー バーの特性を定義します。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuBarAttrType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct {
	UInt16 visible : 1;
	UInt16 commandPending : 1;
	UInt16 insPtEnabled : 1;
	UInt16 needsRecalc : 1;
} MenuBarAttrType;

コードは MenuBarAttrType を実体の無いものとして扱うべきです。各値を取得、セットするために、以下の説明で指定される関数を使用してください。構造体メンバを直接変更しようとしないでください。

フィールド

• visible
  • セットされている場合、メニュー バーは描かれ、スクリーン上で可視になります。この属性は、メニューが描かれるときに呼び出される MenuDrawMenu() の中でセットされます。
• commandPending
  • セットされている場合、メニュー コマンド ショートカットは進行中です。このビットは、メニュー ショートカット キー入力を受け取った場合に {{MenuHandleEvent,MenuHandleEvent()}} の中でセットされます。タイムアウト値が届く前に次のキーを受け取った場合、キーは有効なメニュー コマンドかどうかチェックされます。
• insPtEnabled
  • メニューが描かれた時点での挿入ポイントの状態を保存します。それにより、メニューが消されたときに挿入ポイントの状態を元に戻すことが可能です。
• needsRecalc
  • セットされている場合、メニューの次元（サイズ？）を再計算します。

互換性

3.5 New Feature Set が存在する場合にのみ、needsRecalc は存在します。

MenuCmdBarButtonType 構造体 ^TOP^

目的

MenuCmdBarButtonType 構造体はコマンド バー上に表示されるボタンを定義します。MenuCmdBarType 構造体の buttonsData フィールドはこの構造体の配列を保持します。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuCmdBarButtonType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct {
	UInt16 bitmapId;
	Char name[menuCmdBarMaxTextLength];
	MenuCmdBarResultType resultType;
	UInt8 reserved;
	UInt32 result;
} MenuCmdBarButtonType;

コードは MenuBarAttrType を実体の無いものとして扱うべきです。構造体メンバを直接変更しようとしないでください。その代わり、表示されるボタンを追加するために MenuCmdBarAddButton() を使用してください。MenuCmdBarAddButton のパラメータは MenuCmdBarButtonType のフィールドとほとんど同じです。そのため、このフィールドを直接変更する必要はないはずです。

MenuBarGetButtonData() を使ってコマンド バー ボタンについての情報にアクセスすることができます。

フィールド

• bitmapId
  • ボタン上に表示されるビットマップのリソース ID。このビットマップは高さ 13 ピクセル×幅 16 ピクセルにすべきです。
• name
  • ユーザがボタンをタップしたときステータス メッセージに表示されるテキスト。
• resultType
  • result フィールドに保持されるデータの型を指定します。MenuCmdBarResultType を参照してください。
• reserved
  • 将来使用するために予約されています。
• result
  • ユーザがボタンをクリックしたときに送られるデータを指定します。データは resultType で指定された型であると解釈されます。結果は keyDownEvent の中に加えられるショートカット文字、menuEvent の中に加えられるアイテム ID、あるいはブロードキャストされる通知になる可能性があります。

互換性

この構造体は、3.5 New Feature Set が存在する場合にのみ、定義されます。

MenuCmdBarRedultType 列挙体 ^TOP^

目的

MenuCmdBarResultType 列挙体は MenuCmdBarButtonType 構造体の中の result フィールドがどのように解釈されるべきなのかを指定します。

Prototype

typedef enum {
	menuCmdBarResultNone,
	menuCmdBarResultChar,
	menuCmdBarResultMenuItem,
	menuCmdBarResultNotify
} MenuCmdBarResultType;

定数

• menuCmdBarResultNone
  • 何も送りません。
• menuCmdBarResultChar
  • 結果は keyDownEvent の中に送られる文字です。
• menuCmdBarResultMenuItem
  • 結果は menuEvent の中に送られるメニュー アイテムの ID です。
• menuCmdBarResultNotify
  • 結果は SysNotifyBroadcastDeferred()|Palm OS Programmer's API Reference/43 を使ってブロードキャストされる通知定数です。

互換性

この列挙体は、3.5 New Feature Set が存在する場合にのみ、定義されます。

MenuCmdBarType 構造体 ^TOP^

目的

MenuCmdBarType 構造体はコマンド ツールバーを定義します。このコマンド ツールバーは、ユーザが入力エリアにショートカット キー入力をしたときに、割り当てられ、表示されます。MenuEraseStatus() が呼び出されたときに、割り当てを解除されます。これはたいていタイムアウト値が経過したときに起こります。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuCmdBarType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct MenuCmdBarType {
	WinHandle bitsBehind;
	Int32 timeoutTick;
	Coord top;
	Int16 numButtons;
	Boolean insPtWasEnabled;
	Boolean gsiWasEnabled;
	Boolean feedbackMode;
	MenuCmdBarButtonType *buttonsData;
} MenuCmdBarType;

コードは MenuCmdBarType を実体の無いものとして扱うべきです。構造体メンバを直接変更しようとしないでください。

フィールド

• bitsBehid
  • コマンド ツールバーによって隠される領域を保持するウィンドウのためのハンドル。
• timeoutTick
  • システム時計に与えられるタイムアウト値。この値の時間が経過した時点でユーザがコマンドを指定していなければ、コマンド ツールバーはスクリーンから消され、メモリの割り当てを解除されます。この値はまた、ユーザがコマンド入力に成功した場合にどれくらいの時間ステータス メッセージを表示するかも指定します。
• top
  • コマンド ツールバーの上端の境界位置をディスプレイからの相対座標で示します。コマンド ツールバーの幅はスクリーンの幅と等しく、スクリーンの最下段に表示されます。
• numButtons
  • コマンド ツールバー上に表示されるボタンの数。
• insPtWasEnabled
  • true の場合、コマンド ツールバーが表示される前の時点で挿入ポイントは使用可能であって、コマンド ツールバーが消されるときに挿入ポイントを再度使用可能にするべきです。false の場合、挿入ポイントは使用不可でした。
• gsiWasEnabled
  • true の場合、コマンド ツールバーが表示される前の時点でシフト指示子は使用可能であって、コマンド ツールバーが消されるときにシフト指示子を再度使用可能にするべきです。false の場合、シフト指示子は使用不可でした。
• feedbackMode
  • true の場合、コマンド ツールバーは現在ステータス メッセージを表示しています。ステータス メッセージはユーザに実行されようとしているコマンドは何なのかを知らせるために表示されます。false の場合、コマンド ツールバーは入力待ちの状態です。
• buttonsData
  • コマンド ツールバー上に表示されるボタンのリスト。MenuCmdBarButtonType を参照してください。ボタンはこのリストに右端のボタン（インデックス 0）から順に保存されています。MenuCmdBarGetButtonData() を使ってアクセスします。

互換性

この構造体は、3.5 New Feature Set が存在する場合にのみ、定義されます。

MenuBarPtr Typedef ^TOP^

目的

MenuBarPtr 型は MenuBarType へのポインタを定義します。

Prototype

typedef MenuBarType *MenuBarPtr;

MenuBarType 構造体 ^TOP^

目的

MenuBarType 構造体はメニュー バーを定義します。フォームごとに 1 つのメニュー バーがあります。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuBarType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct {
	WinHandle barWin;
	WinHandle bitsBehind;
	WinHandle savedActiveWin;
	WinHandle bitsBehindStatus;
	MenuBarAttrType attr;
	Int16 curMenu;
	Int16 curItem;
	Int32 commandTick;
	Int16 numMenus;
	MenuPullDownPtr menus;
} MenuBarType;

コードは MenuBarType を実体の無いものとして扱うべきです。構造体メンバを直接変更しようとしないでください。

フィールド

• barWin
  • メニュー バーを保持するウィンドウのためのハンドル
• bitsBehid
  • コマンド ツールバーによって隠される領域を保持するウィンドウのためのハンドル。
• saveActiveWin
  • 現在アクティブなウィンドウを保存しておくためのハンドル。これにより、メニューが消されたときにウィンドウを元に戻すことが可能です。
• bitsBehindStatus
  • ステータス メッセージの背後にあるビットを保存しておくためのハンドル。これにより、メッセージが消されたときにビットを元に戻すことが可能です。ステータス メッセージは、ユーザがコマンド キー入力をしてメニューをアクティブにしたときに、表示されます。
• attr
  • メニュ バー属性。MenuBarAttrType を参照してください。
• curMenu
  • 現在可視のメニューのメニュー番号。メニューは 0 から順に番号を付けられます。メニュー バーが棄却される（訳者注: dismiss、表示が消される？メモリが解放される？）とき、この値は保存されます。noMenuSelection の値は現在プル-ダウン メニューが無いことを示します。
• curItem
  • 現在ハイライトされているメニュ アイテムのアイテム番号。各メニューのアイテムは 0 から順に番号を付けられます。noMenuItemSelection の値は現在選択されているアイテムが無いことを示します。
• commandTick
  • ステータス メッセージが消されるべき時間をカウントする時計。
• numMenus
  • メニュー バー上のプル-ダウン メニューの数。
• menus
  • MenuPullDownType 構造体の配列。

互換性

3.5 New Feature Set が存在する場合、bitsBehindStatus と commandTick フィールドは定義されますが使用されません。その代わり、MenuCmdBarType 構造体の中の bitsBehindStatus と commandTick フィールドが背後にあるウィンドウの保存用ハンドルとコマンド ツールバーのためのタイムアウト値を定義します。

MenuItemType 構造体 ^TOP^

目的

MenuItemType 構造体はメニューの中のある特定のアイテムを定義します。MenuPullDownType 構造体の中の items 配列は、プル-ダウン メニューの中にある各メニュー アイテムに対して 1 つの MenuItemType 構造体を保持します。

3.5 New Feature Set が存在する場合、MenuAddItem() を使ってプログラム上でメニュー アイテムをプル-ダウン メニューに追加することができます。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuItemType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct {
	UInt16 id;
	Char command;
	UInt8 hidden: 1;
	UInt8 reserved: 7;
	Char *itemStr;
} MenuItemType;

フィールド

• id
  • メニュ アイテムの作成時に指定された ID 値。この ID 値はmenuEvent のイベント データの一部として含まれます。
• command
  • ショートカット キー。ショートカットを提供する場合、各ショートカットはその時点で使用可能なすべてのコマンド間で固有であることを確認してください。
• hidden
  • true の場合、メニュー アイテムは隠されます。false の場合、表示されます。MenuHideItem() と MenuShowItem() を使ってこの値をセット、クリアすることができます。
• reserved
  • 将来使用するために予約されています。
• itemStr
  • このメニュー アイテムに表示されるテキストへのポインタ。このテキストはショートカット キーを含みます。ショートカット キーを含めるには、文字列をアイテムのテキストから開始し、それからタブ文字、それからアイテムのショートカット キーと続けます。セパレータ バーを作成するには、MenuSeparatorChar 定数を保持する 1 文字の文字列を作成してください。

互換性

hidden と reserved フィールドは、3.5 New Feature Set が存在する場合にのみ、定義されます。

MenuPullDownPtr Typedef ^TOP^

MenuPullDownPtr 型は MenuPullDownType へのポインタを定義します。

Prototype

typedef MenuPullDownType *MenuPullDownPtr;

MenuPullDownType 構造体 ^TOP^

目的

MenuPullDownType 構造体はメニュー バーからアクセスされるある特定のメニューを定義します。MenuBarType 構造体の中のメニュー配列は、メニュー バーに関連付けられた各プル-ダウン メニューに対して 1 つの MenuPullDownType を保持します。

WARNING!

PalmSource 社（訳者注: 現 ACCESS 社）は MenuPullDownType 構造体の下位互換をサポートしていません。構造体メンバに直接アクセスしてはいけません。そのようなコードは将来のバージョンでは機能しないかもしれません。以下の情報はデバッグ目的でのみ使用してください。

Prototype

typedef struct {
	WinHandle menuWin;
	RectangleType bounds;
	WinHandle bitsBehind;
	RectangleType titleBounds;
	Char *title;
	UInt16 hidden : 1;
	UInt16 numItems : 15;
	MenuItemType *items;
} MenuPullDownType;

フィールド

• menuWin
  • メニューを保持するウィンドウのためのハンドル。
• bounds
  • プル-ダウン メニューの位置とサイズ（ピクセル単位）。
• bitsBehind
  • メニューによって隠される領域を保持するウィンドウのハンドル。
• title
  • メニュー バーの中に表示されるメニュー タイトル（null で終了する文字列）。
• titleBounds
  • メニュー バーの中のタイトルの位置とサイズ（ピクセル単位）。
• hidden
  • true の場合、メニューは隠されます。false の場合、表示されます。このフィールドは現在使用されません。
• numItems
  • メニューの中のアイテムの数。セパレータはアイテムとしてカウントされます。
• items
  • MenuItemType 構造体の配列。

互換性

hidden フィールドは、3.5 New Feature Set が存在する場合にのみ、定義されます。

メニュー定数 ^TOP^

定数	値	説明
noMenuSelection	-1	MenuBarType の curMenu フィールドは、現在選択されているメニューが無いとき、この値にセットされます。
noMenuItemSelection	-1	MenuBarType の curItem フィールドは、現在選択されているメニュー アイテムが無いとき、この値にセットされます。
separatorItemSelection	-2	MenuBarType の curItem フィールドは、メニュー セパレータ アイテムが選択されているとき、この値にセットされます。
MenuSeparatorChar	'-'	メニュー アイテムがメニュー アイテムをグループ分けするのに使用されるバーであることを示す特別な文字。MenuItemType の中の itemStr 文字列の最初の文字がこの値にセットされます。

メニュー リソース ^TOP^

メニュー バー（MBAR）とプル-ダウン メニュー（MENU）リソースはスクリーン上のメニュー オブジェクトを表すために一緒に使用されます。追加情報は、Palm OS User Interface Guidelines を参照してください。

メニュー関数 ^TOP^

MenuAddItem 関数 ^TOP^

目的

現在のアクティブなメニューにアイテムを追加します。

宣言されている場所

Menu.h

Prototype

Err MenuAddItem (
	UInt16 positionId,
	UInt16 id,
	Char cmd,
	const Char *textP
)

パラメータ

• → positionId
  • 存在しているメニュー アイテムの ID。新しいメニュー アイテムはこのメニュー アイテムの後に追加されます。
• → id
  • 新しいメニュー アイテムのために使われる ID。
• → cmd
  • ショートカット キー。ショートカットを提供する場合、各ショートカットはその時点ですべての使用可能なコマンド間で固有であることを確認してください。
• → textP
  • このメニュー アイテムに表示されるテキストへのポインタ。ショートカット キーを含みます。ショートカット キーを含めるには、アイテムのテキストから始めて、それからタブ文字を追加し、それからアイテムのショートカット キーを追加します。セパレータ バーを作成するには、MenuSeparatorChar 定数を保持する 1 文字の文字列を作成してください。

返り値

成功時には 0 を返します。エラーが起きた場合は以下に示すエラーの 1 つを返します。

• menuErrNoMenu
  • textP パラメータが NULL です。
• menuErrSameId
  • メニューはすでに ID id を持つアイテムを保持しています。
• menuErrNotFound
  • メニューは ID positionId を持つアイテムを保持していません。

現在のメニューが無い場合、致命的なエラー メッセージを表示するかもしれません。

コメント

この関数は新しい MenuItemType 構造体を作成し、それを MenuBarType のアイテム リストに追加します。

この関数を menuOpenEvent への応答の中でのみ呼び出すべきです。このイベントはメニューが最初にアクティブにされたときに生成されます。一般に、フォームのメニューは、vchrMenu または vchrCommand を持つ keyDownEvent が最初に生成されたときに、アクティブになり、そのメニューは、新しいフォーム（モーダル ファームまたはアラート パネルを含む）が表示されるか、フォームのメニューを変更するために FrmSetMenu() が呼び出されるまで、アクティブであり続けます。Palm OS user Interface guidelines は、メニューが最初にアクティブにされるとき以外はいつでも、メニュー アイテムを追加したり隠したりすることを妨げます。

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

MenuCmdBarAddButton 関数 ^TOP^

目的

コマンド ツールバー上に表示されるボタンを定義します。

宣言されている場所

Menu.h

Prototype

Err MenuCmdBarAddButton (
	UInt8 where,
	UInt16 bitmapId,
	MenuCmdBarResultType resultType,
	UInt32 result,
	Char *nameP
)

パラメータ

• → where
  • ボタンをコマンド ツールバー上にある他のボタンの左側に追加する場合 menuCmdBarOnLeft、他のボタンの右側またはボタンの正確な位置を示す数の位置に追加する場合は menuCmdBarOnRight でどちらかの値になります。ボタンの位置は右から左へ番号付けされ、右端の位置が番号 1 です。
• → bitmapId
  • ボタンの上に表示されるビットマップのリソース ID。ビットマップの大きさは高さ 13 ピクセル、幅 16 ピクセルであるべきです。
• → resultType
  • result パラメータの中に保持されるデータのタイプ。MenuCmdBarResultType を参照してください。
• → result
  • ユーザがこのボタンをタップしたときに送られるデータ。この値は、文字、メニュー アイテム ID、通知定数になることができます。
• → nameP
  • ユーザがボタンをタップした場合にステータス メッセージの中に表示されるテキストへのポインタ。NULL の場合、result の中で保持されている ID またはショートカット文字に一致するメニュー アイテムがあれば、そこからテキストを取り出します。このパラメータにテキスト バッファを提供した場合、MenuCmdBarAddButton はバッファのコピーを作成します。

返り値

成功時には 0 を返します。エラーが起きた場合、以下に示すエラー コードの 1 つを返します。

• menuErrOutOfMomery
  • 操作を行うのに必要な空き容量が足りません。
• menuErrTooManyItems
  • コマンド ツールバーはすでに許される最大数のボタンを持っています。（現在のところ最大数は 8）

コメント

menuCmdBarOpenEvent または通知 sysNotifyMenuCmdBarOpenEvent への応答の中でこの関数を呼び出します。これらは両方ともユーザがコマンド キー入力を行い、コマンド ツールバーがオープンされようとしていることを知らせるものです。応答として、ボタンをツールバーに追加し、false を返すべきです。それによりイベントを完全にはハンドルしていないことを示します。

sysNotifyMenuCmdBarOpenEvent 通知は、共有ライブラリ、システム拡張、イベント ループを使用しない他のコード リソースによってのみ使用されることを意図しています。アプリケーションを作成する場合、常に通知の代わりにイベントに応答するようにしてください; アプリケーションは、そのアプリケーションが現在のアプリケーションである場合にのみ、ツールバーにボタンを追加すべきです。通知に応答する場合（通知イベントをハンドルする場合）、アプリケーションがアクティブかどうかにかかわらず、コマンド ツールバーが表示されるたびに通知を受け取ります。

コマンド ツールバーはオープンされるたびに割り当てを受け、スクリーンから消されるたびに割り当てを解除されるということに注意してください。

コマンド ツールバー上にボタンを表示するスペースには限りがあります。ボタンの数を 4 つまたは 5 つに制限すべきです。システムによって許される最大数は 8 ですが、ユーザが動作を選択した後に表示されるステータス メッセージのためにスペースを残しておくべきです。ボタンは状況にあったものであるべきです; 例えば、フィールド コードはクリップボードにテキストがある場合にのみ貼付ボタンを表示すべきです。ボタンのためのビットマップは 16 X 13 ピクセルであるべきです。

コマンド ツールバーがオープンされるときにフィールドがフォーカスされている場合、フィールド マネージャは切取、コピー、貼付、取消のためのボタンを追加します。アプリケーションがこのデフォルトの振る舞いを望まない場合、menuCmdBarOpenEvent 構造体の中の preventFieldButtons を true にセットしてください。（通知ハンドラ内からのフィールド ボタンを表示させない方法は無いということに注意してください。）

以下に示すコマンド ツールバーのためのビットマップは UIResources.h の中で定義されています。システムとビルド-イン アプリケーションはこれらのビットマップを、表の中でリストされているコマンドを表すために、使用します。作成するアプリケーションが同じ動作を行う場合も、これらを使うべきです。これらのボタンのいずれかを使用する場合、これらのボタンを右から左へと表示される順に追加します。（例えば、BarDeleteBitmap を使用する場合、それは常に右端のボタンであるべきです。）

ビットマップ	コマンド
BarDeleteBitmap	レコードを削除する。
BarPasteBitmap	クリップボードの内容を挿入ポイントに貼り付ける。
BarCopyBitmap	選択されているものをコピーする。
BarCutBitmap	選択されているものを切り取る。
BarUndoBitmap	前の動作を取り消す。
BarSecureBitmap	セキュリティ ダイアログを表示する。
BarBeamBitmap	現在のレコードを無線通信で送る。
BarInfoBitmap	情報ダイアログを表示する。（起動する。（訳者注: ？　原文 Launcher））

ボタンを左側に追加するのが最善です。右側にボタンを追加する場合、この関数は存在するすべてのボタンを 1 つ分左に移動させます。また、where パラメータで特定の位置を指定することもできます。位置は右から左へと順に、右端が 1 になるように番号を付けられています。特定の位置を指定する場合、この関数は他のボタンのためのスペースを残します。例えば、位置 3 を指定し、位置 1 と 2 に表示されているボタンが無い場合、追加されたボタンの右側に空白ができます。

result と resultType パラメータは、ユーザがボタンをタップして場合に、結果がどうなるべきなのかを指定します。result は実際のデータを保持し、resultType は result の中のデータのタイプを指定する定数を保持します。通常、結果は menuEvent の中に送られます。このケースでは、resultType は menuCmdBarResultMenuItem で、result はイベントの中に含まれるべきであるメニュー アイテムの ID です。

メニュー ID の代わりにショートカット文字を指定することもあるかもしれませんが、それは効率が悪いです。result がショートカット文字である場合、MenuHandleEvent() 関数は result の中の文字を持つ keyDownEvent をイベント キューに追加します。イベント ループの次のサイクルで、MenuHandleEvent は keyDownEvent への応答として menuEvent をイベント キューに追加します。つまり、ボタンが直接 menuEvent をイベント キューに追加するほうが良いのです。

あなたがアプリケーションの外側で MenuCmdBarAddButton を呼び出した場合、あなたはアクティブなメニューの中にあるメニュー アイテムのいずれのことも知らないかもしれません（あなたのコードが MenuAddItem() を使って追加したアイテムでない限り）。このケースでは、ブロードキャストされる通知を指定します。通知は次のイベント ループの先頭にブロードキャストされ、カスタム データを保持していてはいけません。（アプリケーションは通知の結果タイプをも使用するかもしれません。）

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

MenuCmdBarDisplay(), MenuCmdBarGetButtonData()

MenuCmdBarDisplay 関数 ^TOP^

目的

コマンド ツールバーを表示します。

宣言されている場所

Menu.h

Prototype

void MenuCmdBarDisplay (
	void
)

パラメータ

ありません。

返り値

返り値はありません。

コメント

この関数は、ユーザがコマンド キー入力を行ったとき、コマンド ツールバーを表示します。通常、この関数を作成するコードで呼び出すことはありません。フォーム マネージャが、menuCmdBarOpenEvent のハンドルするとき最後にこの関数を呼び出します。

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

MenuCmdBarAddButton(), MenuCmdBarGetButtonData()

MenuCmdBarGetButtonData 関数 ^TOP^

目的

与えられたコマンド ボタンのためのデータを取得します。

宣言されている場所

Menu.h

Prototype

Boolean MenuCmdBarGetButtonData(
	Int16 buttonIndex,
	UInt16 *bitmapIdP,
	MenuCmdBarResultType *resultTypeP,
	UInt32 *resultP,
	Char *nameP
)

パラメータ

• → buttonIndex
  • あなたが情報を取得したいボタンのインデックス。ボタンは右から左に並んでいて、右端のボタンがインデックス 0 です。
• ← bitmapIdP
  • ボタン上に表示されるビットマップのリソース ID。この値を取得したくない場合は、NULL を渡します。
• ← resultTypeP
  • このボタンがとるアクションのタイプ。この値を取得したくない場合は、NULL を渡します。
• ← resultP
  • ボタンをタップした結果。この値を取得したくない場合は、NULL を渡します。
• ← nameP
  • このボタンがタップされたときにステータス メッセージの中に表示されるテキスト。この値を取得したくない場合は、NULL を渡します。NULL でない場合、nameP はサイズ menuCmdBarMaxTextLength の文字列を指さなくてはなりません。

結果

情報が成功裏に取得された場合、true を返します。コマンド ツールバーが無い場合、または、buttonIndex のボタンが無い場合、false を返します。

コメント

この関数を使ってコマンド ツールバー上に表示されるボタンについての情報を取得することができます。コマンド ツールバーがまだ初期化されていない場合、この関数は false を返します。

コマンド ツールバーは、ユーザがコマンド キー入力をしたときに割り当てられ、MenuEraseStatus() が呼び出されたときに割り当てを解除されることに注意してください。それゆえ、MenuCmdBarGetButtonData を呼び出す論理的な場所は、menuCmdBarOpenEvent または sysNotifyMenuCmdBarOpenEvent 通知に応答するときだけです。

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

MenuCmdBarDisplay(), MenuCmdBarAddButton()

MenuDispose 関数 ^TOP^

メニューとコマンド ステータスに割り当てられたいたすべてのメモリを解放し、保存されていたビットをスクリーンに戻します。

宣言されている場所

Menu.h

Prototype

void MenuDispose (
	MenuBarType *menuP
)

パラメータ

• → menuP
  • 処分するメニュー オブジェクトへのポインタ。（MenuBarType を参照してください。）NULL の場合、この関数はただちに返ります。

返り値

返り値はありません。

コメント

たいていのアプリケーションはこの関数を直接呼び出す必要はありません。MenuDispose は、メニューを保持しているフォームがもはやアクティブなフォームでなくなったとき、メニューを保持しているフォームが解放されたとき、それに FrmSetMenu がフォームのメニュー バーを変更するために呼び出されたときに、システムによって呼び出されます。

参照

MenuInit(), MenuDrawMenu()

MenuDrawMenu 関数 ^TOP^

目的

現在のメニュー バーと最後に可視だったプル-ダウンをを描きます。

宣言されている場所

Menu.h

Prototype

void MenuDrawMenu (
	MenuBarType *menuP
)

パラメータ

• → menuP
  • MenuBarType へのポインタ。NULL であってはいけません。

返り値

返り値はありません。

コメント

たいていのアプリケーションはこの関数を直接呼び出す必要はありません。MenuHandleEvent() は、ユーザがメニュー シルク-スクリーン ボタンをタップしたとき（または Palm OS 3.5 以降ではフォームのタイトルをタップしたとき）、MenuDrawMenu を呼び出します。

メニュー バーとプル-ダウン メニューは、すべてのアプリケーション ウィンドウよりも前面に描かれます。挿入ポイントの状態、メニュー バーとプル-ダウン メニューによって覆い隠されるビット、現在アクティブなウィンドウはメニューが描かれる前に保存されます。これらは、メニューが消されるとき、すべて元に戻されます。

メニューは、メニューがアクティブである限り、最後に表示されたプル-ダウン メニューを追跡し続けます。メニューは以下の条件でそのアクティブ状態を失います:

• フォーム上のアクティブなメニューを変更するために FrmSetMenu が呼び出されたとき。
• 新しいフォーム - モーダル フォーム、アラート パネルであっても - がアクティブになったとき。

ユーザがあなたのアプリケーションの Options メニューから About アイテムを選択し、それからメイン フォームに戻るために OK ボタンをクリックすると仮定します。About ダイアログが表示されるとき、それはアクティブなフォームになり、結果としてメイン フォームのメニュー状態は消去されます。このメニュー状態は、メイン フォームが再びアクティブになったとき、元に戻されません。次に MenuDrawMenu が呼び出されるとき（つまり、次にユーザがメニュー シルク-スクリーン ボタンをタップするとき）、メニュー バーは以前のように表示され、Options プル-ダウン メニューの代わりにメニュー バーの中でリストされている最初のプル-ダウン メニューが表示されます。

参照

MenuInit(), MenuDispose()

MenuEarseStatus 関数 ^TOP^

目的

メニュー コマンド ステータスを消去します。

宣言されている場所

Menu.h

Prototype

void MenuEraseStatus (
	MenuBarType *menuP
)

パラメータ

• → menuP
  • MenuBarType へのポインタ。現在のメニューの場合は NULL。

返り値

返り値はありません。

コメント

ユーザがコマンドキー入力を使ってメニュー コマンドを選択したとき、コマンド ツールバーまたはステータス メッセージがスクリーン最下部に表示されます。MenuEraseStatus はツールバー またはステータス メッセージを消去します。

たいていの状況では、あなたはこの関数を明示的に呼び出す必要はありません - ただ、現在のメニュー コマンド ステータスにそれ自身を自動的に削除させるだけです。さもなければ、あなたはユーザがそれを見るよりも早くテキストを消去するかもしれません。

あなたは、コマンド ツールバーがユーザが選択したメニュー コマンドによって変更されるものをカバーする場合にのみ、MenuEraseStatus を明示的に呼び出します。例えば、ユーザが新しいフォームを表示させるコマンドを選択した場合、コマンドを実行する前に MenuEraseStatus を呼び出します。またｈ、コマンドが何かを ウィンドウの下部に描く場合、描画関数を実行する前に MenuEraseStatus を呼び出します。

互換性

メニュー ショートカット文字が入力されたときの正確な動作は、実行されているオペレーティング システムのバージョン次第です。リリース 3.5 よりも前のバージョンでは、システムは、ユーザが Graffiti または Graffiti 2 コマンド入力をしたとき、スクリーンの左下に文字列 "Command:" を表示します。Palm OS 3.5 以降では、コマンド入力はコマンド ツールバーを表示します。このツールバーはスクリーンと同じ幅を持ち、ユーザがその他のキー入力をする代わりにタップすることができるボタンを表示します。ユーザがボタンをタップするか、アクティブ メニュー上に表示されているショートカット文字と一致する文字を入力したとき、コマンドが実行されている間ステータス メッセージがツールバーの中に表示されます。Palm OS 3.5 以降で MenuEraseStatus を呼び出すと、コマンド ツールバー データ構造体の割り当てを解除するのと同時にスクリーンからコマンド ツールバーを消去します。

コマンド ツールバーは Palm OS 3.5 以降ではステータス メッセージの表示以上のことをするため、あなたはそれより前のバージョンの Palm OS よりも頻繁に MenuEraseStatus を呼び出す必要があるかもしれません。

参照

MenuInit()

MenuGetActiveMenu ^TOP^

目的

現在アクティブなメニューへのポインタを返します。

宣言されている場所

Menu.h

Prototype

MenuBarType *MenuGetActiveMenu (
	void
)

パラメータ

ありません。

返り値

現在アクティブなメニューへのポインタを返します。ポインタが無い場合は、NULL を返します。

コメント

アクティブなメニューは必ずしもスクリーン上で可視であるわけではありません。例えば、コマンド ショートカットが入力された場合、メニューはアクティブであるけれども可視ではないかもしれません。一般に、フォームのメニューはまず最初に keyDownEvent が vchrMenu または vchrCommand と共に生成されたときにアクティブになり、新しいフォーム（モーダル フォームまたはアラート パネルを含む）が表示されるか、FrmSetMenu() が呼び出されてフォームのメニューが変更されるまで、アクティブのままでいます。

ウィンドウへのカスタム描画を行うアプリケーションはしばしば、メニューの上に描画していないことを保証するためにメニューが可視であるかどうかをチェックします。どのようにメニューの可視性を検証するかについての説明は、Palm OS Programmer's Companion, vol. I の 「メニューの可視性チェック」 を参照してください。

参照

MenuHandleEvent(), MenuSetActiveMenu()

MenuHandleEvent 関数 ^TOP^

目的

現在のメニューの中のイベントを処理します。このルーチンは 2 タイプのイベント - penDownEvent と keyDownEvent を処理します。

宣言されている場所

Menu.h

Prototype

Boolean MenuHandleEvent (
	MenuBarType *menuP,
	EventType *event,
	UInt16 *error
)

パラメータ

• → menuP
  • MenuBarType データ 構造体へのポインタ。
• → event
  • EventType 構造体へのポインタ。
• → error
  • エラー（エラー無しの場合は 0）。現在のところ、この関数は常に11error に 0 をセットします。

返り値

イベントが処理された場合、true を返します。つまり、イベントがメニュー バーまたはメニュー内部での penDownEvent であるか、メニューがサポートする keyDownEvent である場合です。それ以外のイベントでは false を返します。

コメント

penDownEvent がメニュー バーの中で受信された場合、MenuHandleEvent はペンをペンが持ち上がるまで追跡します。ペンがメニュー バーの領域内で持ち上がった場合、選択されたタイトルは反転し、適切なプル-ダウン メニューが表示されます。それ以前のプル-ダウン メニューは消去されます。ペンがメニュー バーとプル-ダウン メニューの外側で持ち上がった場合、メニューは消去されます。

penDownEvent がプル-ダウン メニューの中で受信された場合、MenuHandleEvent はペンをペンが持ち上がるまで追跡します。ペンがメニューの領域内で持ち上がった場合、選択されたメニュー アイテムのリソース ID を保持している menuEvent がイベント キューに追加されます。ペンがメニューとメニュー バーの外側で持ち上がった場合、メニューはしょうきょされます。

vchrMenu を持つ keyDownEvent が受信された場合、メニューはメニューが可視でないなら描かれ、メニューが可視なら消去されます。

vchrCommand を持つ keyDownEvent が樹脂インされた場合、コマンド ショートカットが実行されます。コマンド ショートカットは、実行されている Palm OS のバージョンによってことなる扱われ方をします。3.5 よりも前のバージョンでは、次の keyDownEvent が有効なメニュー ショートであるかどうかを調べるためにチェックされます。有効なショートカットであるなら、menuEvent がイベント キューに追加されます。

Palm OS 3.5 以降で vchrCommand を持つ keyDownEvent が受信された場合、MenuHandleEvent はツールバーがまだオープンされていないなら menuCmdBarOpenEvent をキューに追加します。menuCmdBarOpenEvent はアプリケーションにそれ自身のボタンをコマンド ツールバーに追加する機会を与えます。次のイベントはショートカットとなる文字を持つ keyDownEvent であるか、ツールバー上のボタンの 1 つでの penDownEvent であるかもしれません。keyDownEvent は以前のリリースと同じように処理されます - それが有効なメニュー ショートカットであるなら、menuEvent がイベント キューに追加されます。次のイベントが penDownEvent の場合、ペンは持ち上がるまで追跡されます。ペンがボタンの領域内で持ち上がった場合、適切なアクションがとられます。更なる情報は、MenuCmdBarAddButton() の説明を参照してください。

Palm OS バージョン 3.5 以降では、vchrMenu または vchrCommand のどちらかのイベントが最初にメニューをアクティブ化と初期化した場合、そのメニューが初期化された理由（vchrMenu に対する menuButtonCause または vchrCommand に対する menuCommandCause）を保持している menuOpenEvent がイベント キューに追加され、それから現在のイベントがその後に追加されます。

MenuHideItem 関数 ^TOP^

目的

指定されたメニュー アイテムを隠します。

宣言されている場所

Menu.h

Prototype

Boolean MenuHideItem (
	UInt16 id
)

パラメータ

• → id
  • 隠すメニュー アイテムの ID。

返り値

指定されたアイテムの hidden 属性のセットに成功した場合、true を返します。そうでない場合、false を返します。

コメント

menuOpenEvent への応答としてのみ、この関数を呼び出すべきです。このイベントは、メニューが最初にアクティブ化されるときに、生成されます。一般に、フォームのメニューは、vchrMenu または vchrCommand を持つ keyDownEvent が初めて生成されるときにアクティブ化され、新しいフォーム（モーダル フォームやアラート パネルを含む）が表示されるかフォームのメニューを変更するために が呼び出されるまでアクティブのままでいます。Palm OS ユーザ インターフェイス ガイドラインは、メニューが初めてアクティブ化されるとき以外で、メニュー アイテムを追加または隠すことをしないように勧めています。

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

MenuShowItem()

MenuInit 関数 ^TOP^

目的

リソース ファイルからメニュー リソースを読み込みます。

宣言されている場所

Menu.h

Prototype

MenuBarType *MenuInit (
	UInt16 resourceId
)

パラメータ

• → resourceId
  • メニュー リソースを指定する ID。

返り値

メニュー リソースを保持するために割り当てられたメモリ ブロックへのポインタ（MenuBarType へのポインタ）を返します。

コメント

メニューは、MenuSetActivate() が呼び出されるまで、使用不可です。

通常、この関数を直接呼び出す必要はありません。フォームはそのフォームに関連付けられているメニューのリソース ID を保存して、必要があればそのメニューを初期化します。あなたがそのフォームのメニューを変更することを望む場合、FrmSetMenu() を呼び出します。FrmSetMenu() は、フォームの現在のメニューの処分、新しいメニューのフォームへの関連付け、必要があれば初期化を行います。

参照

MenuSetActiveMenu(), MenuDispose()

MenuSetActiveMenu 関数 ^TOP^

目的

現在のメニューをセットします。

宣言されている場所

Menu.h

Prototype

MenuBarType *MenuSetActiveMenu(
	MenuBarType *menuP
)

パラメータ

• → menuP

返り値

新しいメニューがセットされる前にアクティブだったメニューへのポインタを返します。アクティブだったメニューが無い場合は NULL を返します。

コメント

この関数はアクティブ メニューをセットしますが、それをフォームに関連付けることはしません。MenuSetActiveMenu の代わりに FrmSetMenu() を呼び出すことを推奨します。FrmSetMenu はアクティブ メニューをセットし、古いメニューを解放し、新しいアクティブ メニューをフォームに関連付けします。これは、フォームが解放されるときにそのメニューも解放されることを意味します。

参照

MenuGetActiveMenu()

MenuSetActiveMenuRscID 関数 ^TOP^

目的

現在のメニューをリソース ID でセットします。

宣言されている場所

Menu.h

Prototype

void MenuSetActiveMenuRscID (
	UInt16 resourceId
)

パラメータ

• → resourceId
  • アクティブ化するメニューのリソース ID。

返り値

返り値はありません。

コメント

この関数は、あなたがメニュー構造体へのポインタの代わりにメニューのリソース ID を渡す点を除いて、MenuSetActiveMenu() と同じです。この関数は最適化として使用されます; MenuSetActiveMenu では、あなたはメニューをアクティブ化する前にそのメニューを初期化しなければなりません。可能性として、アプリケーションはメニューが必要とされる前に終了するかもしれません。この場合、メニューへのメモリ割り当ては不要です。MenuSetActiveMenuRscID は単にリソース ID を保存するだけです。メニューが必要になったときに、メニューはこのリソースから初期化されます。

MenuSetActiveMenu で説明したのと同じ理由で、この関数を呼び出す代わりに FrmSetMenu() を呼び出すことを推奨します。

互換性

2.0 New Feature Set が存在する場合にのみ、実装されます。

MenuShowItem 関数 ^TOP^

目的

指定されたメニュー アイテムを可視にします。

宣言されている場所

Menu.h

Prototype

Boolean MenuShowItem (
	UInt16 id
)

パラメータ

• → id
  • 表示するメニュー アイテムの ID。

返り値

hidden 属性を不能にすることに成功した場合、true を返します。そうでない場合、false を返します。

コメント

menuOpenEvent への応答としてのみ、この関数を呼び出すべきです。このイベントは、メニューが最初にアクティブ化されるときに、生成されます。一般に、フォームのメニューは、vchrMenu または vchrCommand を持つ keyDownEvent が初めて生成されるときにアクティブ化され、新しいフォーム（モーダル フォームやアラート パネルを含む）が表示されるかフォームのメニューを変更するために が呼び出されるまでアクティブのままでいます。Palm OS ユーザ インターフェイス ガイドラインは、メニューが初めてアクティブ化されるとき以外で、メニュー アイテムを追加または隠すことをしないように勧めています。

互換性

3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

MenuHideItem()

←　14 章に戻る　↑トップへ　16 章に進む　→