Palm OS Programmer's API Reference/7

←　6 章に戻る　↑トップへ　8 章に進む　→

7 コントロール

• コントロール データ構造体
  • ButtonFrameType
  • ControlAttrType
  • ControlPtr
  • ControlStyleType
  • ControlType
  • GraphicControlType
  • SliderControlType
• コントロール リソース
• コントロール関数
  • CtlDrawControl
  • CtlEnabled
  • CtlEraseControl
  • CtlGetLabel
  • CtlGetSliderValues
  • CtlGetValue
  • CtlHandleEvent
  • CtlHideControl
  • CtlHitControl
  • CtlNewControl
  • CtlNewGraphicControl
  • CtlNewSliderControl
  • CtlSetEnabled
  • CtlSetGraphics
  • CtlSetLabel
  • CtlSetSliderValues
  • CtlSetUsable
  • CtlSetValue
  • CtlShowControl
  • CtlValidatePointer

この章ではヘッダ ファイル Control.h で定義されているコントロール オブジェクト API について説明します。以下のことを説明します。

• コントロール データ構造体
• コントロール リソース
• コントロール関数

コントロールについての追加情報は Palm OS Programmer's Companion, vol. I の 「コントロール」 を参照してください。（訳者注: 原文では 「フォーム、ウィンドウ、ダイアログ」 の 「オフスクリーン ウィンドウ」 となっていたが誤りと思われる。）

コントロール データ構造体 ^TOP^

ButtonFrameType 列挙体 ^TOP^

目的

ButtonFrameType 列挙体（訳者注: 原文では enum）はボタンの縁のスタイルを指定します。これは ControlAttrType の frame フィールドのための値を定義します。

Prototype

enum buttonFrames {noButtonFrame, 
   standardButtonFrame, boldButtonFrame, 
   rectangleButtonFrame};

typedef enum buttonFrames ButtonFrameType;

定数

• noButtonFrame
  • 縁を持たないボタン
• standardButtonFrame
  • 四隅が丸くなった四角い縁を持つ標準ボタン
• boldButtonFrame
  • 四隅が丸くなった強調された四角い縁を持つボタン
• rectangleButtonFrame
  • 四隅が角張った四角い縁を持つボタン

ControlAttrType 構造体 ^TOP^

目的

ControlAttrType ビット フィールドはコントロールの視覚特性を指定します。以下のように定義されています。

Prototype

typedef struct {
	UInt8 usable:1;
	UInt8 enabled:1;
	UInt8 visible:1;
	UInt8 on:1;
	UInt8 leftAnchor:1;
	UInt8 frame:3;
	UInt8 drawnAsSelected:1;
	UInt8 graphical:1;
	UInt8 vertical:1;
} ControlAttrType;

WARNING!

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

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

フィールド

• usable
  • 0 の場合、コントロールは現在のアプリケーションのインターフェイスの一部とは見なされず、スクリーン上に表示されません。この値をセットまたはクリアするために、CtlSetUsable(), CtlShowControl() または CtlHideControl() を使用できます。
• enable
  • 0 の場合、コントロールは可視ですが、ペンに反応しません。この値は CtlSetEnabled() によってセットされ、CtlEnabled() によって返されます。
• visible
  • コントロールが描かれる（CtlDrawControl()）、消される（CtlEraseControl()）ときに、内部的にセット、クリアされます。
• on
  • セットされている場合、コントロールは値「on」を持ちます。例えば、「on」の値を持つチェック ボックスは、ボックス内にチェック マークが表示されています。この値を取得、セットするために、CtlGetValue() と CtlSetValue() を使用してください。
• leftAnchor
  • ラベルが変更されたときに幅を拡張、縮めるコントロールによって使用されます。この属性がセットされている場合、コントロールの左端は固定されています。
• frame
  • ボタン コントロールのまわりに描かれるフレームのタイプ。取り得る値については ButtonFrameType を参照してください。ボタン コントロールだけがこの属性を使用します。他のすべてのコントロールでは、ControlStyleType がフレームを決定します。
• drawAsSelected
  • Palm OS 3.5で、テキストを保持しないボタン（ビットマップの上端に表示されるボタン）のために使用されます。セットされている場合、ボタンは反転して表示されます。クリアされている場合、ボタンは通常通りに表示されます。
• graphical
  • セットされている場合、コントロールはグラフィカル コントロール、スライダ、または、フィードバック スライダです。
• vertical
  • 現在使用されていません。

互換性

drawAsSelected, grahpical それに vertical 属性は、3.5 New Feature Set が存在する場合にのみ、存在します。

ControlPtr Typedef ^TOP^

目的

ControlPtr は ControlType 構造体へのポインタです。

Prototype

typedef ControlType *ControlPtr;

ControlStyle 列挙体 ^TOP^

目的

