Palm Programmer's Laboratory

トップ 差分 一覧 ソース 検索 ヘルプ RSS ログイン

Palm OS Programmer's API Reference/9

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

9 フィールド

この章ではフィールド オブジェクトについて以下のことを説明します。

ヘッダファイル Field.h がこの章で説明する API を宣言しています。フィールドについての追加情報は Palm OS Programmer's Companion, vol. I の「フィールド」を参照してください。

フィールド データ構造体 ^TOP^

FieldAttrType 構造体 ^TOP^

目的

FieldAttrType ビット フィールドはフィールドの可視特性を定義します。FldGetAttributes() と FldSetAttributes() 関数がこれらの値を返します。ここで定義される特性を各個に検索またはセットする関数も他にあります。それらの関数についてはあとで説明します。

WARNING!!!
特性を変更するために FldSetAttributes() 関数を呼び出してはいけません。この関数は「内部使用のみ」です。

Prototype

typedef struct {
	UInt16 usable:1;
	UInt16 visible:1;
	UInt16 editable:1;
	UInt16 singleLine:1;
	UInt16 hasFocus:1;
	UInt16 dynamicSize:1;
	UInt16 insPtVisible:1;
	UInt16 dirty:1;
	UInt16 underlined:2;
	UInt16 justification:2;
	UInt16 autoShift:1;
	UInt16 hasScrollBar:1;
	UInt16 numeric:1;
} FieldAttrType;

フィールド

  • usable
    • セットされていないと、フィールド オブジェクトは現在のアプリケーション インターフェイスの一部として扱われず、画面にも表示されません。FldSetUsable() 関数はこの値をセットしますが、FrmShowObject() を使用するほうが望ましいです。
  • visible
  • editable
    • セットされていないと、フィールド オブジェクトはテキスト入力と編集を許可せず、ペンによる挿入ポイントの挿入も受け付けません。テキストの選択とコピーを行えるだけです。
  • singleLine
    • （このフラグは内部使用のみです。）セットされていると、フィールドは 1 行であり、テキストがフィールドの幅を超えても折り返されません。セットされていないと、テキストは複数行を満たすように折り返されます。このフラグの値を変更してフィールドを単一行から複数行に（またはその逆に）変更することはできません。
  • hasFocus
    • フィールドがフォーカスされたときに内部的にセットされます。点滅する挿入ポイントが現在フォーカスされているフィールド内に現れます。この値をセットするために関数 FrmSetFocus() と FldReleaseFocus() を使用します。FldSetAttributes でこの特性をセットしようとしないでください。
  • dynamicSize
    • セットされていると、行数を増やすまたは減らす必要が生じたときに fldHeightChangeEvent が発生します。アプリケーションは、フィールドの境界ボックスのサイズを調節することで、このイベントに応答する必要があります。セットされていないと、テキストは現在の行数以上（または以下）の行を満たすように折り返されますが、イベントは発生しません。このビットによって自動的にフィールドのサイズが変更されるわけではないことに注意してください。アプリケーションは fldHeightChangeEvent に応答し、フィールドをリサイズしなくてはなりません。単一行特性がセットされている場合は、この特性を false にセットします。
  • instPrVisible
    • セットされていると、挿入ポイントは視界に入るようにスクロールされます。この特性は内部使用のみです。
  • dirty
    • セットされている場合は、ユーザによる変更が行われています。FldDirty() と FldSetDirty() 関数がこのフィールドの値を調べます。FldSetAttributes でこの特性をセットしようとしないでください。
  • underlined
    • セットされていると、フィールドの各行に下線（破線を含む）が引かれます。とりうる値は Window.h で定義される UnderlineModeType によって決定されます。
      • noUnderline
      • grayUnderline
      • solidUnderline
      • colorUnderline
    • 編集可能なテキスト フィールドは、通常、grayUnderline を使用します。
    • solidUnderline は Palm OS 3.1 以降で有効です。
    • colorUnderline は Palm OS 3.5 以降で有効です。
  • justification
    • テキストの配置方法を指定します。とりうる値は leftAlign と rightAlign です。（左寄せと右寄せのみがサポートされています。centerAlign はサポートされていません）
  • autoShift
    • セットされていると、自動シフト ルールが適用されます。
  • hasScrollBar
    • セットされていると、フィールドはスクロール バーを持ちます。システムは、アプリケーションが適切に高さを調節できるように、より頻繁に fldChangeEvent を発します。
  • numeric
    • セットされていると、0 から 9 までの文字と関連の区切り文字のみをフィールドに入力することができます。関連の区切り文字は、千単位の区切り文字と小数点の区切り文字です。これら 2 つの文字がどの文字になるかは、フォーマット設定パネルでの設定に依存します。

FieldPtr Typedef ^TOP^

目的

FieldPtr 型は FieldType 構造体へのポインタを定義します。

Prototype

typedef FieldType *FieldPtr;

FieldPtr はすべてのフィールド関数への引数として渡されます。FrmGetObjectPtr() 関数を用いて FieldPtr を取得するには、以下のようにします。

fldPtr = FrmGetObjectPtr(frm, 
	FrmGetObjectIndex(frm, fldID));

fldID はフィールドを作成したときに割り当てたリソース ID です。

FieldType 構造体 ^TOP^

目的

FieldType 構造体はフィールドを表します。

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

Prototype

typedef struct {
	UInt16 id;
	RectangleType rect;
	FieldAttrType attr;
	Char *text;
	MemHandle textHandle;
	LineInfoPtr lines;
	UInt16 textLen;
	UInt16 textBlockSize;
	UInt16 maxChars;
	UInt16 selFirstPos;
	UInt16 selLastPos;
	UInt16 insPtXPos;
	UInt16 insPtYPos;
	FontID fontID;
	UInt8 reserved;
} FieldType;

コードでは FieldType 構造体を実体の無いものとして扱うべきです。あとで説明する各値を調べたりセットする関数を使ってください。この構造体のメンバの値を直接変更しようとしないでください。

