javax.swing.text.MaskFormatter

すべての実装されたインタフェース:: Serializable, Cloneable

public class MaskFormatter extends DefaultFormatter

MaskFormatterは、文字列の書式設定および編集に使用されます。 MaskFormatterの動作はDocumentモデルの特定の位置にある有効な文字を指定するStringマスク経由で制御されます。次の文字を指定できます。

有効な文字とそれらの説明
文字	説明
#	任意の有効な数字。`Character.isDigit`を使用する。
'	エスケープ文字、特殊な形式の文字のエスケープに使用します。
U	任意の文字(`Character.isLetter`)。すべての小文字は大文字にマッピングされる。
L	任意の文字(`Character.isLetter`)。すべての大文字は小文字にマッピングされる。
A	任意の文字または数字(`Character.isLetter`または`Character.isDigit`)
?	任意の文字(`Character.isLetter`)。
*	すべての文字および数字。
H	任意の16進数文字(0-9、a-fまたはA-F)。

通常、文字は一つのcharに対応しますが、これは一部の言語では当てはまりません。マスクは文字ごとに異なり、必要な数のcharに対応できるように調整されます。

setInvalidCharactersとsetValidCharactersメソッドで入力可能な文字を詳細に限定できます。setInvalidCharactersではどの文字が不正かを指定できます。またsetValidCharactersではどの文字が有効かを指定できます。たとえば、次のコード・ブロックは無効または有効な文字を持たない「0xHHH」のマスクと等しくなります。

MaskFormatter formatter = new MaskFormatter("0x***");
formatter.setValidCharacters("0123456789abcdefABCDEF");

文字列の長さがマスクの長さより短い場合は、最初に値の書式を設定するとき、2つのことが発生する可能性があります。プレースホルダー文字列が使用されるか、またはプレースホルダー文字が使用されます。プレースホルダー文字列のほうが優先されます。たとえば:

  MaskFormatter formatter = new MaskFormatter("###-####");
  formatter.setPlaceholderCharacter('_');
  System.out.println(formatter.valueToString("123"));

結果は、文字列「123-____」になります。 setPlaceholder("555-1212")が呼び出された場合、結果は「123-1212」になります。プレースホルダー文字列は、初めて書式設定を行うときにのみ使用されます。2回目以降の書式設定時には、プレースホルダー文字だけが使用されます。

有効な文字だけを許可するようにMaskFormatterが構成されている場合(setAllowsInvalid(false))、リテラル文字列は編集時に必要に応じてスキップされます。 MaskFormatterのマスクが"###-####"で、現在の値が"555-1212"だとします。右矢印キーを使ってフィールドをナビゲートしていくと、次のような結果が得られます(|はキャレット位置)。

「-」は編集不可能なリテラル文字で、スキップされます。

編集時も同様の動作が得られます。前述の例のMaskFormatterに文字列'123-45'と'12345'を挿入してみます。どちらの場合も、結果は同じ文字列'123-45__'になります。 MaskFormatterが文字位置3 ('-')で挿入を行う場合、次の2つの処理が発生します。

挿入された文字が「-」の場合は受け付けられる。
挿入された文字が次の非リテラル文字のマスクに一致する場合、新しい位置で受け付けられる。
それ以外の文字が挿入されると、無効な編集となる

デフォルトではMaskFormatterは無効な編集を許可しませんが、setAllowsInvalidメソッドを使用すると変更できます。この場合、有効な編集として編集内容をコミットできます(変更にはsetCommitsOnValidEditを使用)。

デフォルトでは、MaskFormatterは上書きモードです。この場合、新しい文字を入力したときに、その文字が挿入されるのではなく、現在の位置の文字が新しい文字で置き換えられます。この動作を変更するには、setOverwriteModeメソッドを使用します。

警告: このクラスの直列化されたオブジェクトは、今後のSwingリリースと互換ではなくなる予定です。現在の直列化のサポートは、短期間の格納や、同じバージョンのSwingを実行するアプリケーション間のRMIに適しています。 1.4では、すべてのJavaBeansの長期ストレージのサポートがjava.beansパッケージに追加されました。 XMLEncoderを参照してください。

