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

TextBox は TextField と同様の入力制約の概念を持っています。 TextBox クラス内のメソッドの制約パラメータは、TextField クラスの中で定義されている定数を使用します。 これらの定数の定義に関しては TextField クラスにおける入力制約の記述を参照してください。

TextBox

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

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

パラメータ:

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

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 します。

insert

public void insert(String src,
                   int position)

TextBox の内容に文字列を挿入します。 文字列は、内容の１文字目を 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)

TextBox の内容に文字配列の一部を挿入します。 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)

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

パラメータ:

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

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

例外:

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

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

getMaxSize

public int getMaxSize()

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

戻り値:

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

setMaxSize

public int setMaxSize(int maxSize)

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

パラメータ:

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

戻り値:

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

例外:

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

size

public int size()

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

戻り値:

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

getCaretPosition

public int getCaretPosition()

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

戻り値:

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

setConstraints

public void setConstraints(int constraints)

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

パラメータ:

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

例外:

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

getConstraints

public int getConstraints()

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

戻り値:

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