MaskFormatter (Java 2 プラットフォーム SE v1.4.0)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM 2
Platform
Std. Ed. v1.4.0

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

javax.swing.text
クラス MaskFormatter

java.lang.Object
  |
  +--javax.swing.JFormattedTextField.AbstractFormatter
        |
        +--javax.swing.text.DefaultFormatter
              |
              +--javax.swing.text.MaskFormatter

すべての実装インタフェース:: Cloneable, Serializable

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)

通常、文字は 1 つの 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」となります。プレースホルダ String は初期フォーマットにだけ使用され、その後のフォーマットではプレースホルダ文字だけが使用されます。

MaskFormatter が有効な文字だけを許可するように構成されている場合 (setAllowsInvalid(false))、編集時には必要に応じてリテラル文字がスキップされます。マスク「###-####」および現在値「555-1212」を保持する MaskFormatter を考えてみましょう。右矢印キーを使用してフィールドをナビゲートすると、以下のようになります (| はキャレットの位置)。

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

編集時には結果として同様の動作が発生します。上の例の MaskFormatter に文字列「123-45」と「12345」を挿入する場合を考えてみましょう。両方を挿入すると、結果として同じ String ｢ｱｲｳｭｴｵﾟﾟ｣になります。文字位置 3 (「-」) で MaskFormatter が挿入処理を行うと、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 を渡す (デフォルト) ということは、有効な文字がマスクや無効な文字によってだけバインドされていることを表します。

getInvalidCharacters

public String getInvalidCharacters()

入力が無効な文字を返します。

戻り値:: 不正な文字

setPlaceholder

public void setPlaceholder(String placeholder)

値がマスクを完全に埋めていない場合に使用する文字列を設定します。null 値はプレースホルダ char を使用することを表します。

パラメータ:: placeholder - 値がマスクを完全に埋めていない場合、フォーマットに使用される String

getPlaceholder

public String getPlaceholder()

値がマスクを完全に埋めていない場合に使用する String を返します。

戻り値:: 値がマスクを完全に埋めていない場合、フォーマットに使用される 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 がスローされます。

オーバーライド:: クラス DefaultFormatter 内の stringToValue

戻り値:: テキストの Object 表現
例外:: ParseException - 変換にエラーがある場合

valueToString

public String valueToString(Object value)
                     throws ParseException

マスクに基づいた Object value の String 表現を返します。

オーバーライド:: クラス DefaultFormatter 内の valueToString

パラメータ:: value - 変換する値
戻り値:: 値の String 表現
例外:: ParseException - 変換にエラーがある場合

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 によりこのメソッドが呼び出されます。

オーバーライド:: クラス DefaultFormatter 内の install

パラメータ:: ftf - 書式設定用の JFormattedTextField。null も可 (現行の JFormattedTextField のアンインストールを示す)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM 2
Platform
Std. Ed. v1.4.0

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

バグの報告と機能のリクエスト
これ以外の API リファレンスおよび開発者用ドキュメントについては、 Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

#	任意の有効な数字。`Character.isDigit` を使用する
'	エスケープ文字。特殊フォーマット文字をエスケープする
U	任意の文字 (`Character.isLetter`)。すべての小文字は大文字にマッピングされる
L	任意の文字 (`Character.isLetter`)。すべての大文字は小文字にマッピングされる
A	任意の文字または数字 (`Character.isLetter` または `Character.isDigit`)
?	任意の文字 (`Character.isLetter`)
*	すべての文字および数字
H	任意の 16 進数文字 (0-9、a-f または A-F)

コンストラクタの概要
`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 クラス MaskFormatter

MaskFormatter

MaskFormatter

setMask

getMask

setValidCharacters

getValidCharacters

setInvalidCharacters

getInvalidCharacters

setPlaceholder

getPlaceholder

setPlaceholderCharacter

getPlaceholderCharacter

setValueContainsLiteralCharacters

getValueContainsLiteralCharacters

stringToValue

valueToString

install

javax.swing.text
クラス MaskFormatter