ControlStyleType 列挙体（原文: enum）は、ControlType 中のコントロールのタイプ（ボタン、プッシュ ボタンなど）を指定する style フィールドのための値を指定します。

enum controlStyles {buttonCtl, pushButtonCtl,
   checkboxCtl, popupTriggerCtl,
   selectorTriggerCtl, repeatingButtonCtl,
   sliderCtl, feedbackSliderCtl};

typedef enum controlStyles ControlStyleType;

定数

• buttonCtl
  • ボタン。ボタンはボックスの中にテキスト ラベルを表示します。ButtonFrameType はボックスのタイプを指定します。
• pushButtonCtl
  • プッシュ ボタン。プッシュ ボタンを選択すると、ボタンの表示は反転され、それにより、ハイライトされます。
• checkboxCtl
  • チェック ボックス。チェック ボックスは「on」（チェックされている）または「off」（チェックされていない）のどちらにセットされているかを表示します。
• popupTriggerCtl
  • ポップアップ トリガ。ポップアップ トリガはテキスト ラベルが後に続くグラフィック要素を表示します。ポップアップ リストを表示するために使用されます。
• selectorTriggerCtl
  • セレクタ トリガ。セレクタ トリガは灰色の四角いフレームに囲まれたテキスト ラベルを表示します。このコントロールは新しいラベルの幅に合わせて広がったり、縮まったりします。
• repeatingButtonCtl
  • リピート ボタン。リピート ボタンはボタンに似ています。しかし、リピート ボタンは、ユーザがそのボタンの上にペンを置いている間だけ、継続して選択されています。
• sliderCtl
  • スライダ。スライダは 2 つのビットマップを表示します: 1 つは現在値（thumb）を表し、もう 1 つは取り得る値の範囲を表します。ユーザは、値を変更するために、thumb を左または右にスライドさせることができます。
• feedbackSliderCtl
  • フィードバック スライダ。フィードバック スライダはスライダに似ています。しかし、フィードバック スライダは、ペンが接触している間、thumb が動くたびにイベントを発します。通常のスライダは、ペンが離れたときにのみ、イベントを発します。

互換性

sliderCtl と feedbackSliderCtl 値は、3.5 New Feature Set が存在する場合にのみ、定義されます。

ControlType 構造体 ^TOP^

目的

ControlType 構造体はコントロールのタイプと特性を定義します。この構造体は以下のように定義されています。

Prototype

typedef struct {
	UInt16 id;
	RectangleType bounds;
	Char *text;
	ControlAttrType attr;
	ControlStyleType style;
	FontID font;
	UInt8 group;
	UInt8 reserved;
} ControlType;

WARNING!

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

コードは ControlType 構造体を実体の無いものとして扱うべきです。構造体の中のフィールドは、コントロール リソース作成時に指定された値によってセットされ、通常では変わることはありません。以下の説明で指定される関数を、各値を取得、セットするために使用してください。構造体メンバを直接変更しようとしないでください。

フィールド

• id
  • コントロール リソース作成時に指定される ID 値
• bounds
  • コントロールの、ウィンドウとの相対座標としての、領域。コントロールのテキスト ラベルはコントロールの領域に貼り付けられます。コントロールのフレームはコントロール領域のまわり（外側）に描かれます。FrmGetObjectBounds() と FrmSetObjectBounds() がこの値を取得、セットします。
• text
  • コントロール ラベルへのポインタ。text が NULL の場合、コントロールはラベルを持ちません。この値を取得、セットするために、CtlGetLabel() と CtlSetLabe() を使用してください。
• attr
  • コントロール属性。ControlAttrType を参照してください。
• style
  • コントロールのスタイル。ControlStyleType を参照してください。
• font
  • コントロールのラベルを描くのに使用されるフォント
• group
  • 排他的グループの一部であるプッシュ ボタンまたはチェック ボックスのグループ ID。コントロール ルーチンは、他のコントロールが選択されたとき、選択されていたコントロールの選択を自動的に取り消しません。それは、それらのコントロールを管理するアプリケーションまたはダイアログ ボックスのようなより高いレベルのオブジェクト次第です。
• reserved
  • 将来使用するために予約されています。

GraphicControlType 構造体 ^TOP^

目的

GraphicControlType 構造体はグラフィカル コントロールを定義します。グラフィカル コントロールは他のコントロールと似ていますが、テキスト ラベルが置かれる場所にビットマップを表示するところが異なります。

Prototype

typedef struct GraphicControlType {
	UInt16 id;
	RectangleType bounds;
	DmResID bitmapID;
	DmResID selectedBitmapID;
	ControlAttrType attr;
	ControlStyleType style;
	FontID unused;
	UInt8 group;
	UInt8 reserved;
} GraphicControlType;

WARNING!

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

