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('_');
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 ('-')で挿入を行う場合、次の2つの処理が発生します。
デフォルトではMaskFormatterは無効な編集を許可しませんが、setAllowsInvalidメソッドを使用すると変更できます。この場合、有効な編集として編集内容をコミットできます(変更にはsetCommitsOnValidEditを使用)。
デフォルトでは、MaskFormatterは上書きモードです。 この場合、新しい文字を入力したときに、その文字が挿入されるのではなく、現在の位置の文字が新しい文字で置き換えられます。 この動作を変更するには、setOverwriteModeメソッドを使用します。
警告: このクラスの直列化されたオブジェクトは、今後のSwingリリースとの互換性がなくなる予定です。 現在の直列化のサポートは、短期間の格納や、同じバージョンのSwingを実行するアプリケーション間のRMIに適しています。 1.4以降、すべてのJavaBeans™用の長期間の格納サポートがjava.beansパッケージに追加されています。 XMLEncoderを参照してください。
| コンストラクタ | 説明 |
|---|---|
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表現を返します。 |
clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClassgetActions, getFormattedTextField, invalidEdit, setEditValid, uninstallpublic MaskFormatter()
public MaskFormatter(String mask) throws ParseException
MaskFormatterを作成します。 maskが無効である場合、ParseExceptionがスローされます。 ParseException - マスクに有効なマスク文字がない場合public void setMask(String mask) throws ParseException
maskが無効である場合は、ParseExceptionをスローします。 ParseException - マスクに有効なマスク文字がない場合public String getMask()
public void setValidCharacters(String validCharacters)
invalidCharactersではなく、マスクやvalidCharactersで指定された文字だけを入力できます。 nullを渡す(デフォルト)ということは、有効な文字がマスクや無効な文字だけにバインドされていることを表します。 validCharacters - null以外の場合、適正な文字を指定する。public String getValidCharacters()
public void setInvalidCharacters(String invalidCharacters)
invalidCharactersではなく、マスクやvalidCharactersで指定された文字だけを入力できます。 nullを渡す(デフォルト)ということは、有効な文字がマスクや有効な文字だけにバインドされていることを表します。 invalidCharacters - null以外の場合、不正な文字を指定する。public String getInvalidCharacters()
public void setPlaceholder(String placeholder)
placeholder - 値がマスクを完全に埋めていない場合の書式設定時に使用する文字列public String getPlaceholder()
public void setPlaceholderCharacter(char placeholder)
これはプレースホルダー文字列が指定されていないか、マスクが完全に埋められていない場合にだけ適用可能です。
placeholder - 値がマスクを完全に埋めていない場合の書式設定時に使用する文字public char getPlaceholderCharacter()
public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
たとえば、マスクが'(###)###-####'、現在値が'(415) 555-1212'、そしてvalueContainsLiteralCharactersがtrueの場合、stringToValueは'(415) 555-1212'を返します。 一方、valueContainsLiteralCharactersがfalseの場合、stringToValueは'4155551212'を返します。
containsLiteralChars - マスクのリテラル文字をstringToValueに返すかどうかを示すために使用されるpublic boolean getValueContainsLiteralCharacters()
stringToValueがマスクのリテラル文字を返す場合、trueを返します。public Object stringToValue(String value) throws ParseException
valueの適切なObject表現を返します。 値クラス(setValueClass)を指定してある場合は、そのインスタンスを作成するため、必要に応じてリテラル文字列を除去し、スーパー・クラスstringToValueを呼び出します。 値が現在のマスクに一致しない場合は、ParseExceptionをスローします。 リテラル文字列の詳しい処理方法については、setValueContainsLiteralCharacters(boolean)を参照してください。 stringToValue、クラスDefaultFormattervalue - 変換対象の文字列ParseException - 変換でエラーが発生した場合setValueContainsLiteralCharacters(boolean)public String valueToString(Object value) throws ParseException
valueのString表現を返します。 リテラル文字列の詳しい処理方法については、setValueContainsLiteralCharacters(boolean)を参照してください。 valueToString、クラスDefaultFormattervalue - 変換対象の値ParseException - 変換でエラーが発生した場合setValueContainsLiteralCharacters(boolean)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、クラスDefaultFormatterftf - フォーマット対象のJformattedTextField。nullの場合は、現在のJFormattedTextFieldからのアンインストールを示す。 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。 そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。