導入されたバージョン:: 1.4

コンストラクタのサマリー

コンストラクタ

コンストラクタ

説明

MaskFormatter()

マスクを持たないMaskFormatterを作成します。

MaskFormatter(String mask)

指定のマスクを持つMaskFormatterを作成します。
メソッドのサマリー

修飾子と型

メソッド

説明

String

getInvalidCharacters()

入力が無効な文字を返します。

String

getMask()

書式を設定するマスクを返します。

String

getPlaceholder()

値がマスクを完全に埋めていない場合に使用するStringを返します。

char

getPlaceholderCharacter()

値にはない文字(つまりユーザーが入力する必要のある文字)の代わりに使用する文字を返します。

String

getValidCharacters()

入力可能な有効な文字を返します。

boolean

getValueContainsLiteralCharacters()

stringToValueがマスクのリテラル文字を返す場合、trueを返します。

void

install(JFormattedTextField ftf)

DefaultFormatterを特定のJFormattedTextFieldにインストールします。

void

setInvalidCharacters(String invalidCharacters)

入力可能な文字を詳細に制限できます。

void

setMask(String mask)

適正な文字の値を指定するマスクを設定します。

void

setPlaceholder(String placeholder)

値がマスクを完全に埋めていない場合に使用する文字列を設定します。

void

setPlaceholderCharacter(char placeholder)

値にはない文字(つまりユーザーが入力する必要のある文字)の代わりに使用する文字を設定します。

void

setValidCharacters(String validCharacters)

入力可能な文字を詳細に制限できます。

void

setValueContainsLiteralCharacters(boolean containsLiteralChars)

trueの場合、戻り値と設定値はともにマスクにリテラル文字を持ちます。

Object

stringToValue(String value)

テキストを解析し、Stringのvalueの適切なObject表現を返します。

String

valueToString(Object value)

マスクに基づいたObject valueのString表現を返します。

クラスで宣言されたメソッド DefaultFormatter
clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass

修飾子と型

メソッド

説明

Object

clone()

DefaultFormatterのコピーを作成します。

boolean

getAllowsInvalid()

編集中の値を一定時間無効にできるかどうかを返します。

boolean

getCommitsOnValidEdit()

編集がいつJFormattedTextFieldに発行されるかを返します。

protected DocumentFilter

getDocumentFilter()

JFormattedTextFieldに入力可能な文字を限定するDocumentFilterを返します。

protected NavigationFilter

getNavigationFilter()

カーソルを配置できる場所を限定するNavigationFilterを返します。

boolean

getOverwriteMode()

文字の挿入時の動作を返します。

Class<?>

getValueClass()

新規Objectの作成に使用するクラスを返します。

void

setAllowsInvalid(boolean allowsInvalid)

編集中の値を一定時間無効(つまりstringToValueがParseExceptionをスローする)にできるかどうかを設定します。

void

setCommitsOnValidEdit(boolean commit)

編集がいつJFormattedTextFieldに発行されるかを設定します。

void

setOverwriteMode(boolean overwriteMode)

文字の挿入時の動作を構成します。

void

setValueClass(Class<?> valueClass)

新規Objectの作成に使用するクラスを設定します。

クラスで宣言されたメソッド JFormattedTextField.AbstractFormatter
getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall

修飾子と型

メソッド

説明

protected Action[]

getActions()

Actionのカスタム・セットを提供する場合は、サブクラス化してオーバーライドします。

protected JFormattedTextField

getFormattedTextField()

AbstractFormatterがインストールされている現在のJFormattedTextFieldを返します。

protected void

invalidEdit()

これはユーザーが不正な文字を入力したときに呼び出されます。

protected void

setEditValid(boolean valid)

JFormattedTextFieldのeditValidプロパティを更新するために呼び出します。

void

uninstall()

JFormattedTextFieldにインストールされた、任意の状態のAbstractFormatterをアンインストールします。

クラスオブジェクトで宣言されたメソッド
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

修飾子と型

メソッド

説明

boolean

equals(Object obj)

このオブジェクトと他のオブジェクトが等しいかどうかを示します。

protected void

finalize()