コードは GraphicControlType 構造体を実体の無いものとして扱うべきです。構造体の中のフィールドは、コントロール リソース作成時に指定された値によってセットされ、通常では変わることはありません。以下の説明で指定される関数を、各値を取得、セットするために使用してください。構造体メンバを直接変更しようとしないでください。

フィールド

• id
  • コントロール リソース作成時に指定される ID 値
• bounds
  • コントロールの、ウィンドウとの相対座標としての、コントロールのフレームはコントロール領域のまわり（外側）に描かれます。FrmGetObjectBounds() と FrmSetObjectBounds() がこの値を取得、セットします。
• bitmapID
  • ボタンの中に表示されるビットマップのリソース ID。この値を変更するために CtlSetGraphics() を使用することができます。
• selectedBitmapID
  • 選択されたときにボタンが異なるビットマップを表示する場合、このフィールドはそのビットマップのリソース ID を保持します。通常、このフィールドはプッシュ ボタンまたはリピート ボタンのために使用されます。この値を変更するために CtlSetGraphics() を使用することができます。
• attr
  • コントロール属性。ControlAttrType を参照してください。グラフィカル コントロールでは、graphical 属性がセットされていなくてはなりません。ControlAttrType セクションで説明した API を使ってここのビットフィールドにアクセスすることができます。ControlAttrType API は引数として ControlType* を取るため、API を呼び出すとき、GraphicControlType* を ControlType* にキャストすべきです。
• style
  • コントロールのスタイル。ControlStyleType を参照してください。グラフィカル コントロールは checkboxCtl 以外のどのコントロール タイプにもなり得ます。
• unused
  • 使用されません。
• group
  • 排他的グループの一部であるプッシュ ボタンのグループ ID。コントロール ルーチンは、他のコントロールが選択されたとき、選択されていたコントロールの選択を自動的に取り消しません。それは、それらのコントロールを管理するアプリケーションまたはダイアログ ボックスのようなより高いレベルのオブジェクト次第です。
• reserved
  • 将来使用するために予約されています。

互換性

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

SliderControlType 構造体 ^TOP^

目的

SliderControlType 構造体はスライダ コントロールまたはフィードバック スライダ コントロールを定義します。

Prototype

typedef struct SliderControlType {
	UInt16 id;
	RectangleType bounds;
	DmResID thumbID;
	DmResID backgroundID;
	ControlAttrType attr;
	ControlStyleType style;
	UInt8 reserved;
	Int16 minValue;
	Int16 maxValue;
	Int16 pageSize;
	Int16 value;
	MemPtr activeSliderP;
} SliderControlType;

WARNING!

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

コードは SliderControlType 構造体を実体の無いものとして扱うべきです。構造体の中のフィールドは、コントロール リソース作成時に指定された値によってセットされ、通常では変わることはありません。CtlSetSliderValues() を使って新しい最小値、最大値、ページ サイズ、それに現在値をセットでき、CtlGetSliderValues() を使ってこれらの値を取得できます。構造体メンバを直接変更しようとしないでください。

フィールド

• id
  • コントロール リソース作成時に指定される ID 値
• bounds
  • コントロールの、ウィンドウとの相対座標としての、領域。FrmGetObjectBounds() と FrmSetObjectBounds() がこの値を取得、セットします。
• thumbID
  • スライダ ノブ（「thumb」と呼ばれます）に使用されるビットマップのリソース ID。NULL の場合、デフォルトのビットマップが使用されます。
• backgroundID
  • スライダの背景に使用されるビットマップのリソース ID。NULL の場合、デフォルトのビットマップが使用されます。
• attr
  • コントロール属性。ControlAttrType を参照してください。スライダ コントロールでは、graphical 属性がセットされていなくてはなりません。ControlAttrType セクションで説明した API を使ってここのビットフィールドにアクセスすることができます。ControlAttrType API は引数として ControlType* を取るため、API を呼び出すとき、GraphicControlType* を ControlType* にキャストすべきです。
• style
  • コントロールのスタイル。ControlStyleType を参照してください。sliderCtl または feedbackSliderCtl でなくてはなりません。
• reserved
  • 将来使用するために予約されています。
• minValue
  • thumb が一番左端にあるときのスライダの値
• maxValue
  • thumb が一番右端にあるときのスライダの値
• pageSize
  • ユーザが thumb の右または左をタップしたときにスライダ値を増加または減少させる量
• value
  • スライダによって表される現在値。CtlGetValue() と CtlSetValue() を使ってこの値を取得、セットします。
• activeSliderP
  • スライダがアクティブなときに使用されるメモリへのポインタ。スライダは、描かれている間、または、ペンを追跡している間、アクティブになります。スライダがアクティブでない場合、このポインタは NULL です。

互換性

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

コントロール リソース ^TOP^

