モジュール java.desktop
パッケージ javax.swing

クラスJFormattedTextField

  • すべての実装されたインタフェース:
    ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
    @JavaBean
public class JFormattedTextField
extends JTextField
    JFormattedTextFieldはJTextFieldを拡張して、任意の値をフォーマットしたり、ユーザーがテキストを編集したあとに特定のオブジェクトを取得したりするためのサポートを追加します。 JFormattedTextFieldの日付編集用の設定例を次に挙げます。 
       JFormattedTextField ftf = new JFormattedTextField();
   ftf.setValue(new Date());

    JFormattedTextFieldが一度生成されると、PropertyChangeListenerを追加し、プロパティ名valueを使用してPropertyChangeEventを待機することで、変更の編集を待機できます。

    JFormattedTextFieldが、フォーカスを失ったときに実行するアクションを設定できます。 次の設定が用意されています。

    JFormattedTextFieldの有効な構成とその説明
    値 説明
    JFormattedTextField.REVERT getValueの表示に合うように、表示を元に戻す。現在の編集は失われる可能性がある。
    JFormattedTextField.COMMIT 現在の値を確定。 現在の値がAbstractFormatterによる正当な値ではなく、ParseExceptionがスローされる場合、値は変更されず、編集された値がそのまま残る。
    JFormattedTextField.COMMIT_OR_REVERT COMMITとほぼ同じ。値が正当なものでない場合はREVERTと同様。
    JFormattedTextField.PERSIST 何も処理しない。新しいAbstractFormatterの取得、値の更新、どちらも実行しない。
    デフォルトはJFormattedTextField.COMMIT_OR_REVERTです。詳細については、setFocusLostBehavior(int)を参照してください。

    JFormattedTextFieldは、現在編集中の値が不正な場合でも、フォーカスの移動が可能です。 JFormattedTextFieldの編集状態が不正な場合にフォーカスをロックするには、InputVerifierを接続します。 このようなInputVerifierを実装したコードの一部を例として挙げます。 

     public class FormattedTextFieldVerifier extends InputVerifier {
     public boolean verify(JComponent input) {
         if (input instanceof JFormattedTextField) {
             JFormattedTextField ftf = (JFormattedTextField)input;
             AbstractFormatter formatter = ftf.getFormatter();
             if (formatter != null) {
                 String text = ftf.getText();
                 try {
                      formatter.stringToValue(text);
                      return true;
                  } catch (ParseException pe) {
                      return false;
                  }
              }
          }
          return true;
      }
      public boolean shouldYieldFocus(JComponent input) {
          return verify(input);
      }
  }

    commitEditを呼び出すことでも値を確定できます。

    JFormattedTextFieldはそれ自体ではフォーマットを行わず、JFormattedTextField.AbstractFormatterFactoryのインスタンスから取得されるJFormattedTextField.AbstractFormatterのインスタンスでフォーマットを行います。 JFormattedTextField.AbstractFormatterのインスタンスは、アクティブになったときにinstallメソッドから通知を受け、JFormattedTextField.AbstractFormatterはその時点で必要なオブジェクト(通常はDocumentFilter)をインストールできます。 同様にJFormattedTextFieldでAbstractFormatterが不要になった場合は、uninstallが呼び出されます。

    JFormattedTextFieldは、通常、フォーカスを取得または喪失したときに、AbstractFormatに対するAbstractFormatterFactoryを照会します。 ただし、これはフォーカス喪失ポリシーに基づいて変更できます。 フォーカス喪失ポリシーがJFormattedTextField.PERSISTであり、JFormattedTextFieldが編集されている場合、AbstractFormatterFactoryは値が確定されるまで照会されません。 同様に、フォーカス喪失ポリシーがJFormattedTextField.COMMITであり、例外がstringToValueからスローされる場合、AbstractFormatterFactoryはフォーカスが喪失または取得されるまで照会されません。

    JFormattedTextField.AbstractFormatterは、確定値をJFormattedTextFieldに設定するタイミングも決定します。 JFormattedTextField.AbstractFormatterの中には、編集のたびに新しく値を生成するものもあり、まったく値を確定しないものもあります。 commitEditを呼び出すことで、現在の値を現在のJFormattedTextField.AbstractFormatterから強制的に取得できるようになります。commitEditはJFormattedTextFieldで[Enter]を押すたびに呼び出されます。

    AbstractFormatterFactoryが明示的に設定されていない場合で、値がnull以外のときには、setValueが呼び出されたあとに、値の型Classに基づいてこれが設定されます。 たとえば、次のコードでは、適切なAbstractFormatterFactoryとAbstractFormatterが、数値のフォーマット処理のために生成されます。 

       JFormattedTextField tf = new JFormattedTextField();
   tf.setValue(100);

    警告: AbstractFormatterは、通常、DocumentにDocumentFilterをインストールし、JFormattedTextFieldにNavigationFilterをインストールするため、この2つを独自にインストールしないでください。 独自にインストールすると、動作が奇妙になり、AbstractFormatterの編集ポリシーが強化されなくなります。

    警告: Swingはスレッドに対して安全ではありません。 詳細は、「Swing's Threading Policy」を参照してください。

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

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

    • フィールドの詳細

      • COMMIT

        public static final int COMMIT
        フォーカス喪失時にcommitEditを呼び出すことを指定する定数です。 新しい値の確定時にParseExceptionがスローされると、無効な値がそのまま残ることになります。
        関連項目:
        setFocusLostBehavior(int)、定数フィールド値

      • COMMIT_OR_REVERT

        public static final int COMMIT_OR_REVERT
        フォーカス喪失時にcommitEditを呼び出すことを指定する定数です。 新しい値の確定時にParseExceptionがスローされると、元の値に戻されます。
        関連項目:
        setFocusLostBehavior(int)、定数フィールド値

    • コンストラクタの詳細

      • JFormattedTextField

        public JFormattedTextField()
        AbstractFormatterFactoryを使用しないでJFormattedTextFieldを生成します。 特定の型の値を編集するようにJFormattedTextFieldを設定する場合は、setMaskまたはsetFormatterFactoryを使用してください。

      • JFormattedTextField

        public JFormattedTextField​(Object value)
        指定された値を使用してJFormattedTextFieldを生成します。 valueの型に基づいたAbstractFormatterFactoryが生成されます。
        パラメータ:
        value - JFormattedTextFieldの初期値

      • JFormattedTextField

        public JFormattedTextField​(Format format)
        JFormattedTextFieldを作成します。formatは適切なAbstractFormatterにラップされ、AbstractFormatterはAbstractFormatterFactoryにラップされます。
        パラメータ:
        format - AbstractFormatterの検索に使用されるフォーマット

      • JFormattedTextField

        public JFormattedTextField​(JFormattedTextField.AbstractFormatter formatter)
        指定されたAbstractFormatterでJFormattedTextFieldを作成します。 AbstractFormatterはAbstractFormatterFactoryに配置されます。
        パラメータ:
        formatter - フォーマットで使用されるAbstractFormatter。

      • JFormattedTextField

        public JFormattedTextField​(JFormattedTextField.AbstractFormatterFactory factory)
        指定されたAbstractFormatterFactoryでJFormattedTextFieldを作成します。
        パラメータ:
        factory - フォーマットに使用されるAbstractFormatterFactory。

      • JFormattedTextField

        public JFormattedTextField​(JFormattedTextField.AbstractFormatterFactory factory,
                           Object currentValue)
        指定されたAbstractFormatterFactoryと初期値を使用してJFormattedTextFieldを生成します。
        パラメータ:
        factory - フォーマットに使用されるAbstractFormatterFactory。
        currentValue - 使用される初期値

    • メソッドの詳細

      • setFocusLostBehavior

        @BeanProperty(bound=false,
              enumerationValues={"JFormattedTextField.COMMIT","JFormattedTextField.COMMIT_OR_REVERT","JFormattedTextField.REVERT","JFormattedTextField.PERSIST"},
              description="Behavior when component loses focus")
