javax.microedition.lcdui
クラス TextBox

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Screen
          javax.microedition.lcdui.TextBox

public class TextBox
extends Screen

このクラスはユーザーがテキストを入力および編集することを可能にする Screen です。

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

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

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

入力制約が TextField.ANY に設定されているなら、テキストは改行を含むことができます。 テキストを表示する際にはそれに従って改行しなければなりません。そして、ユーザーは改行文字を入力できなければなりません。

TextBox は TextField と同様の入力制約の概念を持っています。 TextBox クラス内のメソッドの制約パラメータは、TextField クラスの中で定義されている定数を使用します。 これらの定数の定義に関しては TextField クラスにおける入力制約の記述を参照してください。 また、TextBox には、同じセクションで説明されいている実際の内容と表示される内容について、TextField と同じ考え方を共有しています。

TextBox には、TextField と同じ入力モードの概念があります。 その他の詳細に関しては TextField クラスにおける、入力モードの解説を参照してください。

導入されたバージョン:

MIDP 1.0

TextBox

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

指定したタイトル文字列、初期のテキスト内容、最大キャラクタ数および入力制約を持った新しい TextBox オブジェクトを作成します。 text パラメータが null ならば、TextBox は空の状態で作成します。 maxSize パラメータは 0 以上でなければなりません。 初期のテキスト内容文字列の長さが maxSize を超えているならば、IllegalArgumentException を throw します。 しかし、実装はアプリケーションが要求したよりも小さな最大サイズを割り当てることがあります。 これによって、内容の長さが新たに割り当てられた最大サイズを超えているのであれば、内容をこのサイズに合うように終端を切り取ります。この際例外は一切 throw しません。

パラメータ:

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

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

maxSize - 最大キャラクタ数を渡します。実装は最大サイズに上限を設けることがあり、アプリケーションが要求した最大サイズよりも小さな最大サイズが設定されることがあります。 実際に割り当てられた最大サイズは getMaxSize() メソッドによって取得することができます。 注意深く記述されたアプリケーションは、この値を要求した値と比較するでしょう。

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

例外:

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

getString

public String getString()

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

戻り値:

現在の内容を返します。

setString

public void setString(String text)

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

パラメータ:

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

例外:

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

getChars

public int getChars(char[] data)

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

パラメータ:

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

戻り値:

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

例外:

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

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

関連項目:

setChars(char[], int, int)

setChars

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

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

パラメータ:

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

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

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

例外:

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

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

関連項目:

getChars(char[])

insert

public void insert(String src,
                   int position)

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

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

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

パラメータ:

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

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

例外:

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

insert

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

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

offset と length パラメータは文字配列データ内の文字の有効範囲を示していなければなりません。 offset パラメータは 0 〜 (data.length) の範囲内でなければなりません。 length パラメータは常に正数でなければならず、(offset + length) <= data.length の範囲となります。

パラメータ:

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

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

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

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

例外:

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

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

NullPointerException - data が null の場合に throw します。

delete

public void delete(int offset,
                   int length)

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

offset と length パラメータは TextBox の内容文字列データ内の有効範囲を示していなければなりません。 offset パラメータは 0 〜 (size()) の範囲内でなければなりません。 length パラメータは常に正数でなければならず、(offset + length) <= size() の範囲となります。

パラメータ:

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

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

例外:

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

IllegalArgumentException - 結果として得られる内容が入力制約に違反する場合に throw します。

getMaxSize

public int getMaxSize()

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

戻り値:

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

関連項目:

setMaxSize(int)

setMaxSize

public int setMaxSize(int maxSize)

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

パラメータ:

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

戻り値:

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

例外:

IllegalArgumentException - maxSize に 0 あるいはそれ以下の値を渡した場合および内容をサイズに合わせて切り詰めた結果が入力制約に違反する場合に throw します。

関連項目:

getMaxSize()

size

public int size()

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

戻り値:

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

getCaretPosition

public int getCaretPosition()

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

戻り値:

現在の入力位置を１文字目が 0 となる位置で返します。

setConstraints

public void setConstraints(int constraints)

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

パラメータ:

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

例外:

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

関連項目:

getConstraints()

getConstraints

public int getConstraints()

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

戻り値:

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

関連項目:

setConstraints(int)

setInitialInputMode

public void setInitialInputMode(String characterSubset)

ユーザーがこの TextBox に対する編集を開始する際に使用すべき入力モードに関して実装に対するヒントを設定します。 characterSubset パラメータには初期入力モードを選択するために実装が使用すべき Unicode 文字のサブセットを指定します。 null が指定されたなら、実装はデフォルトの入力モードを選択します。

入力モードに関するさらに詳しい説明は入力モードを参照してください。

パラメータ:

characterSubset - Unicode 文字サブセットを意味する文字列あるいは null を渡します。

導入されたバージョン:

MIDP 2.0