モジュール java.desktop
パッケージ 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");

文字列の長さがマスクの長さより短い場合は、最初に値の書式を設定するとき、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"だとします。 右矢印キーを使ってフィールドをナビゲートしていくと、次のような結果が得られます(|はキャレット位置)。 

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
「-」は編集不可能なリテラル文字で、スキップされます。

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

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

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

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

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

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