public void setFocusLostBehavior​(int behavior)
        フォーカス喪失時の動作を設定します。 値はJFormattedTextField.COMMIT_OR_REVERT、JFormattedTextField.REVERT、JFormattedTextField.COMMITまたはJFormattedTextField.PERSISTのいずれかです。AbstractFormatterの中には、この値により影響を与えないように、変更発生時に変更をプッシュするものがあります。

        渡されるオブジェクトの値が前述の値でない場合はIllegalArgumentExceptionがスローされます。

        このプロパティのデフォルト値はJFormattedTextField.COMMIT_OR_REVERTです。

        パラメータ:
        behavior - フォーカス喪失時の動作
        例外:
        IllegalArgumentException - 動作が指定された値で示されるものでない場合

      • getFocusLostBehavior

        public int getFocusLostBehavior()
        フォーカス喪失時の動作を返します。 値はCOMMIT_OR_REVERT、COMMIT、REVERTまたはPERSISTのいずれかです。AbstractFormatterの中には、この値により影響を与えないように、変更発生時に変更をプッシュするものがあります。
        戻り値:
        フォーカス喪失時の動作

      • setFormatterFactory

        @BeanProperty(visualUpdate=true,
              description="AbstractFormatterFactory, responsible for returning an AbstractFormatter that can format the current value.")
