javax.swing.text
クラス MaskFormatter

java.lang.Object
  javax.swing.JFormattedTextField.AbstractFormatter
      javax.swing.text.DefaultFormatter
          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");
 

文字列の長さがマスクの長さより短い場合は、最初に値の書式を設定するとき、プレースホルダ文字列またはプレースホルダ文字が使用されます。プレースホルダ文字列のほうが優先されます。次に例を示します。

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");
 

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

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

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
 

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

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

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

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

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

警告: このクラスの直列化されたオブジェクトは、今後の Swing リリースと互換ではなくなる予定です。現在の直列化のサポートは、短期間の運用や、同じバージョンの Swing を実行するアプリケーション間の RMI に適しています。JDK Version 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 表現を返します。

クラス javax.swing.text.DefaultFormatter から継承されたメソッド

clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass

クラス javax.swing.JFormattedTextField.AbstractFormatter から継承されたメソッド

getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall

クラス java.lang.Object から継承されたメソッド

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

MaskFormatter

public MaskFormatter()

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

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException

指定のマスクを持つ MaskFormatter を作成します。mask が無効である場合、ParseException がスローされます。

例外:

ParseException - マスクに有効なマスク文字がない場合

メソッドの詳細

setMask

public void setMask(String mask)
             throws ParseException

適正な文字の値を指定するマスクを設定します。mask が無効である場合は、ParseException をスローします。

例外:

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) を参照してください。

オーバーライド:

クラス DefaultFormatter 内の stringToValue

パラメータ:

value - 変換対象の文字列

戻り値:

テキストのオブジェクト表現

例外:

ParseException - 変換でエラーが発生した場合

関連項目:

setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException

マスクに基づいた Object の value の String 表現を返します。リテラル文字列の詳しい処理方法については、setValueContainsLiteralCharacters(boolean) を参照してください。

オーバーライド:

クラス DefaultFormatter 内の valueToString

パラメータ:

value - 変換対象の値

戻り値:

値の文字列表現

例外:

ParseException - 変換でエラーが発生した場合

関連項目:

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)

DefaultFormatter を特定の JFormattedTextField にインストールします。これにより valueToString が呼び出されて、現在の値が JFormattedTextField から String へ変換されます。次に getActions からの Action、getDocumentFilter から返された DocumentFilter、getNavigationFilter から返された NavigationFilter が、JFormattedTextField にインストールされます。

通常、サブクラスでのオーバーライドが必要になるのは、JFormattedTextField に追加リスナーをインストールする場合だけです。

現在の値を文字列に変換するときに ParseException が発生した場合は、テキストとして空の文字列が設定され、JFormattedTextField に不正な状態を示す値が設定されます。

これは public メソッドですが、通常は JFormattedTextField のサブクラスに対してだけ有効です。値が変更されるか、内部状態が変更される場合、JFormattedTextField によりこのメソッドが呼び出されます。

オーバーライド:

クラス DefaultFormatter 内の install

パラメータ:

ftf - フォーマット対象の JformattedTextField。 null の場合は、現在の JFormattedTextField からのアンインストールを示す