MaskFormatter (Java Platform SE 8)

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"だとします。右矢印キーを使ってフィールドをナビゲートしていくと、次のような結果が得られます(|はキャレット位置)。

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

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

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

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

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

警告: このクラスの直列化されたオブジェクトは、今後のSwingリリースとの互換性がなくなる予定です。現在の直列化のサポートは、短期間の格納や、同じバージョンのSwingを実行するアプリケーション間のRMIに適しています。1.4以降、すべてのJavaBeans(tm)用の長期間の格納サポートが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)を参照してください。
    
    オーバーライド:
    
    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からのアンインストールを示す。

バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.

クラスMaskFormatter

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

メソッドのサマリー

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

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

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

コンストラクタの詳細

MaskFormatter

MaskFormatter

メソッドの詳細

setMask

getMask

setValidCharacters

getValidCharacters

setInvalidCharacters

getInvalidCharacters

setPlaceholder

getPlaceholder

setPlaceholderCharacter

getPlaceholderCharacter

setValueContainsLiteralCharacters

getValueContainsLiteralCharacters

stringToValue

valueToString

install