javax.microedition.lcdui
クラス TextField

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.TextField

public class TextField
extends Item

このクラスは Form に置くことができる編集可能なテキスト・コンポーネントです。 初期値として任意のテキストを設定することができます。

TextField には格納できる文字数の最大サイズが存在します。 最大サイズはオブジェクトに常に格納することができるキャラクタ数の最大値（キャパシティ）です。 TextField のオブジェクトを構築する際に設定した最大サイズは、内容を編集することができる TextField の場合、アプリケーションがメソッドを呼び出す場合だけではなく、ユーザーがテキストを変更する際にもこのリミットが適用されます。 最大サイズは、格納できるキャラクタ数の最大値であり、いかなる場合もディスプレイに表示できるキャラクタ数とは無関係です。 表示可能なキャラクタ数および表示方法はデバイスの表示能力およびカラム数と行数によって決定されます。

実装は最大サイズに上限を設けることがあり、アプリケーションが要求した最大サイズよりも小さな最大サイズが設定されることがあります。 実際に割り当てられた最大サイズは getMaxSize() メソッドによって取得することができます。 注意深く記述されたアプリケーションは、この値を要求した値と比較し、それらが異なるケースの処理を考慮すべきです。

TextField 内に含まれるテキストは、一度に表示することができる量よりも多いかもしれません。 その場合、実装はテキストのスクロールを行い、テキスト全体の編集および表示を行えるようにします。 スクロールはアプリケーションに対して透過的に行われます。

入力制約

TextField は、TextBox オブジェクトと入力制約の概念を共有しています。 個々の制約は、ユーザーや様々なメソッドで入力するテキストをアプリケーションが必要に応じて制限することを可能にします。 実装はアプリケーションによって要求されたようにユーザーの入力を制限することを求められます。 例えば、アプリケーションが TextField 上の NUMERIC 制約を要求している場合、実装は数字の入力のみを許可します。

実装は文字列オブジェクトの内容について、どのような意味的チェックも行いません。 アプリケーションは自身でその意味的チェックを行う処理を用意しなければなりません。

実装は入力された内容に特別なフォーマットを提供することがあります。 例えば PHONENUMBER フィールドを使用すると、電話番号規則にしたがって、国番号、市外局番、プレフィックスなどに、数字をグループ化して分離し、強調するかもしれません。 この際提供される、いかなるスペースおよび句読点も TextField の内容の一部とはみなしません。 例えば、PHONENUMBER 制約を指定された TextField は以下の様に表示するかもしれません。

     (408) 555-1212

しかし、アプリケーションに見える TextField の内容は「4085551212」のような一般的な電話番号を表す文字列となります。 いくつかの電話網では、先頭に「+」がつく電話番号を返す可能性があることに注意しなければなりません。

ANY

public static final int ANY

ユーザーは制限なくテキストを入力できることを示す定数（=0）です。

関連項目:

定数フィールド値

EMAILADDR

public static final int EMAILADDR

ユーザーによる電子メールアドレスの入力を受け付けることを示す定数（=1）です。

関連項目:

定数フィールド値

NUMERIC

public static final int NUMERIC

ユーザーによる正数値の入力を受け付けることを示す定数（=2）です。 実装は数字からなる文字列にオプションのマイナス文字が付加される可能性を考慮しなければなりません。

関連項目:

定数フィールド値

PHONENUMBER

public static final int PHONENUMBER

ユーザーによる電話番号の入力を受け付けることを示す定数（=3）です。 これは特殊なケースですが、電話ベースの実装ではネイティブの電話アプリケーションを使用し、電話番号を受け取ることができます。 実装は押している単一のキーが、電話をかけるのに十分な電話番号を返すダイヤラを自動的に起動することができるかもしれません。 なお、ユーザーの確認を得ることなく、自動的にダイヤルを開始してはなりません。 入力が許可されるキャラクタセットはデバイスおよびデバイスが接続されるネットワークに依存します。 また、そのキャラクタには数字以外の文字を含んでいる可能性があります。

関連項目:

定数フィールド値

URL

public static final int URL

ユーザーによる URL の入力を受け付けることを示す定数（=4）です。

関連項目:

定数フィールド値

PASSWORD

public static final int PASSWORD

タイプされた文字がディスプレイに表示されないように、入力されたテキストを隠して表示することを示す定数（=0x10000）です。 TextField に実際に入力できる内容には影響を与えません。 しかし、表示は「*」などに置き換えて行います。 マスク文字として使用される文字は実装に依存します。 PASSWORD は PIN（暗証番号）のような機密情報を入力するために使用します。

関連項目:

定数フィールド値

CONSTRAINT_MASK

public static final int CONSTRAINT_MASK

設定されている制約に対する修飾フラグを解除するためのマスク値を示す定数（=0xFFFF）です。 アプリケーションが PASSWORD のような修飾フラグを削除した値が必要な場合に、現在の制約設定を取得する getConstraints() メソッドが返す値に対して、この定数で論理積（AND 演算）を行います。

関連項目:

定数フィールド値

TextField

public TextField(String title,
                 String text,
                 int maxSize,
                 int constraints)

指定されたタイトル文字列、テキストの内容、最大文字数および入力制約を設定した新しい TextField オブジェクトを作成します。 text パラメータが null の場合、TextBox は「空」の状態で作成されます。 maxSize パラメータは 0 以上の値でなければなりません。

パラメータ:

title - ディスプレイに表示するタイトル文字列を渡します。

text - 編集エリアに設定するテキストの初期内容あるいは null を渡します。

maxSize - 最大キャラクタ数を渡します。

constraints - 入力制約を渡します。

例外:

