モジュール 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('_');
   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つの処理が発生します。

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

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

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

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

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

  • コンストラクタの詳細

    • 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からのアンインストールを示す。