フィールド

  • id
    • フィールド リソースを作成したときに指定した ID です。この ID 値は fldEnterEvent のイベント データにデータの一部として含まれます。
  • rect
  • attr
    • フィールド オブジェクトの属性です。（FieldAttrType を参照してください）
  • text
    • フィールド オブジェクトによって表示される null で終了する文字列へのポインタです。FldGetTextPtr() と FldSetTextPtr() 関数がこの値を調べ、セットします。（以下を参照してください）
    • この文字列の中身を直接セットしてはいけません。例えば、このポインタを StrCopy 関数などにあて先の値（destination value）として渡さないでください。
  • textHandle
    • 格納されているテキストまたはデータベース レコードに格納されているテキストへのハンドルです。FldGetTextHandle() と FldSetTextHandle() 関数がこの値を調べ、セットします。
    • textHandle が定義されている場合、そのテキスト ポインタがロックされるとフィールドはそのポインタを信頼します。一般的に、編集不可のテキスト フィールドには FldGetTextPtr() と FldSetTextPtr() 関数のみを使用すべきです。編集可能なテキスト フィールドには FldGetTextHandle() と FldSetTextHandle() 関数を使用します。また、編集可能なテキスト フィールドは必要があればテキスト ハンドルを割り当てます。ユーザが割り当てられたテキスト ハンドルを持っていないフィールドに文字を入力し始めると、フィールドはテキスト ハンドルを 1 つ割り当てるでしょう。そのフィールドは、また、ユーザがさらにテキストを追加すると必要に応じてテキストのメモリ ブロックをリサイズします。
  • lines
    • LineInfoType 構造体の配列へのポインタです。テキストの各可視行には、この配列の中に 1 つのエントリがあります。（LineInfoType を参照してください）フィールドのコードはこの配列を内部でメンテナンスします。lines 配列を直接変更すべきではありません。
    • 単一行フィールドと割り当てられたテキスト ハンドルを持たないフィールドの場合、この値は NULL であることに注意してください。
  • textBlockSize
    • フィールド オブジェクトのテキスト文字列を保持しているメモリ ブロックに割り当てられたサイズです。この値は FldGetTextAllocatedSize() で調べることができます。フィールドは、必要に応じて、フィールド テキストに対して 1 回に数バイトのメモリを割り当てます。
    • textBlockSize は、textHandle によって指されているチャンクのサイズとは異なるかもしれないということに注意してください。textHandle は、フィールドに表示されたテキストを一部含んでいるデータベース レコードを指しているかもしれません。そのような textHandle に対して MemHandleSize() を呼び出した場合、返される値は textBlockSize よりも大きいかもしれません。
  • maxChars
    • フィールド オブジェクトが受け入れることができる最大バイト数です。FldGetMaxChars() と FldSetMaxChars() 関数がこの値を調べ、セットします。textLen,TextBlockSize と maxChars は違うということに注意してください。textLen は text が実際に保持している文字データのバイト数です。textBlockSize はテキストに現在割り当てられているメモリの量です（これは textLen 以上でなくてはなりません）。maxChars は、textBlockSize と textLen が拡張することができる最大値を、セットします。
    • 例えば、ユーザがファースト ネームを入力するテキスト フィールドを作成し、このフィールドの最大長を 20 バイトと指定したとします。ユーザが「John」と入力すると、textLen は 4 に、textBlockSize は 16 に、そして maxChars は 20 になります。
  • selFirstPos
    • 現在の選択されている文字開始位置のオフセット（バイト単位）です。この値と selLastPos の値を調べ、セットするのには、FldGetSelection() と FldSetSelection() を使用してください。
  • selLastPos
    • 現在の選択されている文字終了位置のオフセット（バイト単位）です。selFirstPos と selLastPos が等しい場合は、何も選択されていません。
  • insPtXPos
    • 挿入ポイントの水平位置です。insPtYPos によって指される行でのオフセット（バイト単位）として与えられます。FldGetInsPtPosition()} と {{goto FldSetInsPtPosition 関数がこの値から算出されるバイト オフセットを調べ、セットします。挿入ポイントが見えていない場合 -- 挿入ポイントが見えている行の上あるいは下にある --、insPtXPos は挿入ポイントのバイト オフセットの絶対値になります。
  • insPtYPos
    • 挿入ポイントの垂直位置です。表示されている行の何行目に挿入ポイントが位置しているかで与えられます。表示されている最初の行は 0 です。フィールドがスクロールされている場合、表示されている最初の行はフィールドのテキストの最初の行ではないかもしれません。FldGetInsPtPosition() と FldSetInsPtPosition() 関数がこの値から計算されるバイト オフセットを調べ、セットします。挿入ポイントが見えていない場合 -- 挿入ポイントが見えている行の上あるいは下にある -- insPtYPos は 0x8000 にセットされています。
  • fontID
    • フィールドのフォント ID です。詳しいことは Font.h を参照してください。FldGetFont() と FldSetFont() 関数がこの値を調べ、セットします。
  • reserved
    • 将来使用するために予約されています。

LineInfoPtr Typedef ^TOP^

目的

LineInfoPtr 型は LineInfoType へのポインタを定義します。

Prototype

typedef LineInfoType *LineInfoPtr;

LineInfoType 構造体 ^TOP^

目的

LineInfoType 構造体はフィールドの lines 配列の 1 要素を定義します。lines 配列は、情報を保持しているフィールドの語を、保持します。配列中には、フィールドのテキストを持たない行も含めた可視行ごとに、1 要素が存在します。フィールド コードはこの配列を内部的に維持します。決して、lines 配列を直接変更しようとすべきではありません。

関数 {goto FldCalcFieldHeight,FldCalcFieldHeight()}}, FldGetVisibleLines(), FldRecalculateField() それに FldGetNumberOfBlankLines() はこの構造体の情報を調べ、または、セットします。スクロールに係る関数 FldGetScrollPosition(), FldGetScrollValues(), FldScrollField() それに FldSetScrollPosition() もまたこの構造体の情報を調べ、または、セットします。

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

Prototype

typedef struct {
	UInt16 start;
	UInt16 length;
} LineInfoType;

フィールド

  • start
    • この行で表示される最初の文字を保持する FieldType の text フィールドへのバイト オフセット。行が空の場合、start は textLen と等しく、かつ、length は 0 です。
  • length
    • この行の文字列で表示される部分のバイト長。行が空の場合、length は 0 です。

フィールド リソース ^TOP^

フィールド リソース（tFLD）はスクリーン上のフィールドを表します。詳細は、Palm OS User Interface Guidelines を参照してください。

フィールド関数 ^TOP^

FldCalcFieldHeight 関数 ^TOP^

目的

文字列のためにフィールドの高さを調べます。

宣言されている場所

Field.h

Prototype

UInt16 FldCalcFieldHeight (
	const Char *chars,
	UInt16 maxWidth
)

パラメータ

  • → chars
    • null で終了する文字列へのポインタ
  • → maxWidth
    • ピクセル単位での最大行幅

返り値

渡された文字列を表示するのに必要な行の総数を返します。

コメント

フィールドの幅は、FieldType 構造体の rect メンバに含まれます。この値を以下の方法で調べることができます。

FrmGetObjectBounds(frm,  
	FrmGetObjectIndex(frm, fldID), 
	&myRect); 
fieldWidth = myRect.extent.x; 
FldCalcFieldHeight(myString, fieldWidth);

参照

FldWordWrap()

FldCompactText 関数 ^TOP^

目的

フィールドのテキストを保持しているメモリ ブロックを圧縮し、使われなくなった容量を解放します。

宣言されている場所

Field.h

Prototype

void FldCompactText (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

文字がフィールドのテキストに追加されるのに合わせて、テキストを保持しているブロックも大きくなります。ブロックは 1 度に数バイトずつ拡張されるため、文字が追加されるたびに拡張する必要はありません。この拡張は、結果として、テキスト ブロックに使用されない容量を作り出すかもしれません。

アプリケーションは、フィールドのロックを解除する前の適当なタイミングで、フィールド オブジェクトに対してデータ レコードを編集するこの関数を呼び出すべきです。また、コンパクトなフィールドが望まれる場合にも呼び出すべきです。例えば、ストレージ ヒープに書き込みを行う前です。

参照

FldGetTextAllocatedSize(), FldSetTextAllocatedSize()

FldCopy 関数 ^TOP^

目的

現在の選択（訳者注: 現在選択されている文字列）をテキスト クリップボードにコピーします。

宣言されている場所

Field.h

Prototype

void FldCopy (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

この関数は現在の選択をハイライトされたままにしておきます。

この関数は、テキスト クリップボードにコピーされたテキストがある場合、それを置き換えます。テキストが選択されていない場合、関数はビープ音を鳴らし、クリップ ボードには手を付けません。

参照

FldCut(), FldPaste()

FldCut 関数 ^TOP^

目的

現在の選択（訳者注: 現在選択されている文字列）をテキスト クリップボードにコピーし、フィールドから選択された文字列を削除し、フィールドを描き直します。

宣言されている場所

Field.h

Prototype

void FldCut (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

テキストが選択されている場合、そのテキストはフィールドから削除され、フィールドの Dirty 属性がセットされ、テキスト クリップボードにある前のテキストは選択されているテキストによって置き換えられます。

選択されたテキストが無い場合、または、フィールドが編集不可の場合、この関数はビープ音を鳴らします。

FldDelete 関数 ^TOP^

目的

指定された範囲の文字をフィールドから削除し、フィールドを描き直します。

宣言されている場所

Field.h

Prototype

void FldDelete (
	FieldType *fldP,
	UInt16 start,
	UInt16 end
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → start
    • フィールドの text 文字列への有効バイト オフセットとして与えられる削除する文字範囲の開始点
  • → end
    • フィールドの text 文字列への有効バイト オフセットとして与えられる削除する文字範囲の終了点。マルチ バイト文字をサポートしているシステムでは、この場所は文字の境目でなくてはなりません。つまり、マルチ バイト文字の中間点になってはいけません。フィールドのバイト数よりも大きな値が渡された場合、フィールドのすべての文字が削除されます。

返り値

返り値はありません。

コメント

この関数は、開始オフセットから終了オフセットまでのすべての文字を削除し、フィールドの Dirty 属性とセットします。終了オフセット地点の文字は削除しません。

start または end がマルチ バイト文字の内部を指す場合、FldDelete はオフセットを、テキストの開始点に向けてオフセットが文字の境目を指すまで、ずらそうと試みます。

FldDelte は fldChangedEvent をイベント キューに対して発します。この関数を繰り返し呼び出した場合、イベント キューは fkdChangedEvent によってオーバー フローしてしまうかもしれません。代わりに、フィールドからテキスト ハンドルを取り外し、テキストを変更し、再度フィールドのハンドルとしてセットする方法があります。コードの例は、FldGetTextHandle() を参照してください。

参照

FldInsert(), FldEraseField(), TxtCharBounds()|Palm OS Programmer's API Reference/55

FldDirty 関数 ^TOP^

テキスト値がセットされてからフィールドが変更されている場合、true を返します。

宣言されている場所

Field.h

Prototype

Boolean FldDirty (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

ユーザ、あるいは、FldInsert() や FldDelete() などの関数を呼び出すことによってフィールドが変更されている場合は、true を返します。フィールドが変更されていない場合は、false を返します。

参照

FldSetDirty(), FieldAttrType

FldDrawField 関数 ^TOP^

目的

フィールドのテキストを描きます。

宣言されている場所

Field.h

Prototype

void FldDrawField (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

フィールドの usable 属性は、true でなくてはなりません。そうでなければ、フィールドを描くことができません。

この関数は、以前にフィールドに描かれたものを消しません。

フィールドがフォーカスされている場合、点滅する挿入ポイントがフィールドに表示されます。

参照

FldEraseField()

FldEraseField 関数 ^TOP^

目的

フィールドのテキストを消し、フィールドに挿入ポイントがある場合は、それも消します。

宣言されている場所

Field.h

Prototype

void FldEraseField (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

まれに、この関数を直接呼び出す必要が生じます。代わりとして、FldEraseField を呼び出す FrmHideObject() を使用します。

この関数はディスプレイからフィールドを明示的に消去しますが、フィールドの中身を変更したり、フィールドに関連するメモリを解放したりすることはしません。

フィールドがフォーカスされている場合、点滅する挿入ポイントは消されます。

この関数は、visible 属性を false にセットします。（FieldAttrType を参照してください。）

参照

FldDrawField()

FldFreeMemory 関数 ^TOP^

目的

フィールドのテキストと、それに関連付けられた各行が保持するテキスト関連の情報に割り当てられているハンドル ベースのメモリを解放します。

宣言されている場所

Field.h

Prototype

void FldFreeMemory (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。フィールドに関連するテキストがデータベースのレコードである場合、致命的なエラー メッセージが表示されるかもしれません。

コメント

この関数が解放するのは以下のものです。

  • フィールドのテキストに割り当てられているメモリ -- FieldType データ 構造体の textHandle メンバが指すメモリ ブロック
    • フィールドの textHandle は NULL だが そのフィールドに関連する text 文字列がある場合（編集不可のテキスト フィールドだとしばしばありえます）、そのテキスト文字列は解放されません。
  • 各行が保持するテキスト関連の情報を保持するために割り当てられているメモリ -- FieldType データ 構造体の lines メンバが指すメモリ ブロック

この関数はフィールドの表示には影響を与えません。フィールドはテキスト文字列に必要があればメモリを割り当てます。そのため、フィールドがまだ表示されている間にこの関数を呼び出してもエラーにはなりません。つまり、text が NULL で、ユーザがそのフィールドに文字を打ち込み始めた場合、フィールドは、単純に、テキストにメモリを割り当て、表示され続けます。

FldGetAttributes 関数 ^TOP^

目的

フィールドの属性を返します。

宣言されている場所

Field.h

Prototype

void FldGetAttributes (
	const FieldType *fldP,
	FieldAttrPtr attrP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • ← attrP

返り値

フィールドの属性を attP パラメータに収めて返します。

参照

FldSetAttributes()

FldGetBounds 関数 ^TOP^

目的

フィールドの現在の境界を返します。

宣言されている場所

Field.h

Prototype

void FldGetBounds (
	const FieldType *fldP,
	RectanglePtr rect
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • ← rect
    • RectangleType 構造体へのポインタ

返り値

返り値はありません。rect で参照される RectangleType 構造体にフィールドの境界が保存されています。

コメント

FieldType 構造体の rect フィールドを返します。

参照

FldSetBounds(), FrmGetObjectBounds()

FldGetFont 関数 ^TOP^

目的

フィールドのテキストを描くのに使用されているフォントの ID を返します。

宣言されている場所

Field.h

Prototype

FontID FldGetFont (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

フォントの ID を返します。

参照

FldSetFont()

FldGetInsPtPosition 関数 ^TOP^

目的

文字列中の挿入ポイントの位置を返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetInsPtPosition(
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

挿入ポイントのバイト オフセットを返します。

コメント

この関数が返す挿入ポイントは左端からのバイト オフセットです。つまり、この関数が 0 を返した場合、挿入ポイントは文字列の最初の文字の左側です。複数行のフィールドの場合、行送り（訳者注: 原文は line feed。1 行を 1 改行文字としてカウントするということ？）は文字列中の 1 文字としてカウントされ、1 つの行送り文字後のバイト オフセットは次の行の始まりとなります。

参照

FldSetInsPtPosition()

FldGetMaxChars 関数 ^TOP^

目的

フィールドが受け入れる最大バイト数を返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetMaxChars (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

ユーザが入力することができる文字の最大長をバイト数で返します。返り値は FieldType の maxChars です。

参照

FldSetMaxChars()

FldGetNumberOfBlankLines 関数 ^TOP^

目的

フィールドの最後に表示される空の行数を返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetNumberOfBlankLines(
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

可視の空の行数を返します。

コメント

このルーチンは、フィールドのテキストから文字を削除した後にスクロール バーを更新するのに有用です。サンプルとして挙げられているアドレス帳の NoteViewScroll 関数を参照してください。

互換性

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

FldGetScrollPosition 関数 ^TOP^

目的

フィールドの最初の可視行の最初の文字のオフセットを返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetScrollPosition(
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

最初の可視文字のオフセットを返します。

参照

FldSetScrollPosition(), LineInfoType

FldGetScrollValues 関数 ^TOP^

目的

スクロール バーの更新に必要な値を返します。

宣言されている場所

Field.h

Prototype

void FldGetScrollValues (
	const FieldType *fldP,
	UInt16 *scrollPosP,
	UInt16 *textHeightP,
	UInt16 *fieldHeightP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • ← scrollPosP
    • 最初の可視行であるテキストの行。行番号は 0 から始まります。
  • ← textHeightP
    • 与えられたフィールド幅からフィールドのテキストを表示するのに必要な行数を返します。
  • ← fieldHeightP
    • フィールドの可視行の行数

返り値

返り値はありません。位置、テキストの高さ、それに、フィールドの高さを渡されたパラメータに収めます。

コメント

この関数が返す値を使用して、スクロール バーを更新する SclSetScrollBar() に送る値を計算します。以下に例を挙げます。

FldGetScrollValues (fldP, &scrollPos,
  &textHeight,  &fieldHeight);
  
if (textHeight > fieldHeight)
  maxValue = textHeight - fieldHeight;
else if (scrollPos)
  maxValue = scrollPos;
else
  maxValue = 0;
  
SclSetScrollBar (bar, scrollPos, 0, maxValue,
  fieldHeight-1);
}

互換性

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

参照

FldSetScrollPosition()

FldGetSelection 関数 ^TOP^

目的

フィールドの現在の選択を返します。

宣言されている場所

Field.h

Prototype

void FldGetSelection (
	const FieldType *fldP,
	UInt16 *startPosition,
	UInt16 *endPosition
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • ← startPosition
    • 選択された文字の範囲の開始点へのポインタ。フィールドのテキストのバイト オフセットとして与えられます。
  • ← endPosition
    • 選択された文字の範囲の終了点へのポインタ。フィールドのテキストのバイト オフセットとして与えられます。

返り値

開始バイト オフセットと終了バイト オフセットを startPosition と endPosition に収めて返します。

コメント

フィールドの最初の文字は、オフセット 0 です。

ユーザがフィールドの最初の 5 文字を選択している場合、すべての文字が 1 バイト長と仮定すると、startPosition は値 0 を、endPosition は値 5 を保持します。

参照

FldSetSelection()

FldGetTextAllocatedSize 関数 ^TOP^

目的

フィールドのテキスト文字列を保持するために割り当てられたバイト数を返します。この数値と表示されているフィールドのテキスト文字列の長さを混同しないでください。

宣言されている場所

Field.h

Prototype

UInt16 FldGetTextAllocatedSize(
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

フィールドのテキストに割り当てられたバイト数を返します。この値は FieldType の textBlockSize フィールドです。

参照

FldSetTextAllocatedSize()

FldGetTextHandle 関数 ^TOP^

目的

フィールドのテキスト文字列を保持しているブロックへのハンドルを返します。

宣言されている場所

Field.h

Prototype

MemHandle FldGetTextHandle (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

フィールドのテキスト文字列へのハンドルを返します。フィールド ポインタに対してハンドルが割り当てられていない場合、NULL を返します。

コメント

この関数によって返されるハンドルは、必ずしも文字列の開始点へのハンドルではありません。フィールドのテキストをデータベース レコードの一部である文字列にセットするために FldSetText() を使用した場合、テキスト ハンドルはそのレコードの開始点を指します。レコードの開始点から文字列の開始点までのオフセットを計算する必要があります。FleSetText に渡したオフセットを保存することもできますし、この関数で返されるハンドルをロックすることで得られるポインタと FldGetTextPtr() によって返されるポインタに対してポインタ計算を行うことでオフセットを算出することもできます。

フィールドのテキストを編集できるようにするためにテキスト ハンドルを取得する場合、取得する前にフィールドからハンドルを削除しなくてはなりません。テキストがフィールドによって使用されている間にそのテキストを変更すると、テキストの長さ、割り当てサイズ、各行が保持するテキスト関連の情報を指定しているフィールドの内部構造体は同期（訳者注: 原文は sync）から外されてしまいます。この問題を避けるために、フィールドからテキスト ハンドルを削除し、テキストを変更し、それからフィールドのテキスト ハンドルを再度セットしてください。以下に例を挙げます。

// Get the handle for the string and unlock
// it by removing it from the field.
textH = FldGetTextHandle(fldP);
FldSetTextHandle (fldP, NULL);
 
/* Insert code that modifies the string here.*/
/* The basic steps are: */
/* resize the chunk if necessary,*/
/* lock the chunk, write to it, and then */
/* unlock the chunk. If the text is in a */
/* database record, use Data Manager calls. */

/* Update the text in the field. */
FldSetTextHandle (fldP, textH);
FldDrawField(fldP);

参照

FldSetTextHandle(), FldGetTextPtr()

FldGetTextHeight ^TOP^

目的

空でない可視行の高さをピクセル数で返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetTextHeight (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

空でない可視行の高さをピクセル数で返します。

コメント

空の行とは、テキストの最後のバイトの後に続くフィールド中のすべての行です。1 つの改行のみを持つ行は空ではないということに注意してください。また、可視の行のみがカウントされるということにも注意してください。

参照

FldCalcFieldHeight()

FldGetTextLength ^TOP^

目的

フィールドのテキストの長さをバイト数で返します。

宣言されている場所

Field.h

Prototype

UInt16 FldGetTextLength (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

null 終端文字を含まないフィールドのテキストの長さをバイト数で返します。返されるのは FieldType の textLen フィールドです。

FldGetTextPtr ^TOP^

目的

フィールドのテキスト文字列へのロックされたポインタを返します。

宣言されている場所

Field.h

Prototype

Char *FldGetTextPtr (
const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

フィールドのテキスト文字列へのロックされたポインタを返します。フィールドが空の場合、NULL を返します。

コメント

この関数によって返されるポインタは、ユーザがこのポインタを取得した後に編集すると、無効になる可能性があります。

ポインタの内容を編集してはいけません。テキストがフィールドによって使用されている間にそのテキストを変更すると、テキストの長さ、割り当てサイズ、各行が保持するテキスト関連の情報を指定しているフィールドの内部構造体は同期（訳者注: 原文は sync）から外されてしまいます。この問題を避けるために、FldGetTextHandle() に書かれている指示に従ってください。

WARNING!
この関数で返されるポインタは、フィールドに異なるポインタを指定するまでは、フィールドによって「所有」されています。このポインタを将来使用するために保存しておくべきではありません。なぜなら、フィールドは文字列のサイズを変更することができ、それにより、ポインタが無効になる可能性があるからです。

参照

FldSetTextPtr(), FldGetTextHandle()

FldGetVisibleLines 関数 ^TOP^

目的

フィールドの可視領域内に表示することができる行数を返します。フィールドに保存されているテキストとは無関係です。

宣言されている場所

Field.h

Prototype

UInt16 FldGetVisibleLines (
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

フィールドが表示する行数を返します。（この値は、FieldType 構造体の中の lines 配列のサイズです。）

参照

FldGetNumberOfBlankLines(), FldCalcFieldHeight()

FldGrabFocus 関数 ^TOP^

目的

（指定されたフィールドが可視であれば）挿入ポイントを表示させ、点滅する挿入ポイントをフィールドの中に位置させます。

宣言されている場所

Field.h

Prototype

void FldGrabFocus (

  FieldType *fldP

)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

この関数を直接呼び出すことはほとんどありません。代わりに、FldGrabFocus を呼び出す FrmSetFocus() を使用してください。

直接 FldGrabFocus を呼び出す必要がある 1 つのケースは、テーブル セルを保持しているフィールドにプログラム的にフォーカスをセットする場合です。

この関数は、フィールド属性 hasFocus を true にセットします。（FieldAttrType を参照してください。）

参照

FrmSetFocus(), FldReleaseFocus()

FldHandleEvent 関数 ^TOP^

目的

フィールドに影響を与えるイベント（keyDownEvent, penDownEvent それに fldEnterEvent を含む）をハンドルします。

宣言されている場所

Field.h

Prototype

Boolean FldHandleEvent (
	FieldType *fldP,
	EventType *eventP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → eventP
    • イベント（EventType データ 構造体）へのポインタ

返り値

イベントがハンドルされた場合、true を返します。

コメント

編集可能なテキスト フィールド内で keyDownEvent が起こると、キーが表示可能な文字であればそのキーが現れ、キーが「移動」文字であれば挿入ポイントを操作します。

penDownEvent が起こると、フィールドは fldEnterEvent をイベント キューに送ります。

fldEnterEvent が起こると、フィールドはフォーカスを取得します。ユーザが同じ場所で 2 回タップした場合、その場所の単語が選択されます。ユーザが 3 回タップした場合、その場所の行全体が選択されます。そうでない場合、指定された場所に挿入ポイントが置かれます。

menuCmdBarOpenEvent が起こると、フィールドはコマンド ツールバーに貼付、コピー、切取、取消ボタンを追加します。これらのボタンは、現在の状況で意味を持つ場合ににのみ、追加されます。つまり、フィールドが編集可能である場合にのみ切取ボタンが追加され、クリップボードにテキストがあり、かつ、フィールドが編集可能である場合にのみ貼付ボタンが追加され、取り消すことのできるアクションがある場合にのみ取消ボタンが追加されます。

イベントがフィールドの内容を変更する場合、この関数はフィールドを視覚的に更新します。

この関数は、フィールドが編集可能でも使用可能でもない場合、一切のイベントをハンドルしません。

互換性

単語を選択するダブル-タップと行を選択するトリプル-タップは、3.5 New Feature Set が存在する場合にのみ、サポートされます。

3.5 New Feature Set が存在する場合、FldHandleEvent は menuCmdBarOpenEvent のみをハンドルします。

FldInsert 関数 ^TOP^

目的

現在の選択がもしあれば、そこに指定された文字列を挿入し、フィールドを再描画します。

宣言されている場所

Field.h

Prototype

Boolean FldInsert (
	FieldType *fldP,
	const Char *insertChars,
	UInt16 insertLen
)

パラメータ

  • → fldP
    • 挿入先となるフィールド オブジェクト（FieldType 構造体）へのポインタ
  • → insertChars
    • 挿入されるテキスト文字列
  • → insertLen
    • 挿入されるテキスト文字列のバイト長。終端の null 文字はカウントしません。

返り値

文字列の挿入に成功すれば true を返します。以下の条件で false を返します。

  • insertLen パラメータが 0
  • フィールドが編集可能ではない
  • 追加される文字列の長さがフィールドのサイズ制限（maxChars 値）を超える
  • フィールドに対しさらにメモリを割り当てする必要があるが、割り当てに失敗した

コメント

現在の選択が無い場合、渡された文字列は挿入ポイントがある場所に挿入されます。

この関数はフィールドの Dirty 属性をセットし、fldChangedEvent をイベント キューに送ります。この関数を繰り返し呼び出すと、イベント キューは fldCHangedEvent で溢れる（訳者注: オーバーフローする）かもしれません。代わりとなる方法は、フィールドからテキスト ハンドルを削除し、テキストを変更し、それからフィールドのハンドルを再度セットすることです。コードの例については、FldGetTextHandle() を参照してください。

参照

FldPaste(), FldDelete(), FldCut(), FldCopy()

FldMakeFullyVisible 関数 ^TOP^

目的

動的にリサイズ可能なフィールドに対して、フィールドのテキストをすべて可視にするためにフィールドの高さを拡張させるためのイベントを生成します。

宣言されている場所

Field.h

Prototype

Boolean FldMakeFullyVisible (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

テキスト全体が可視にはなっていなかったフィールドが動的にリサイズされると true を返します。そうでない場合、false を返します。

コメント

dynamicSize 属性（FieldAttrType を参照してください）が true であるフィールドに対してこの関数を使用してください。

この関数は実際にはフィールドをリサイズしません。その代わり、この関数は、フィールド全体を可視にするためにはフィールドをどれくらいの大きさにすべきか計算し、それからこの情報を fldHeightChangedEvent の中に収めてイベント キューに送ります。

NOTE
フィールドの行数がそのフィールドの最大行数属性の値以上である場合、イベントは生成されません。

テーブルに含まれるフィールドの場合、テーブルのコードが fldHeightChangedEvent をハンドルします。フィールドがフォームの上に直接置かれている場合、アプリケーション コードが fldHeightChangedEvent をハンドルすべきです。フォーム コードはそのイベントをハンドルしません。定数 maxFieldLines が、フィールドが標準フォントを使用する場合にフィールド拡張可能な最大行数を定義することに注意してください。

参照

TblHandleEvent()

FldNewField 関数 ^TOP^

目的

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

宣言されている場所

Field.h

Prototype

FieldType *FldNewField (
	void **formPP,
	UInt16 id,
	Coord x,
	Coord y,
	Coord width,
	Coord height,
	FontID font,
	UInt32 maxChars,
	Boolean editable,
	Boolean underlined,
	Boolean singleLine,
	Boolean dynamicSize,
	JustificationType justification,
	Boolean autoShift,
	Boolean hasScrollBar,
	Boolean numeric
)

パラメータ

  • ←→ formPP
    • 新しいフィールドがインストールされるフォームへのポインタへのポインタ。この値はハンドルではありません。つまり、この関数が返った後では、古いポインタ値は必ずしも有効ではありません。この関数が返った後の関数呼び出しでは、常にこの関数で返される新しいフォーム ポインタ値を使用してください。
  • → id
    • 開発者によってしていされたフィールドの記号的な ID。慣例として、この ID はリソース ID と一致すべきです（義務ではありません）。
  • → x
    • フィールドが表示されるウィンドウから見た相対的な、フィールドの境界の左上端の水平座標。
  • → y
    • フィールドが表示されるウィンドウから見た相対的な、フィールドの境界の左上端の垂直座標。
  • → width
    • フィールドの幅をピクセル表記で
  • → height
    • フィールドの高さをピクセル表記で
  • → font
    • フィールドのテキストを描くのに使用するフォント
  • → maxChars
    • この関数が作成するフィールドによって保持される最大バイト数
  • → editable
    • ユーザがテキストを編集することができるフィールドを作成する場合 true を渡してください。編集不可にする場合 false を渡してください。
  • → underlined
    • 下線無しなら noUnderline を渡してください。フィールドが表示するテキストに下線をひく場合 grayUnderline を渡してください。Palm OS バージョン 3.1 以降では、破線の代わりに実線の下線を使用する場合 solidUnderline を渡してください。
  • → singleLine
    • テキストのために単一の行のみを持つことができるフィールドを作成する場合、true を渡してください。
  • → dynamicSize
    • 表示されるテキストの量に合わせて動的にリサイズするフィールドを作成する場合、true を渡してください。
  • → justification
    • 左行揃えまたは右行揃えするかに合わせて、leftAlign または rightAlign のどちらかを渡してください。centerAlign 値はサポートされません。
  • → autoShift
    • Palm OS 2.0 （以降）の自動シフト ルールを指定する場合、true を渡してください。
  • → hasScrollBar
    • この関数が作成するフィールドにスクロール バー コントロールを付加する場合、true を渡してください。
  • → numeric
    • 0 から 9 までの文字のみを受け付けるフィールドを作成する場合、true を渡してください。

返り値

新しいフィールド オブジェクトへのポインタを返します。フィールドを作成するのに十分なメモリが無かった場合、NULL を返します。メモリ不足はメモリの断片化によって引き起こされる可能性があります。

互換性

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

参照

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

FldPaste 関数 ^TOP^

目的

フィールドの中の現在の選択、がもしあれば、をテキスト クリップボードの内容に置き換えます。

宣言されている場所

Field.h

Prototype

void FldPaste (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

この関数は以下のことを行います。

  • 挿入ポイントが可視になるように、必要があれば、フィールドをスクロールさせます。
  • 現在の選択が無い場合、挿入ポイントの位置にクリップボード テキストを挿入します。
  • 挿入ポイントを、挿入された最後の文字の後に、置きます。
  • クリップボードにテキストが無い場合、現在の選択を削除しません。

参照

FldInsert(), FldDelete(), FldCut(), FldCopy() FldUndo()

FldRecalculateField 関数 ^TOP^

目的

各可視行に対する「各行が保持するテキスト関連の情報」を保持している構造体を更新します。

宣言されている場所

Field.h

Prototype

void FldRecalculateField (
	FieldType *fldP,
	Boolean redraw
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → redraw
    • true の場合、フィールドを再描画します。

返り値

返り値はありません。

コメント

この関数は、表示される行の情報を保持するためのメモリ ブロックがまだ存在して場合、その場合にのみ、そのブロックを割り当てます。

フィールド幅またはフィールドのテキスト長を変更したときに、この関数を呼び出すべきです。フォントまたはフィールドの高さを変更した後には、この関数を呼び出さないでください。

FldSetTextHandle(), FldInsert() それに FldDelete() を含むフィールド関数の多くは、各行が保持するテキスト関連の情報を再計算するということに注意してください。

互換性

Palm OS 4.0 よりも前のリリースでは、各行が保持するテキスト関連の情報は、redraw パラメータが true にセットされている場合にのみ、更新されます。
Palm OS 4.0 では、単語を保持している情報は、FldRecalculateField が呼び出されればいつでも、redraw パラメータに関係なく、更新されます。

FldReleaseFocus 関数 ^TOP^

目的

フィールドが可視で現在のフォーカスを持っている場合は、点滅する挿入ポイントの表示を消し、Graffiti または Graffiti 2 の状態をリセットし、取消（undo）の状態をリセットします。

宣言されている場所

Field.h

Prototype

void FldReleaseFocus (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

この関数は、フィールド属性 hasFocus を false にセットします。（FieldAttrType を参照してください。）

通常、この関数を呼び出す必要はありません。カスタム描画関数を持たないフォームまたはテーブルにあるフィールドの場合、フォーカスが他のコントロールに移るときに、フィールド コードがフォーカスを解放します。カスタム描画関数を使用するテーブル、または、ガゼットなどの上記以外の型のオブジェクトにあるフィールドの場合、フォーカスがフィールドから去るときに、FldReleaseFocus を呼び出す必要があります。

参照

FldGrabFocus()

FldScrollable 関数 ^TOP^

目的

フィールドが指定された方向にスクロール可能ならば true を返します。

宣言されている場所

Field.h

Prototype

Boolean FldScrollable (
	const FieldType *fldP,
	WinDirectionType direction
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → direction
    • テストする方向。WinDirectionType（訳者注: 原文では DirectionType だが誤りと思われる）は Window.h で定義されています。それは定数 winUp と winDown（訳者注: 原文では up と down となっていたが誤りと思われる）を定義している列挙体です。

返り値

フィールドが指定された方向にスクロール可能なら true を返します。そうでない場合、false を返します。

参照

FldScrollField()

FldScrollField 関数 ^TOP^

目的

指定された行数分だけフィールドを上または下へスクロールさせます。

宣言されている場所

Field.h

Prototype

void FldScrollField (
	FieldType *fldP,
	UInt16 linesToScroll,
	WinDirectionType direction
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → linesToScroll
    • スクロールする行数
  • → direction
    • スクロールする方向。WinDirectionType（訳者注: 原文では DirectionType だが誤りと思われる）は Window.h で定義されています。それは定数 winUp と winDown を定義している列挙体です。

返り値

返り値はありません。

コメント

この関数は、水平に、つまり、右または左にスクロールすることはできません。

フィールド オブジェクトは、スクロールされると、再描画されます。しかし、スクロールバーは更新されません。スクロールバーを更新するために SclSetScrollBar() を使用してください。以下に例を挙げます。

FldScrollField (fldP, linesToScroll,
direction); 

// Update the scroll bar. 
SclGetScrollBar (bar, &value, &min, &max,
  &pageSize);

if (direction == winUp)
  value -= linesToScroll;
else
  value += linesToScroll;

SclSetScrollBar (bar, value, min, max,
  pageSize);

フィールドが指定された方向にスクロールできない場合、この関数は何もせずに返ります。この関数を呼び出す前にフィールドがスクロールできるかどうか調べるために、FldScrollable() を使用することができます。

参照

FldScrollable(), FldSetScrollPosition()

FldSendChangeNotificaton 関数 ^TOP^

目的

イベント キューに fldChangedEvent を送ります。

宣言されている場所

Field.h

Prototype

void FldSendChangeNotification(
	const FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

コメント

この関数はフィールド コードによって内部的に使用されます。通常、アプリケーション コードの中でこの関数を呼び出すことはありません。

FldSendHeightChangeNotificaton 関数 ^TOP^

目的

イベント キューに fldHeightChangedEvent を送ります。

宣言されている場所

Field.h

Prototype

void FldSendHeightChangeNotification(
	const FieldType *fldP,
	UInt16 pos,
	Int16 numLines
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → pos
    • 挿入ポイントの文字の位置
  • → numLines
    • フィールドの中の新しい行数

返り値

返り値はありません。

コメント

この関数はフィールド コードによって内部的に使用されます。通常、アプリケーション コードがこの関数を呼び出すことはありません。

FldSetAttributes 関数 ^TOP^

目的

フィールドの属性をセットします。

宣言されている場所

Field.h

Prototype

void FldSetAttributes (
	FieldType *fldP,
	const FieldAttrType *attrP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → attrP
    • 属性へのポインタ

返り値

返り値はありません。

コメント

この関数は、新しい属性値が影響を与えるようにするために、何もしません。例えば、下線属性の値を変更するためにこの関数を使用した場合、FldDrawField() を呼び出すまでは変更の影響は現れません。

通常、実行中にフィールド属性を変更する必要はありませんので、この関数を呼び出す必要はほとんどありません。

WARNING!
「内部使用のみ」と注意書きされている属性を変更するために、この関数を呼び出してはいけません。

FldSetAttributes の効果的な使い方は以下のようなものです。

  1. 属性を取得するために FldGetAttributes を呼び出す。
  2. 変更したいフラグをセットする。
  3. 変更を行うために FldSetAttributes を呼び出す。
WARNING!
FldGetAttributes とFldSetAttributes 呼び出しの間に他のいかなるフィールド ルーチンも呼び出してはいけません。そのようなことをすると、その属性は同期（sync）から外され、その結果を予想することはできません。

参照

FldGetAttributes(), FieldAttrType

FldSetBounds 関数 ^TOP^

目的

フィールドの位置またはサイズを変更します。

宣言されている場所

Field.h

Prototype

void FldSetBounds (
	FieldType *fldP,
	const RectangleType *rP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → rP
    • 表示に関する新しい領域を保持する RectangleType 構造体へのポインタ

返り値

返り値はありません。各行が保持するテキスト関連の情報を保持しているメモリブロックをリサイズする必要があり、それに必要な空き容量が十分でない場合、致命的なエラー メッセージを表示するかもしれません。

コメント

フィールドが可視の場合、フィールドは新しい領域で再描画されます。

NOTE
フィールドの高さまたは位置を、フィールドが可視の間に、変更することができます。しかし、幅を変更することはできません。

可視行の数が変更される場合、各行が保持するテキスト関連の情報（LineInfoType を参照してください）を保持しているメモリ ブロックはリサイズされます。この関数が呼び出されるとき、挿入ポイントは off であると仮定されています。

rect（訳者注: 指定される RectangleType 構造体のことだと思われる）の高さが少なくとも現在のフォントを 1 行表示するのに必要な高さ（FntLineHeight()|Palm OS Programmer's API Reference/37 を呼び出すことでこの値を決定できます）であることを確認してください。その高さより低いと、結果を予測できません。

参照

FldGetBounds(), FrmSetObjectBounds()

FldSetDirty 関数 ^TOP~

目的

フィールドが変更されたかどうかをセットします。

宣言されている場所

Field.h

Prototype

void FldSetDirty (
	FieldType *fldP,
	Boolean dirty
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → dirty
    • テキストが変更されたことにする場合 true

返り値

返り値はありません。

コメント

通常、Dirty 属性をクリアしたい場合に、この関数を呼び出します。Dirty 属性は、ユーザがフィールドの中のテキストに入力または削除したときに、セットされます。ある特定のフィールド関数（FldInsert() と FldDelete() など）によってもセットされます。

参照

FldDirty()

FldSetFont 関数 ^TOP^

目的

フィールドによって使用されるフォントをセットし、各行が保持するテキスト関連の情報を更新し、フィールドが可視の場合はフィールドを再描画（訳者注: 原文では draw だが redraw の方が適当と思われる）します。

宣言されている場所

Field.h

Prototype

void FldSetFont (
	FieldType *fldP,
	FontID fontID
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → fontID
    • 新しいフォントの ID

返り値

返り値はありません。

参照

FldGetFont(), FieldAttrType

FldSetInsertionPoint 関数 ^TOP^

目的

指定された文字列位置に基づいて、挿入ポイントの位置をセットします。

宣言されている場所

Field.h

Prototype

void FldSetInsertionPoint (
	FieldType *fldP,
	UInt16 pos
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → pos
    • 挿入ポイントの新しい位置。フィールドのテキスト（訳者補足: の開始点から）の有効なバイト オフセットとして与えられます。マルチ-バイト文字をサポートするシステムでは、この位置が文字間の境目を指していることを保証する必要があります（マルチ-バイト文字の中間または終端バイトを指していてはいけません）。

返り値

返り値はありません。

コメント

このルーチンは、FldSetInsPtPosition() とは異なり、挿入ポイントを可視にしません。FldSetInsertionPoint はまた、フィールドがフォーカスされていない場合、入力のための現在のフォーカスをフィールドにセットしません。

pos がフィールドの中のテキストの終端を越えた場所を指す場合、挿入ポイントはフィールドのテキストの終端にセットされます。

互換性

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

参照

TxtCharBounds()|Palm OS Programmer's API Reference/55

FldSetInsPtPosition 関数 ^TOP^

目的

指定された文字列位置に基づいて、挿入ポイントの位置をセットします。

宣言されている場所

Field.h

Prototype

void FldSetInsPtPosition (
	FieldType *fldP,
	UInt16 pos
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → pos
    • 挿入ポイントの新しい位置。フィールドのテキスト（訳者補足: の開始点から）の有効なバイト オフセットとして与えられます。マルチ-バイト文字をサポートするシステムでは、この位置が文字間の境目を指していることを保証する必要があります（マルチ-バイト文字の中間または終端バイトを指していてはいけません）。

返り値

返り値はありません。

コメント

pos がテキストの可視範囲を越えた場所を指す場合、挿入ポイントが可視になるまでフィールドをスクロールさせます

参照

FldGetInsPtPosition(), TxtCharBounds()|Palm OS Programmer's API Reference/55

FldSetMaxChars 関数 ^TOP^

目的

フィールドが受け付ける最大バイト数（maxChars 値）をセットします。

宣言されている場所

Field.h

Prototype

void FldSetMaxChars (

  FieldType *fldP,
  UInt16 maxChars

)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → maxChars
    • ユーザが入力するかもしれない文字の最大バイト数。maxFieldTextLen までのいずれかの値を指定します。

返り値

返り値はありません。

コメント

文字列の長さを決定するとき、折り返し文字（改行文字）はカウントされます。

参照

FldGetMaxChars()

FldSetMaxVisibleLines 関数 ^TOP^

目的

フィールドに提供されているスペースよりも多くのテキスト行がある場合、テーブルまたはフィールドがドラッグ-選択されている間に、それらの高さを 121 ピクセルよりも低い高さにすることを許可します。

宣言されている場所

Field.h

Prototype

void FldSetMaxVisibleLines (
	FieldType *fldP,
	UInt8 maxLines
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → maxLines
    • フィールドが視覚的に高くなることのできる最大行数

返り値

返り値はありません。

コメント

フィールドを動的に拡張することができます。拡張するとき、フィールド パッケージは表示されるべき最大行数を知る必要があります。それにより、フィールド パッケージはフィールドがそれよりも大きくなることを防ぐことができます。フィールドの拡張は、実際にはフィールドを保持しているオブジェクト -- テーブルまたはフォーム -- によってハンドルされるため、この関数の主な目的はフィールドを保持しているオブジェクトにどれくらいの大きさまでフィールドを大きくさせることができるのかを知らせることです。

この関数を呼び出さない場合、フィールドは少なくとも 121 ピクセルの高さになると予想され、その高さになるまでフィールドは繰り返し高くなろうとします。

FldSetScrollPosition 関数 ^TOP^

目的

指定されたオフセットにある文字が最初の可視行の最初の文字になるまで、フィールドをスクロールします。必要があればフィールドを再描画します。

宣言されている場所

Field.h

Prototype

void FldSetScrollPosition (
	FieldType *fldP,
	UInt16 pos
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → pos
    • フィールドのテキスト文字列の可視にされる最初の文字へのバイト オフセット。マルチ-バイト文字をサポートするシステムでは、この値が文字間の境界を指していることを保証する必要があります（マルチ-バイト文字の中間または終端バイトを指してはいけません）。

返り値

返り値はありません。

コメント

この関数はフィールドをスクロールしますが、フィールドのスクロールバーを更新しません。この関数の呼出し後にスクロールバーを更新すべきです。そうするには、まず使用する値を決定するために FldGetScrollValues() を呼び出し、それから SclSetScrollBar() を呼び出します。

参照

FldGetScrollPosition(), FldScrollField(), TxtCharBounds()|Palm OS Programmer's API Reference/55

FldSetSelection 関数 ^TOP^

目的

フィールドの中に現在の選択をセットし、フィールドが可視の場合は選択をハイライトします。

宣言されている場所

Field.h

Prototype

void FldSetSelection (
	FieldType *fldP,
	UInt16 startPosition,
	UInt16 endPosition
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → startPosition
    • ハイライトする文字範囲の開始オフセット。フィールドのテキスト（訳者補足: の開始点から）のバイト オフセットとして与えられます。
  • → endPosition
    • ハイライトする文字範囲の終了オフセット。終了オフセットは開始オフセット以上であるべきです。マルチ-バイト文字をサポートするシステムでは、この位置は文字間の境界でなければなりません。つまり、マルチ-バイト文字の中間バイトを指してはいけません。

返り値

返り値はありません。

コメント

選択をキャンセルするには、startPosition と endPosition を同じ値にセットしてください。startPosition と endPosition が等しい場合、現在の選択はハイライトされなくなります。

startPosition と endPosition のいずれかがマルチ-バイト文字の中間バイトを指す場合、FldSetSelection は、オフセットが文字間の境界（つまり、マルチ-バイト文字の開始文字）を指すようになるまで、オフセットを文字列の開始点に向けて移動させようと試みます。

参照

TxtCharBounds()|Palm OS Programmer's API Reference/55

FldSetText 関数 ^TOP^

目的

フィールドのテキスト値をセットします。表示の更新は行いません。

宣言されている場所

Field.h

Prototype

void FldSetText (
	FieldType *fldP,
	MemHandle textHandle,
	UInt16 offset,
	UInt16 size
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → textHandle
    • null で終了するテキスト文字列を保持しているブロックのロックが解除されているハンドル。フィールドとフィールドが現在表示している文字列の関連付けを削除するには、このパラメータに NULL を渡します。そうすることで、フォームが削除されるときその文字列は解放されません。
  • → offset
    • ブロックの開始点からテキスト文字列の開始点までのオフセット
  • → size
    • テキスト文字列に割り当てられたサイズ。この値は文字列の長さではありません。それに、テキストに空の文字列をセットしていない場合にこの値を 0 にセットすべきではありません。

返り値

返り値はありません。

コメント

この関数は、アプリケーションがメモリの適所で編集を実行することを許可します。フィールドがデータベース レコードの文字列を指すようにするためにこの関数を使用でき、それによりフィールド ルーチンを使ってその文字列を直接編集できます。

文字がフィールドのテキストに追加されるのに合わせて、テキストを保持するブロックは大きくなります。ブロックは一度に数バイト拡張されるため、文字が追加されるたびに拡張される必要はありません; この拡張は、結果として、テキスト ブロックに中の使用されない容量を作り出すことになるかもしれません。文字がフィールドのテキストから削除されるのに合わせて、その容量は自動的に解放されるわけではありません。データ レコードの編集時の文字の追加または削除は、結果として、フィールドのテキスト ブロックの最後に使用されない容量を作り出すかもしれないため、アプリケーションは、フィールドのロックが解除される前に使用されない容量をすべて解放するために、FldCompactText() を呼び出すべきです。

この関数に渡されるハンドルは、メモリ チャンクの中の offset バイト目から始まる null で終了する文字列を保持していると仮定されます。開始点は 0 から size-1 バイトであるべきです。フィールドはメモリ チャンクまたは文字列データのコピーを作成しません; その代わり、フィールドはレコードへのハンドルをフィールドの構造体の中に保存します。

WARNING!
この関数をフォーム上にある 2 つのフィールドをセットするために使用することはできません。そのようなことをするとそれらのフィールドは 1 つの文字列値を共有することになります。つまり、例えば個人名を保持している 1 つの文字列があったとして、その文字列を使って姓のフィールドと名のフィールドをセットアップするために 2 度 FldSetText を呼び出すことはできないということです。（異なるオフセットであっても。）

FldSetText は各行が保持するテキスト関連の情報を更新し、最後の可視文字の後に挿入ポイントを起きますが、ディスプレイの更新は行いません。この関数の呼出し後、ディスプレイを更新するために FldDrawField() を呼び出す必要があります。

FldSetText は textHandle のロック カウントを +1 して、フィールドの以前のテキスト ハンドル（がもしあれば）のロック カウントを -1 します。

FldSetText（と FldSetTextHandle）はデータベース レコードを編集するために使用されるかもしれないため、フィールドの以前のテキスト ハンドルに関連付けられているメモリを解放しません。以前のテキスト ハンドルがダイナミック ヒープ上の文字列を指していて、それを解放したいのなら、FldSetText を使用する前にハンドルを取得するために FldGetTextHandle() を使用し、それから FldSetText 使用後にそのハンドルを解放してください。（コード例については、FldSetTextHandle() を参照してください。）

フィールドがデータベース レコードを指す場合、そのテキスト ハンドルに関連付けられたメモリを解析したいと思うことがあります。しかしながら、このメモリとフィールドに関連付けられた他のすべてのメモリは、フィールド自身が解放されるとき（フォームがクローズされるときに起こります）に、解放されます。テキスト ハンドルに関連付けられたメモリを解放させたくないのなら、フォームがクローズされる前に FldSetText を使ってテキスト ハンドルに NULL を渡してください。NULL を渡すことによって、フィールドと維持したいテキスト ハンドルの関連付けが削除されます。FldSetText の呼び出しの結果としてテキスト ハンドルのロックは解除され、フィールドが解放されるときにフィールドと一緒に解放されるテキスト ハンドルは存在しなくなります。

参照

FldSetTextPtr(), FldSetTextHandle()

FldSetTextAllocatedSize 関数 ^TOP^

目的

フィールドのテキスト文字列を保持するために割り当てられるバイト数をセットします。このバイト数と実際にフィールドに表示されるテキスト文字列の長さを混同しないでください。

宣言されている場所

Field.h

Prototype

void FldSetTextAllocatedSize (
	FieldType *fldP,
	UInt16 allocatedSize
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → allocatedSize
    • テキストのために割り当てられるバイト数

返り値

返り値はありません。

コメント

この関数は普段使用されることはありません。この関数はテキスト文字列のために割り当てられたフィールドのメモリをリサイズしません。この関数は単に FieldType 構造体の textBlockSize フィールドをセットするだけです。このフィールドの値はフィールドによって内部的に計算され、維持されるため、FldSetTextAllocatedSize を直接呼び出す必要はありません。

参照

FldGetTextAllocatedSize(), FldCompactText()

FldSetTextHandle 関数 ^TOP^

目的

フィールドのテキスト値を指定されたハンドルに関連付けされた文字列にセットします。ディスプレイの更新は行いません。

宣言されている場所

Field.h

Prototype

void FldSetTextHandle (
	FieldType *fldP,
	MemHandle textHandle
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → textHandle
    • フィールドのテキスト文字列のロックを解除されたハンドル。フィールドとフィールドが現在表示している文字列の関連付けを削除するには、このパラメータに NULL を渡してください。それにより、フォームが削除されるときに、その文字列はフィールドと一緒に解放されなくなります。

返り値

返り値はありません。

コメント

この関数は、文字列のための textHandle によって指されるメモリ チャンク全体を扱う点が FldSetText() と異なります。実際、この関数は、オフセットを 0、サイズをメモリ チャンク全体の長さとして FldSetText を呼び出しているだけです。データベース レコード全体が文字列を保持する場合に、フィールドでレコードの中の文字列を編集するためにこの関数を使用します。また、フィールドでダイナミック ヒープの中の文字列を編集するためにこの関数を使用します。

文字がフィールドのテキストに追加されるのに合わせて、テキストを保持するブロックは大きくなります。ブロックは一度に数バイト拡張されるため、文字が追加されるたびに拡張される必要はありません; この拡張は、結果として、テキスト ブロックに中の使用されない容量を作り出すことになるかもしれません。文字がフィールドのテキストから削除されるのに合わせて、その容量は自動的に解放されるわけではありません。データ レコードの編集時の文字の追加または削除は、結果として、フィールドのテキスト ブロックの最後に使用されない容量を作り出すかもしれないため、アプリケーションは、フィールドのロックが解除される前に使用されない容量をすべて解放するために、FldCompactText() を呼び出すべきです。

FldSetTextHandle は各行が保持するテキスト関連の情報を更新し、最後の可視文字の後に挿入ポイントを起きますが、ディスプレイの更新は行いません。この関数の呼出し後、ディスプレイを更新するために FldDrawField() を呼び出す必要があります。

FldSetTextHandle は textHandle のロック カウントを +1 して、フィールドの以前のテキスト ハンドル（がもしあれば）のロック カウントを -1 します。

FldSetTextHandle（と FldSetText）はデータベース レコードを編集するために使用されるかもしれないため、フィールドの以前のテキスト ハンドルに関連付けられているメモリを解放しません。以前のテキスト ハンドルがダイナミック ヒープ上の文字列を指していて、それを解放したいのなら、FldSetText を使用する前にハンドルを取得するために FldGetTextHandle() を使用し、それから FldSetText 使用後にそのハンドルを解放してください。以下に例を挙げます。

/* get the old text handle */ 
oldTxtH = FldGetTextHandle(fldP);
 
/* change the text and update the display */
FldSetTextHandle(fldP, txtH);
FldDrawField(fldP);
 
/* free the old text handle */
if (oldTxtH != NULL) 
  MemHandleFree(oldTxtH);

フィールドがデータベース レコードを指す場合、そのテキスト ハンドルに関連付けられたメモリを解析したいと思うことがあります。しかしながら、このメモリとフィールドに関連付けられた他のすべてのメモリは、フィールド自身が解放されるとき（フォームがクローズされるときに起こります）に、解放されます。テキスト ハンドルに関連付けられたメモリを解放させたくないのなら、フォームがクローズされる前に FldSetText を使ってテキスト ハンドルに NULL を渡してください。NULL を渡すことによって、フィールドと維持したいテキスト ハンドルの関連付けが削除されます。FldSetText の呼び出しの結果としてテキスト ハンドルのロックは解除され、フィールドが解放されるときにフィールドと一緒に解放されるテキスト ハンドルは存在しなくなります。

参照

FldSetTextPtr(), FldSetText()

FldSetTextPtr 関数 ^TOP^

目的

編集不可のフィールドのテキストが指定されたテキスト文字列を指すようにセットします。

宣言されている場所

Field.h

Prototype

void FldSetTextPtr (
	FieldType *fldP,
	Char *textP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → textP
    • null で終了する文字列へのポインタ

返り値

返り値はありません。編集可能なテキスト フィールドが渡された場合、エラー メッセージを表示するかもしれません。

コメント

編集可能なテキスト フィールドに対して FldSetTextPtr を呼び出さないでください。代わりに、編集可能なテキスト フィールドに対して FldSetTextHandle() を呼び出してください。FldSetTextPtr はユーザ インターフェイスの中の編集不可のテキストを表示することを意図しています。

フィールドが 1 行よりも多い行を持つ場合、各行が保持するテキスト関連の情報を再計算するために FldRecalculateField() を使用してください。

この関数はフィールドを視覚的に更新しません。そうするには FldDrawField() を使用してください。

フィールドはこの関数に渡された文字列を解放することは、フィールド自身が解放される場合であっても、ありません。アプリケーション コード自身がその文字列を解放しなくてはなりません。文字列を解放する前に、フィールドがもはやその文字列を表示していないことを確認してください。この関数に渡した文字列を解放する前に、フィールドの文字列ポインタを他の文字列にセットするか、FldSetTextPtr(fldP, NULL) を呼び出してください。

互換性

Palm OS 4.0 より前のバージョンでは、textP パラメータに NULL を渡すことはできません: この関数は NULL ポインタに対して StrLen() を呼び出し、結果としてクラッシュします。

参照

FldSetTextHandle(), FldGetTextPtr()

FldSetUsable 関数 ^TOP^

目的

フィールドを使用可能または使用不可にセットします。

宣言されている場所

Field.h

Prototype

void FldSetUsable (
	FieldType *fldP,
	Boolean usable
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ
  • → usable
    • 使用可能にするには true、使用不可にするには false

返り値

返り値はありません。

コメント

使用不可のフィールドは表示されず、入力を受け付けません。

この関数を使用する代わりに、FrmHideObject() と FrmShowObject() を使用することもあります。

参照

FldEraseField(), FldDrawField(), {[goto FieldAttrType,FieldAttrType}}

FldUndo 関数 ^TOP^

目的

フィールド オブジェクトに対して行われた最後の変更（がもしあれば）を取り消します。
変更には、文字入力、バックスペース、削除、貼付、それに切取が含まれます。

宣言されている場所

Field.h

Prototype

void FldUndo (
	FieldType *fldP
)

パラメータ

  • → fldP
    • フィールド オブジェクト（FieldType 構造体）へのポインタ

返り値

返り値はありません。

参照

FldPaste(), FldCut(), FldDelete(), FldInsert()

FldWordWrap 関数 ^TOP^

目的

文字列と幅を与えられ、現在のフォントを使用して表示することのできる文字のバイト数を返します。

宣言されている場所

Field.h

Prototype

UInt16 FldWordWrap (
	const Char *chars,
	Int16 maxWidth
)

パラメータ

  • → chars
    • null で終了している文字列へのポインタ
  • → maxWidth
    • 行の最大幅をピクセルで

返り値

表示することのできる文字のバイト長を返します。

参照

FntWordWrap()|Palm OS Programmer's API Reference/37

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

Copyright (C) 2002-2006 PalmwareInfo
Powered by FreeStyleWiki3.6.2 with Perl5.032001

Index


メニュー

各種掲示板

検索

キーワード

Wiki

最新

2023/12/1

2021/4/5

2020/7/7

2020/5/15

2020/1/13

2019/4/1

2018/4/18

2018/4/17

Visitor:
[Today:]
[Yesterday:]