削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
最終決定は非推奨であり、将来のリリースで削除される可能性があります。

final Class<?>

getClass()

このObjectの実行時クラスを返します。

int

hashCode()

このオブジェクトに対するハッシュ・コード値を返します。

final void

notify()

このオブジェクトのモニターで待機中のスレッドを1つ再開します。

final void

notifyAll()

このオブジェクトのモニターで待機中のすべてのスレッドを再開します。

String

toString()

オブジェクトの文字列表現を返します。

final void

wait()

現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。

final void

wait(long timeoutMillis)

現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

final void

wait(long timeoutMillis, int nanos)

現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

コンストラクタの詳細
- MaskFormatter
  
  public MaskFormatter()
  
  マスクを持たないMaskFormatterを作成します。
- MaskFormatter
  
  public MaskFormatter(String mask) throws ParseException
  
  指定のマスクを持つMaskFormatterを作成します。 maskが無効である場合、ParseExceptionがスローされます。
  
  パラメータ:
  
  mask - マスク
  
  スロー:
  
  ParseException - マスクに有効なマスク文字がない場合
メソッドの詳細
- setMask
  
  public void setMask(String mask) throws ParseException
  
  適正な文字の値を指定するマスクを設定します。 maskが無効である場合は、ParseExceptionをスローします。
  
  パラメータ:
  
  mask - マスク
  
  スロー:
  
  ParseException - マスクに有効なマスク文字がない場合
- getMask
  
  public String getMask()
  
  書式を設定するマスクを返します。
  
  戻り値:
  
  適正な文字の値を規定するマスク。
- setValidCharacters
  
  public void setValidCharacters(String validCharacters)
  
  入力可能な文字を詳細に制限できます。 invalidCharactersではなく、マスクやvalidCharactersで指定された文字だけを入力できます。 nullを渡す(デフォルト)ということは、有効な文字がマスクや無効な文字だけにバインドされていることを表します。
  
  パラメータ:
  
  validCharacters - null以外の場合、適正な文字を指定する。
- getValidCharacters
  
  public String getValidCharacters()
  
  入力可能な有効な文字を返します。
  
  戻り値:
  
  適正な文字
- setInvalidCharacters
  
  public void setInvalidCharacters(String invalidCharacters)
  
  入力可能な文字を詳細に制限できます。 invalidCharactersではなく、マスクやvalidCharactersで指定された文字だけを入力できます。 nullを渡す(デフォルト)ということは、有効な文字がマスクや有効な文字だけにバインドされていることを表します。
  
  パラメータ:
  
  invalidCharacters - null以外の場合、不正な文字を指定する。
- getInvalidCharacters
  
  public String getInvalidCharacters()
  
  入力が無効な文字を返します。
  
  戻り値:
  
  不正な文字。
- setPlaceholder
  
  public void setPlaceholder(String placeholder)
  
  値がマスクを完全に埋めていない場合に使用する文字列を設定します。 null値は、プレースホルダー文字を使用してはいけないことを示します。
  
  パラメータ:
  
  placeholder - 値がマスクを完全に埋めていない場合の書式設定時に使用する文字列
- getPlaceholder
  
  public String getPlaceholder()
  
  値がマスクを完全に埋めていない場合に使用するStringを返します。
  
  戻り値:
  
  値がマスクを完全に埋めていない場合の書式設定時に使用する文字列
- setPlaceholderCharacter
  
  public void setPlaceholderCharacter(char placeholder)
  
  値にはない文字(つまりユーザーが入力する必要のある文字)の代わりに使用する文字を設定します。デフォルト値は空白文字です。
  これはプレースホルダー文字列が指定されていないか、マスクが完全に埋められていない場合にだけ適用可能です。
  
  パラメータ:
  
  placeholder - 値がマスクを完全に埋めていない場合の書式設定時に使用する文字
- getPlaceholderCharacter
  
  public char getPlaceholderCharacter()
  
  値にはない文字(つまりユーザーが入力する必要のある文字)の代わりに使用する文字を返します。
  
  戻り値:
  
  値がマスクを完全に埋めていない場合の書式設定時に使用する文字