IllegalArgumentException - maxSize が 0 未満の場合、constraints が不正な場合、text が入力制約に違反する場合および text の長さが最大サイズを超えている場合に throw します。

getString

public String getString()

TextField の内容を文字列として返します。

戻り値:

現在の内容を返します。

setString

public void setString(String text)

指定された新しい内容を TextField に設定します。 以前の内容は新しい内容と置き換えられます。

パラメータ:

text - 新しく設定する内容を渡します。

例外:

IllegalArgumentException - text が入力制約に違反する場合および text の長さが最大サイズを超えている場合に throw します。

getChars

public int getChars(char[] data)

指定された文字配列に TextField の内容をコピーします。 内容をコピーした配列以降の配列の内容は変更されません。

パラメータ:

data - 内容を受け取る文字配列を渡します。

戻り値:

コピーした文字数を返します。

例外:

ArrayIndexOutOfBoundsException - 内容の長さと比較してコピー先の文字配列の長さが短い場合に throw します。

NullPointerException - data に null が渡された場合に throw します。

setChars

public void setChars(char[] data,
                     int offset,
                     int length)

指定された文字配列の指定された位置から指定文字分を TextField に設定します。 以前の内容は新しい内容と置き換えられます。 data 配列内の offset が示す位置（1 文字目が 0）から length 文字数分の内容を設定します。 data が null の場合、TextBox は「空」の状態になります。

パラメータ:

data - 設定する元の文字配列あるいは null を渡します。

offset - 設定を開始する文字配列中の位置を渡します。

length - 設定する文字数を渡します。

例外:

ArrayIndexOutOfBoundsException - offset および length による範囲指定が data に対して不適切な場合に throw します。

IllegalArgumentException - data が入力制約に違反する場合および length の長さが最大サイズを超えている場合に throw します。

insert

public void insert(String src,
                   int position)

TextField の内容に文字列を挿入します。 文字列は、内容の１文字目を 0 とする位置を基準とするパラメータ position によって指定された位置に挿入されます。 以後のテキストは挿入した文字数分、後方へ移動します。 position が 0 あるいはそれ以下の場合、内容の前に指定された文字列を挿入します。 同様に position が内容の最後の位置あるいは最上の場合、内容の直後に指定された文字列を挿入、つまり追加します。

内容のサイズは挿入した文字数分増加します。 増加した結果のサイズは設定されている最大サイズ以下でなければなりません。

アプリケーションはタイピングしたように文字を挿入する場合、getCaretPosition() メソッドによって取得した位置を使用して挿入します。 例えば、text.insert(src, text.getCaretPosition()) と記述すると、現在の入力位置に文字列 src を挿入することができます。

パラメータ:

src - 挿入する文字列を渡します。

position - 文字列を挿入する内容の中の位置を渡します。

例外:

IllegalArgumentException - src が入力制約に違反する場合および挿入後の内容の長さが最大サイズを超えている場合に throw します。

insert

public void insert(char[] data,
                   int offset,
                   int length,
                   int position)

TextField の内容に文字配列の一部を挿入します。 offset と length パラメータは、挿入のために使用する文字配列内の開始位置と文字数を示します。 挿入自体の動作は insert(String, int) と同一です。

パラメータ:

data - 設定する元の文字配列を渡します。

offset - 設定を開始する文字配列中の位置を渡します。

length - 設定する文字数を渡します。

position - 文字列を挿入する内容の中の位置を渡します。

例外:

ArrayIndexOutOfBoundsException - offset および length による範囲指定が data に対して不適切な場合に throw します。

IllegalArgumentException - data が入力制約に違反する場合および挿入後の内容の長さが最大サイズを超えている場合に throw します。

delete

public void delete(int offset,
                   int length)

TextField の内容の指定された位置から指定された長さの文字を削除します。

パラメータ:

offset - 削除を開始する内容中の位置を渡します。

length - 削除する文字数を渡します。

例外:

StringIndexOutOfBoundsException - offset および length によって指定された範囲が TextField の内容の範囲外の場合に throw します。

IllegalArgumentException - data が入力制約に違反する場合に throw します。

getMaxSize

public int getMaxSize()

この TextField に格納することができる最大サイズ（文字数）を返します。

戻り値:

格納できる最大サイズを返します。

setMaxSize

public int setMaxSize(int maxSize)

この TextField に格納することができる最大サイズ（文字数）を設定します。 もし、現在の内容が maxSize よりも長い場合、内容は maxSize に切り詰められます。

パラメータ:

maxSize - 新しい最大サイズを渡します。

戻り値:

設定された最大サイズを返します。このサイズは要求したサイズよりも小さい可能性があります。

例外:

IllegalArgumentException - maxSize に 0 あるいはそれ以下の値を渡した場合に throw します。

size

public int size()

この TextField に現在格納されている内容の文字数を返します。

戻り値:

内容の文字数を返します。

getCaretPosition

public int getCaretPosition()

現在の入力位置を返します。 ユーザーインタフェースの種類によっては、この呼び出しによってしばらくの間ブロックすることがあります。 また、意図するキャレット位置をユーザーに問い合わせることがあります。 単純にキャレット記号を表示している位置を返すこともあります。

戻り値:

現在の入力位置を 0 を始点とする値で返します。

setConstraints

public void setConstraints(int constraints)

TextField に新たな入力制約を設定します。 TextField の現在の内容が新しい制約に一致しない場合、内容はクリアされます。

パラメータ:

constraints - 入力制約を渡します。

例外:

IllegalArgumentException - 指定した constraints が不適切な場合に throw します。

getConstraints

public int getConstraints()

TextField に設定されている現在の入力制約を返します。

戻り値:

現在設定されている入力制約を返します。