public void setFormatterFactory​(JFormattedTextField.AbstractFormatterFactory tf)
        AbstractFormatterFactoryを設定します。 AbstractFormatterFactoryは、表示値のフォーマット、および編集ポリシー強化に使用されるAbstractFormatterのインスタンスを返すことができます。

        このメソッドまたはコンストラクタでAbstractFormatterFactoryが明示的に設定されていない場合、AbstractFormatterFactory、そして結果的にAbstractFormatterは値のClassに基づいて使用されます。 NumberにはNumberFormatter、DatesにはDateFormatter、それ以外にはDefaultFormatterが使用されます。

        これはJavaBeansバウンド・プロパティです。

        パラメータ:
        tf - AbstractFormatterのインスタンス検索に使用されるAbstractFormatterFactory

      • setFormatter

        protected void setFormatter​(JFormattedTextField.AbstractFormatter format)
        現在のAbstractFormatterを設定します。

        通常、これを呼び出す代わりに、AbstractFormatterFactoryまたはその値を設定します。 JFormattedTextFieldは、これをJFormattedTextField変更の状態として呼び出し、値のリセットを要求します。 JFormattedTextFieldはAbstractFormatterFactoryから取得したAbstractFormatterを渡します。

        これはJavaBeansバウンド・プロパティです。

        パラメータ:
        format - フォーマットで使用されるAbstractFormatter
        関連項目:
        setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)

      • setValue

        @BeanProperty(visualUpdate=true,
              description="The value to be formatted.")
public void setValue​(Object value)
        現在のAbstractFormatterFactoryから取得したAbstractFormatterでフォーマットされる値を設定します。 AbstractFormatterFactoryが指定されていない場合は、valueの型に基づいてその生成を試みます。

        このプロパティのデフォルト値はnullです。

        これはJavaBeansバウンド・プロパティです。

        パラメータ:
        value - 表示される現在の値

      • getValue

        public Object getValue()
        最新の有効な値を返します。 AbstractFormatterの編集ポリシーに基づいて、現在の値が返されない場合があります。 現在編集されている値はgetValueのあとcommitEditを呼び出すことによって取得できます。
        戻り値:
        最新の有効な値

      • commitEdit

        public void commitEdit()
                throws ParseException
        現在の値をAbstractFormatterから強制的に取得し、現在の値として設定します。 AbstractFormatterが現在インストールされていない場合は何も実行しません。
        例外:
        ParseException - AbstractFormatterが現在の値をフォーマットできない場合

      • isEditValid

        @BeanProperty(bound=false)
public boolean isEditValid()
        現在編集中の値が有効な場合にtrueを返します。 この値は現在のAbstractFormatterで管理されます。この値をpublicに設定する機能はありません。
        戻り値:
        現在編集中の値が有効な場合にtrueが返される。

      • invalidEdit

        protected void invalidEdit()
        ユーザーが無効な値を入力した場合に呼び出されます。 これにより、コンポーネントのフィード・バックが実行可能になります。 デフォルトの実装では、ビープ音を鳴らします。

      • processInputMethodEvent

        protected void processInputMethodEvent​(InputMethodEvent e)
        InputMethodEvent.INPUT_METHOD_TEXT_CHANGEDやInputMethodEvent.CARET_POSITION_CHANGEDなどのインプット・メソッド・イベントを処理します。
        オーバーライド:
        processInputMethodEvent 、クラス:  Component
        パラメータ:
        e - InputMethodEvent
        関連項目:
        InputMethodEvent

      • processFocusEvent

        protected void processFocusEvent​(FocusEvent e)
        FocusEvent.FOCUS_GAINEDやFocusEvent.FOCUS_LOSTなどのフォーカス・イベントを処理します。
        オーバーライド:
        processFocusEvent 、クラス:  Component
        パラメータ:
        e - FocusEvent
        関連項目:
        FocusEvent

      • getActions

        @BeanProperty(bound=false)
public Action[] getActions()
        エディタのコマンド・リストを取得します。 これは、エディタ自身がサポートするコマンド・コレクションで拡張された、プラグイン済みUIによってサポートされるコマンドのリストです。 これらは、キーマップ内と同じように、イベントへの割当てに役立ちます。
        オーバーライド:
        getActions 、クラス:  JTextField
        戻り値:
        コマンド・リスト

      • setDocument

        @BeanProperty(expert=true,
              description="the text document model")
public void setDocument​(Document doc)
        エディタをテキスト・ドキュメントに関連付けます。 現在登録済のファクトリを使用すると、ドキュメントのビューを構築できます。このドキュメントは、再検証後にエディタによって表示されます。 PropertyChangeイベント("document")は、各リスナーに通知されます。
        オーバーライド:
        setDocument 、クラス:  JTextField
        パラメータ:
        doc - 表示および編集するドキュメント
        関連項目:
        JTextComponent.getDocument()