異なるリソースは、以下のように、異なるコントロールに関連付けられています。

• ボタン -- ボタン リソース（tBTN）
• ポップアップ トリガ -- ポップアップ トリガ リソース（tPUT）
• セレクタ トリガ -- セレクタ トリガ リソース（tSLT）
• リピート ボタン（訳者注: 原文では Repeat control となっていたが誤りと思われる） -- リピート ボタン リソース（tREP）
• プッシュ ボタン -- プッシュ ボタン リソース（tPBN）
• チェック ボックス -- チェック ボックス リソース（tCBX）
• スライダ -- スライダ リソース リソース（tsld）
• フィードバック スライダ -- フィードバック スライダ リソース（tslf）

追加情報については、Palm OS User Interface Guidelines を参照してください。

コントロール関数 ^TOP^

CtlDrawControl 関数 ^TOP^

目的

コントロール オブジェクト（とその中のテキストまたはグラフィック）をスクリーン上に描きます。

宣言されている場所

Control.h

Prototype

void CtlDrawControl (
	ControlType *controlP
)

パラメータ

• → controlP
  • 描くコントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

返り値はありません。

コメント

usable 属性が true である場合にのみ、コントロールは描かれます。この関数は visible 属性を true にセットします。

互換性

Palm OS 3.5 より前のリリースでは、ビットマップの上にテキスト ラベルの無いボタンを描くことによってグラフィカル ボタンを作成する方法が普通でした。3.5 New Feature Set が存在する場合、代わりにグラフィカル コントロールを使用すべきです。（GraphicControlType を参照してください。）CtlDrawControl は古いタイプのグラフィカル ボタンに対して下位互換を提供しようと試みます。

参照

CtlSetUsable(), CtlShowControl()

CtlEnabled 関数 ^TOP^

目的

コントロールがペンに反応する場合、true を返します。

宣言されている場所

Control.h

Prototype