- setValueContainsLiteralCharacters
  
  public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
  
  trueの場合、戻り値と設定値はともにマスクにリテラル文字を持ちます。
  たとえば、マスクが'(###)###-####'、現在値が'(415) 555-1212'、そしてvalueContainsLiteralCharactersがtrueの場合、stringToValueは'(415) 555-1212'を返します。一方、valueContainsLiteralCharactersがfalseの場合、stringToValueは'4155551212'を返します。
  
  パラメータ:
  
  containsLiteralChars - マスクのリテラル文字をstringToValueに返すかどうかを示すために使用される
- getValueContainsLiteralCharacters
  
  public boolean getValueContainsLiteralCharacters()
  
  stringToValueがマスクのリテラル文字を返す場合、trueを返します。
  
  戻り値:
  
  マスクのリテラル文字がstringToValueに返される場合はtrue
- stringToValue
  public Object stringToValue(String value) throws ParseException
  
  テキストを解析し、Stringのvalueの適切なObject表現を返します。値クラス(setValueClass)を指定してある場合は、そのインスタンスを作成するため、必要に応じてリテラル文字列を除去し、スーパー・クラスstringToValueを呼び出します。値が現在のマスクに一致しない場合は、ParseExceptionをスローします。リテラル文字列の詳しい処理方法については、setValueContainsLiteralCharacters(boolean)を参照してください。
  
  オーバーライド:
  
  stringToValue、クラスDefaultFormatter
  
  パラメータ:
  
  value - 変換対象の文字列
  
  戻り値:
  
  テキストのオブジェクト表現
  
  スロー:
  
  ParseException - 変換でエラーが発生した場合
  
  関連項目:
  
  setValueContainsLiteralCharacters(boolean)
- valueToString
  public String valueToString(Object value) throws ParseException
  
  マスクに基づいたObject valueのString表現を返します。リテラル文字列の詳しい処理方法については、setValueContainsLiteralCharacters(boolean)を参照してください。
  
  オーバーライド:
  
  valueToString、クラスDefaultFormatter
  
  パラメータ:
  
  value - 変換対象の値
  
  戻り値:
  
  値の文字列表現
  
  スロー:
  
  ParseException - 変換でエラーが発生した場合
  
  関連項目:
  
  setValueContainsLiteralCharacters(boolean)
- install
  
  public void install(JFormattedTextField ftf)
  
  DefaultFormatterを特定のJFormattedTextFieldにインストールします。これによりvalueToStringが呼び出されて、現在の値がJFormattedTextFieldからStringへ変換されます。次に、getActionsからのAction、getDocumentFilterから返されたDocumentFilter、getNavigationFilterから返されたNavigationFilterが、JFormattedTextFieldにインストールされます。
  通常、サブクラスでのオーバーライドが必要になるのは、JFormattedTextFieldに追加リスナーをインストールする場合だけです。
  現在の値をStringに変換するときにParseExceptionが発生した場合は、テキストとして空のStringが設定され、JFormattedTextFieldに不正な状態を示す値が設定されます。
  これはpublicメソッドですが、通常はJFormattedTextFieldのサブクラスに対してだけ有効です。値が変更されるか、内部状態が変更される場合、JFormattedTextFieldによりこのメソッドが適切なタイミングで呼び出されます。
  
  オーバーライド:
  
  install、クラスDefaultFormatter
  
  パラメータ:
  
  ftf - フォーマット対象のJformattedTextField。nullの場合は、現在のJFormattedTextFieldからのアンインストールを示す。

クラスMaskFormatter

コンストラクタのサマリー

メソッドのサマリー

クラスで宣言されたメソッド DefaultFormatter

クラスで宣言されたメソッド JFormattedTextField.AbstractFormatter

クラスオブジェクトで宣言されたメソッド

コンストラクタの詳細

MaskFormatter

MaskFormatter

メソッドの詳細

setMask

getMask

setValidCharacters

getValidCharacters

setInvalidCharacters

getInvalidCharacters

setPlaceholder

getPlaceholder

setPlaceholderCharacter

getPlaceholderCharacter

setValueContainsLiteralCharacters

getValueContainsLiteralCharacters

stringToValue

valueToString

install