Boolean CtlEnabled (
	const ControlType *controlP
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

コントロール オブジェクトがペンに反応する場合、true を返します。そうでない場合、false を返します。

コメント

この関数は、コントロールがスクリーン上で可視であるかどうかについては示しません。ペンに反応しないコントロールは可視かもしれません、そしてそうである場合、そのコントロールの見え方はペンに反応するコントロールと変わりません。そのようなコントロールを、アプリケーションの変更できない状態を表示するために、使用するかもしれません。

参照

CtlSetEnabled()

CtlEraseControl 関数 ^TOP^

目的

使用可能かつ可視のコントロール オブジェクトとそのフレームをスクリーンから消します。

宣言されている場所

Control.h

Prototype

void CtlEraseControl (
	ControlType *controlP
)

パラメータ

• → controlP
  • 消すコントロール オブジェクトへのポインタ。（ControlType を参照してください。）

コメント

この関数は visible 属性を false にセットします。3.5 New Feature Set が存在する場合、drawnAsSelected 属性をも false にセットします。

この関数を直接呼び出さないでください。その代わり、この関数を呼び出す FrmHideObject() を使用してください。

CtlGetLabel 関数 ^TOP^

目的

コントロールのテキスト ラベルへの文字ポインタを返します。

宣言されている場所

Control.h

Prototype

const Char *CtlGetLabel(
	const ControlType *controlP
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

null で終了している文字列へのポインタを返します。

コメント

controlP がグラフィカル コントロールまたはスライダ コントロールではないことを確認してください。グラフィカル コントロールとスライダ コントロール構造体はテキスト ラベル フィールドを持っていません。

参照

CtlSetLabel()

CtlGetSliderValues 関数 ^TOP^

目的

スライダ コントロールによって使用されている現在の値を返します。

宣言されている場所

Control.h

Prototype

void CtlGetSliderValues (
	const ControlType *ctlP,
	UInt16 *minValueP,
	UInt16 *maxValueP,
	UInt16 *pageSizeP,
	UInt16 *valueP
)

パラメータ

• → ctlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）
• ← minValueP
  • スライダの最小値。この値を取得したくない場合、NULL を渡してください。
• ← maxValueP
  • スライダの最大値。この値を取得したくない場合、NULL を渡してください。
• ← pageSizeP
  • スライダのページ サイズ値。この値を取得したくない場合、NULL を渡してください。
• ← valueP
  • スライダの現在値。この値を取得したくない場合、NULL を渡してください。

返り値

返り値はありません。スライダの値はこの関数へのパラメータの中に収められて返されます。

コメント

ctlP がスライダまたはフィードバック スライダではない場合、この関数はすぐに返ります。

互換性

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

参照

CtlSetSliderValues(), SliderControlType

CtlGetValue 関数 ^TOP^

目的

指定されたコントロールの現在の値を返します。

宣言されている場所

Control.h

Prototype

Int16 CtlGetValue (
	const ControlType *controlP
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

コントロールの現在の値を返します。たいていのコントロールでは、返り値は 0 (off) または 1 (on) のどちらかです。スライダでは、この関数は value フィールドの値を返します。

参照

CtlSetValue(), FrmGetControlGroupSelection|Palm OS Programmer's API Reference/11(), FrmSetControlGroupSelection(), FrmGetControlValue(), FrmSetControlValue()

CtlHandleEvent 関数 ^TOP^

目的

指定されたコントロール オブジェクトのイベントをハンドルします。

宣言されている場所

Control.h

Prototype

Boolean CtlHandleEvent (
	ControlType *controlP,
	EventType *pEvent
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）
• → pEvent
  • EventType 構造体へのポインタ

返り値

この関数によってイベントがハンドルされる場合、true を返します。ハンドルされるイベントを以下に示します。

• penDownEvent -- ペンがコントロールの領域内に接触する。
• ctlEnterEvent, ctlRepeatEvent それに ctlExitEvent -- イベント データの中のコントロール ID がコントロールの ID と一致する。

コメント

この関数でイベントをハンドルするために、コントロール オブジェクトは、使用可能、可視、さらにペンに反応する状態でなくてはなりません。

このルーチンが penDownEvent を受け取ると、ルーチンはペンの位置がコントロール オブジェクトの領域内かどうかをチェックします。領域内である場合、ctlEnterEvent がイベント キューに追加され、このルーチンは終了します。

このルーチンが ctlEnterEvent を受け取ると、コントロールは選択されたか選択を解除されたかに合わせて再描画されます。これはコントロールの前の状態次第です。

このルーチンが ctlEnterEvent または ctlRepeatEvent を受け取ると、ルーチンは渡されたイベント レコードのコントロール ID が指定された紺とローうの ID と一致するかどうかをチェックします。一致する場合、このルーチンはペンが持ち上げられる、または、ペンがオブジェクトの領域から離れるまでペンを追跡します。それ（訳者注: ペンの追跡を終了する出来事）が起こると、ペンがコントロールの領域内で持ち上げられた場合は、ctlSelectEevent がイベント キューに送られます。ペンが領域から出る場合、ctlExitEvent がイベント キューに送られます。

CtlHideControl 関数 ^TOP^

目的

コンロトールの usable 属性を false にセットし、コントロールをスクリーンから消します。

宣言されている場所

Control.h

Prototype

void CtlHideControl (
	ControlType *controlP
)

パラメータ

• → controlP
  • 隠すコントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

返り値はありません。

コメント

使用可能ではないコントロールは描かれず、ペンにも反応しません。

この関数は CtlEraseControl() と似ていますが、（visible を false にセットするのに加えて）usable をも false にセットする点が異なります。

この関数を直接呼び出さないでください。その代わり、同じ機能を果たし、すべてのユーザ インターフェイス オブジェクトのための FrmHideObject() を使用してください。

参照

CtlShowControl()

CtlHitControl 関数 ^TOP^

目的

コントロールをタップする動作をシミュレートします。この関数は ctlSelectEvent をイベント キューに追加します。

宣言されている場所

Control.h

Prototype

void CtlHitControl (
	const ControlType *controlP
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）

返り値

返り値はありません。

コメント

テスト時に有用です。

CtlNewControl 関数 ^TOP^

目的

新しいコントロール オブジェクトを動的に作成し、それを指定されたフォームにインストールします。

宣言されている場所

Control.h

Prototype

ControlType *CtlNewControl (
	void **formPP,
	UInt16 ID,
	ControlStyleType style,
	const Char *textP,
	Coord x,
	Coord y,
	Coord width,
	Coord height,
	FontID font,
	UInt8 group,
	Boolean leftAnchor
)

パラメータ

• ←→ formPP
  • 新しいコントロールがインストールされるフォームへのポインタへのポインタ。この値はハンドルされません。つまり、オブジェクトがメモリの中を移動しても formPP 値は変わらないということです。その後の呼び出しの中で、常にこの関数によって返される新しい formPP を使用します。
• → ID
  • コントロールの記号的 ID
• → style
  • 作成されるコントロールの種類を指定する ControlStyleType 値。（コントロールの種類: ボタン、プッシュ ボタン、リピート ボタン、チェック ボックス、ポップアップ トリガ、ポップアップ セレクタ）グラフィカル コントロールまたはスライダ コントロールを動的に作成するためには、それぞれ CtlNewGraphicControl() または CtlNewSliderControl() を使用してください。
• textP
  • コントロールのテキスト ラベルへのポンタ。textP が NULL の場合、コントロールはラベルを持ちません。ボタン、プッシュ ボタンそれにテキスト ボックスのみがテキスト ラベルを持ちます。このポインタの内容は作成されるコントロール自身のバッファにコピーされるため、CtlNewControl 関数が返った後であればいつでも textP ポインタを解放することができます。この文字列がコピーされるバッファは、フォームからコントロールを削除するとき、または、フォームを削除するときに自動的に解放されます。
• → x
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の水平座標
• → y
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の垂直座標
• → width
  • ピクセルで表現されたコントロールの幅。有効値は 1-160 です。width または height のどちらかの値が 0 である場合、コントロールは自動的に、テキスト パラメータの値として渡されたテキストを表示するために必要とされるサイズにされます。
• → height
  • ピクセルで表現されたコントロールの高さ。有効値は 1-160 です。width または height のどちらかの値が 0 である場合、コントロールは自動的に、テキスト パラメータの値として渡されたテキストを表示するために必要とされるサイズにされます。
• → font
  • コントロールのラベルを描くために使用されるフォント
• → group
  • 排他的グループの一部であるプッシュ ボタンまたはチェック ボックスのグループ ID。コントロール ルーチンは、他のコントロールが選択されたとき、選択されていたコントロールの選択を自動的に取り消しません。それは、それらのコントロールを管理するアプリケーションまたはダイアログ ボックスのようなより高いレベルのオブジェクト次第です。
• → leftAnchor
  • true である場合、このコントロールの領域の左端は固定されます。この属性は、ラベル テキストの変更に合わせて動的にリサイズするコントロールによって使用されます。

返り値

新しいコントロールへのポインタを返します。

互換性

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

参照

CtlValidatePointer(), FrmRemoveObject()

CtlNewGraphicControl 関数 ^TOP^

目的

新しいグラフィカル コントロールを動的に作成し、それを指定されたフォームにインストールします。

宣言されている場所

Control.h

Prototype

GraphicControlType *CtlNewGraphicControl(
	void **formPP,
	UInt16 ID,
	ControlStyleType style,
	DmResID bitmapID,
	DmResID selectedBitmapID,
	Coord x,
	Coord y,
	Coord width,
	Coord height,
	UInt8 group,
	Boolean leftAnchor
)

パラメータ

• ←→ formPP
  • 新しいコントロールがインストールされるフォームへのポインタへのポインタ。この値はハンドルされません。つまり、オブジェクトがメモリの中を移動しても formPP 値は変わらないということです。その後の呼び出しの中で、常にこの関数によって返される新しい formPP を使用します。
• → ID
  • コントロールの記号的 ID
• → style
  • 作成されるコントロールの種類を指定する ControlStyleType 値。（コントロールの種類: ボタン、プッシュ ボタン、リピート ボタン、チェック ボックス、ポップアップ トリガ、ポップアップ セレクタ）グラフィカル コントロールはチェック ボックスにはなれません。
• → bitmapID
  • ボタンの中に表示されるビットマップのリソース ID。
• → selectedBitmapID
  • 選択されたときにボタンが異なるビットマップを表示する場合の、選択されたときに表示されるビットマップのリソース ID。
• → x
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の水平座標
• → y
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の垂直座標
• → width
  • ピクセルで表現されたコントロールの幅。有効値は 1-160 です。
• → height
  • ピクセルで表現されたコントロールの高さ。有効値は 1-160 です。
• → group
  • 排他的グループの一部であるプッシュ ボタンのグループ ID。コントロール ルーチンは、他のコントロールが選択されたとき、選択されていたコントロールの選択を自動的に取り消しません。それは、それらのコントロールを管理するアプリケーションまたはダイアログ ボックスのようなより高いレベルのオブジェクト次第です。
• → leftAnchor
  • true である場合、このコントロールの領域の左端は固定されます。

返り値

新しいグラフィカル コントロールへのポインタを返します。GraphicControlType を参照してください。

互換性

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

参照

CtlNewSliderControl(), CtlNewControl(), CtlValidatePointer(), FrmRemoveObject()

CtlNewSliderControl 関数 ^TOP^

目的

新しいスライダまたはフィードバック スライダを動的に作成し、それを指定されたフォームにインストールします。

宣言されている場所

Control.h

Prototype

SliderControlType *CtlNewSliderControl void **formPP,
	UInt16 ID,
	ControlStyleType style,
	DmResID thumbID,
	DmResID backgroundID,
	Coord x,
	Coord y,
	Coord width,
	Coord height,
	UInt16 minValue,
	UInt16 maxValue,
	UInt16 pageSize,
	UInt16 value
)

パラメータ

• ←→ formPP
  • 新しいコントロールがインストールされるフォームへのポインタへのポインタ。この値はハンドルされません。つまり、オブジェクトがメモリの中を移動しても formPP 値は変わらないということです。その後の呼び出しの中で、常にこの関数によって返される新しい formPP を使用します。
• → ID
  • コントロールの記号的 ID
• → style
  • sliderCtl または feedbackSliderCtl のどちらか。ControlStyleType を参照してください。
• thumbID
  • スライダ thumbとして表示されるビットマップのリソース ID。スライダ thumb はスライダの値を変更するためにユーザがドラッグできるノブ（訳者注: 取っ手）です。デフォルトの thumb ビットマップを使用する場合、このパラメータに NULL を渡してください。
• backgroundID
  • スライダの背景として表示されるビットマップのリソース ID。デフォルトの背景ビットマップを使用する場合、このパラメータに NULL を渡してください。
• → x
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の水平座標
• → y
  • 作成されるコントロールが表示されるウィンドウに関係する、コントロールの領域の左上端の垂直座標
• → width
  • ピクセルで表現されたコントロールの幅。有効値は 1-160 です。
• → height
  • ピクセルで表現されたコントロールの高さ。有効値は 1-160 です。
• → minValue
  • スライダの最小値。
• → maxValue
  • スライダの最大値。
• → pageSize
  • ユーザが thumb の右または左をクリックしたときにスライダの値を増加または減少させる量。
• → value
  • スライダの中に表示するための初期値。

返り値

新しいスライダ コントロールへのポインタを返します。SliderControlType を参照してください。

互換性

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

参照

CtlNewGraphicControl(), CtlNewControl(), CtlValidatePointer(), FrmRemoveObject()

CtlSetEnabled 関数 ^TOP^

目的

コントロールを機能可能または機能不可としてセットします。機能不可のコントロールはペンに反応しません。

宣言されている場所

Control.h

Prototype

void CtlSetEnabled (
	ControlType *controlP,
	Boolean usable
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）
• → usable
  • コントロールを機能可能にするには true、コントロールを機能不可にするには false

返り値

返り値はありません。

コメント

可視のコントロールを機能不可にした場合、コントロールは表示されたままで、ペンに反応するコントロールと見た目は変わりません。変更できないアプリケーションの状態をユーザに知らせるために、そのようなコントロールを使用することがあるかもしれません。

参照

CtlEnabled()

CtlSetGraphics 関数 ^TOP^

目的

グラフィカル コントロールのためのビットマップをセットし、コントロールが可視の場合はそれを再描画します。

宣言されている場所

Control.h

Prototype

void CtlSetGraphics (
	ControlType *ctlP,
	DmResID newBitmapID,
	DmResID newSelectedBitmapID
)

パラメータ

• → ctlP
  • グラフィカル コントロール オブジェクトへのポインタ。（ControlType を参照してください。）
• → newBitmapID
  • コントロールの上に表示するための新しいビットマップのリソース ID。または、現在のビットマップを使用する場合、NULL。
• → newSelectedBitmapID
  • コントロールが選択されたときに表示するための新しいビットマップのリソース ID。または、現在のビットマップを使用する場合、NULL。

返り値

返り値はありません。

コメント

ctlP がグラフィカル コントロールではない場合、この関数はすぐに返ります。

互換性

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

参照

GraphicControlType

CtlSetLabel 関数 ^TOP^

目的

指定されたコントロール オブジェクトのための新しい（訳者注: 原文では current となっていたが誤りと思われる）ラベルをセットし、コントロールが可視の場合はそれを再描画します。

宣言されている場所

Control.h

Prototype

void CtlSetLabel (
	ControlType *controlP,
	const Char *newLabel
)

パラメータ

• → controlP
  • コントロール オブジェクトへのポインタ。（ControlType を参照してください。）
• → newLabel
  • 新しいテキスト ラベルへのポインタ。null で終了している文字列でなければなりません。

返り値

返り値はありません。

コメント

この関数は、新しいラベルのサイズに合わせて、コントロールの幅をリサイズします。

この関数は newLabel ポインタをコントロールのデータ構造体の中に保存します。渡された文字列のコピーを作成しません。ですから、CtlSetLabel を使用する場合、文字列を管理しなくてはなりません。文字列が表示されている限りは（つまり、コントロールが表示されている限り、または、新しい文字列を使って CtlSetLabel を再度呼び出すまでは）、文字列が維持されることを保証する必要があり、さらに、文字列がもはや使われなくなったとき（たいていはコントロールを保持していたフォームが解放されるとき）、文字列を解放する必要があります。

CtlSetLabel を一度も使用しないのなら、コントロールのラベルを解放することについて気を配る必要はありません。

controlP がグラフィカル コントロールまたはスライダ コントロールでないことを確認してください。グラフィカル コントロールとスライダ コントロール構造体はテキスト ラベル フィールドを持ちません。そのため、それらのコントロールにラベルをセットしようとするとアプリケーションがクラッシュします。

参照

CtlGetLabel()

CtlSetSliderValues 関数 ^TOP~

目的

スライダ コントロールの値を変更し、スライダが可視である場合はそれを再描画します。

宣言されている場所

Control.h

Prototype

void CtlSetSliderValues (
	ControlType *ctlP,
	const UInt16 *minValueP,
	const UInt16 *maxValueP,
	const UInt16 *pageSizeP,
	const UInt16 *valueP
)

パラメータ

• → ctlP
  • アクティブではないスライダまたはフィードバック スライダ コントロールへのポインタ。（ControlType を参照してください。）
• → minValueP
  • スライダの最小値として使用される新しい値へのポインタ。この値を変更したくない場合、NULL を渡してください。
• → maxValueP
  • スライダの最大値として使用される新しい値へのポインタ。この値を変更したくない場合、NULL を渡してください。
• → pageSizeP
  • スライダのページ サイズとして使用される新しい値へのポインタ。この値を変更したくない場合、NULL を渡してください。
• → valueP
  • スライダの現在値として使用される新しい値へのポインタ。この値を変更したくない場合、NULL を渡してください。

返り値

返り値はありません。

コメント

コントロールのスタイルは sliderCtl または feedbackSliderCtl であり、コントロールが現在ペンを追跡している状態ではない必要があります。スライダが現在ペンを追跡している場合、value フィールドをセットするためには CtlSetValue() を使用してください。

互換性

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

参照

CtlGetSliderValues(), SliderControlType

CtlSetUsable 関数 ^TOP^

目的

コントロールを使用可能または使用不可にセットします。

宣言されている場所

Control.h

Prototype

void CtlSetUsable (
	ControlType *controlP,
	Boolean usable
)

パラメータ

• → controlP
  • コントロールへのポインタ。（ControlType を参照してください。）
• → usable
  • コントロールを使用可能にするには true、コントロールを使用不可にするには false

返り値

返り値はありません。

コメント

使用不可のコントロールは描かれず、ペンにも反応しません。

この関数は、通常、コントロールを更新しません。

参照

CtlEraseControl(), CtlHideControl(), CtlShowControl()

CtlSetValue 関数 ^TOP^

目的

指定されたコントロールの現在値をセットします。コントロールが可視の場合でも、それは再描画されません。

宣言されている場所

Control.h

Prototype

void CtlSetValue (
	ControlType *controlP,
	Int16 newValue
)

パラメータ

• → controlP
  • コントロールへのポインタ。（ControlType を参照してください。）
• → newValue
  • コントロールにセットされる新しい値。スライダの場合、スライダの最小値と最大値の間の値を指定します。グラフィッカル コントロール、プッシュ ボタンまたはチェック ボックスの場合、off にするには 0 を、on にするには 0 以外を指定します。

返り値

返り値はありません。

コメント

この関数は、グラフィカル コントロール、スライダ、プッシュ ボタンそれにチェック ボックスに対してのみ機能します。これ以外のすべてのコントロールの値をセットする場合、どのような振る舞いをするか定義されていません。

互換性

スライダとグラフィカル コントロールは、3.5 New Feature Set が存在する場合にのみ、実装されます。

参照

CtlGetValue(), FrmGetControlGroupSelection(), FrmSetControlGroupSelection(), FrmGetControlValue(), FrmSetControlValue()

CtlShowControl 関数 ^TOP^

目的

コントロールの usable 属性を true にセットし、スクリーン上にコントロールを描きます。この関数は CtlDrawControl() を呼び出します。

宣言されている場所

Control.h

Prototype

void CtlShowControl (
	ControlType *controlP
)

パラメータ

• → controlP
  • コントロールへのポインタ。（ControlType を参照してください。）

返り値

返り値はありません。

コメント

コントロールがすでに使用可能になっている場合、この関数は CtlDrawControl と等価の関数です。

visible と usable 属性を true にセットします。（ControlAttrType を参照してください。）

この関数を直接呼び出さないでください。代わりに、同じ機能を果たす FrmShowObject() を呼び出してください。

参照

CtlHideControl()

CtlValidatePointer 関数 ^TOP^

目的

指定されたポインタが有効なコントロール オブジェクトを参照している場合、true を返します。

宣言されている場所

Control.h

Prototype

Boolean CtlValidatePointer(
	const ControlType *controlP
)

パラメータ

• → controlP
  • コントロールへのポインタ。（ControlType を参照してください。）

返り値

コントロールへの有効なポインタが渡された場合、true を返します。そうでない場合、false を返します。

コメント

デバッグ用です。製品の中にこの関数を含めないでください。デバッグ ビルドの中で、エラーが起こると、この関数はダイアログを表示し、デバッガを待ちます。

互換性

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

参照

FrmValidatePtr(), WinValidateHandle()|Palm OS Programmer's API Reference/59

←　6 章に戻る　↑トップへ　8 章に進む　→