8154431: Allow source and target based validation for the focus transfer between two JComponents
authorssadetsky
Tue, 07 Jun 2016 11:29:42 +0300
changeset 39032 0df349c99122
parent 39031 270b6bdddb53
child 39033 d61135c3795c
8154431: Allow source and target based validation for the focus transfer between two JComponents Reviewed-by: alexsch, prr
jdk/src/java.desktop/share/classes/javax/swing/InputVerifier.java
jdk/src/java.desktop/share/classes/javax/swing/JComponent.java
jdk/test/javax/swing/InputVerifier/VerifyTarget/VerifyTargetTest.java
--- a/jdk/src/java.desktop/share/classes/javax/swing/InputVerifier.java	Tue Jun 07 11:02:21 2016 +0530
+++ b/jdk/src/java.desktop/share/classes/javax/swing/InputVerifier.java	Tue Jun 07 11:29:42 2016 +0300
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,108 +28,151 @@
 import java.util.*;
 
 /**
- * The purpose of this class is to help clients support smooth focus
- * navigation through GUIs with text fields. Such GUIs often need
- * to ensure that the text entered by the user is valid (for example,
- * that it's in
- * the proper format) before allowing the user to navigate out of
- * the text field. To do this, clients create a subclass of
- * <code>InputVerifier</code> and, using <code>JComponent</code>'s
- * <code>setInputVerifier</code> method,
- * attach an instance of their subclass to the <code>JComponent</code> whose input they
- * want to validate. Before focus is transfered to another Swing component
- * that requests it, the input verifier's <code>shouldYieldFocus</code> method is
- * called.  Focus is transfered only if that method returns <code>true</code>.
+ * This class provides the validation mechanism for Swing components. GUIs often
+ * need to ensure that the components are in a valid state before allowing the
+ * user to navigate the input focus. To do this, clients create a subclass of
+ * {@code InputVerifier} and, using {@code JComponent}'s
+ * {@code setInputVerifier} method, attach an instance of their subclass to
+ * the {@code JComponent} which is the source of the focus transfer operation.
+ * The {@code InputVerifier} also provides the possibility to validate against
+ * the target of the focus transfer which may reject the focus.
+ * Before focus is transferred from the source Swing component to the target
+ * Swing component, the input verifier's
+ * {@code shouldYieldFocus(source, target)} method is called. Focus is
+ * transferred only if that method returns
+ * {@code true}.
  * <p>
  * The following example has two text fields, with the first one expecting
- * the string "pass" to be entered by the user. If that string is entered in
- * the first text field, then the user can advance to the second text field
- * either by clicking in it or by pressing TAB. However, if another string
- * is entered in the first text field, then the user will be unable to
+ * the string "pass" to be entered by the user. If either that string is entered
+ * in the first text field or the second text field contains "accept" string,
+ * then the user can advance focus to the second text field by clicking in it or
+ * by pressing TAB.
+ * However, if another string is entered in the first text field and the second
+ * text field does not contain "accept", then the user will be unable to
  * transfer focus to the second text field.
  *
  * <pre>
  * import java.awt.*;
- * import java.util.*;
- * import java.awt.event.*;
  * import javax.swing.*;
  *
  * // This program demonstrates the use of the Swing InputVerifier class.
  * // It creates two text fields; the first of the text fields expects the
- * // string "pass" as input, and will allow focus to advance out of it
- * // only after that string is typed in by the user.
+ * // string "pass" as input, and will allow focus to advance to the second text
+ * // field if either that string is typed in by the user or the second
+ * // field contains "accept" string.
  *
  * public class VerifierTest extends JFrame {
+ *
  *     public VerifierTest() {
- *         JTextField tf1 = new JTextField ("Type \"pass\" here");
- *         getContentPane().add (tf1, BorderLayout.NORTH);
- *         tf1.setInputVerifier(new PassVerifier());
+ *         JTextField field1 = new JTextField("Type \"pass\" here");
+ *         JTextField field2 = new JTextField("or \"accept\" here");
+ *         getContentPane().add(field1, BorderLayout.NORTH);
+ *         getContentPane().add(field2, BorderLayout.SOUTH);
  *
- *         JTextField tf2 = new JTextField ("TextField2");
- *         getContentPane().add (tf2, BorderLayout.SOUTH);
+ *         field.setInputVerifier(new InputVerifier() {
+ *             public boolean verify(JComponent input) {
+ *                return "pass".equals(((JTextField) input).getText());
+ *             }
  *
- *         WindowListener l = new WindowAdapter() {
- *             public void windowClosing(WindowEvent e) {
- *                 System.exit(0);
+ *             public boolean verifyTarget(JComponent input) {
+ *                 return "accept".equals(((JTextField) input).getText());
  *             }
- *         };
- *         addWindowListener(l);
- *     }
  *
- *     class PassVerifier extends InputVerifier {
- *         public boolean verify(JComponent input) {
- *             JTextField tf = (JTextField) input;
- *             return "pass".equals(tf.getText());
- *         }
+ *             public boolean shouldYieldFocus(JComponent source,
+ *                                                          JComponent target) {
+ *                 return verify(source) || verifyTarget(target);
+ *             }
+ *         });
+ *
+ *         pack();
+ *         setVisible(true);
  *     }
  *
  *     public static void main(String[] args) {
- *         Frame f = new VerifierTest();
- *         f.pack();
- *         f.setVisible(true);
+ *         SwingUtilities.invokeLater(VerifierTest::new);
  *     }
  * }
  * </pre>
  *
- *  @since 1.3
+ * @since 1.3
  */
-
-
 public abstract class InputVerifier {
 
-  /**
-   * Checks whether the JComponent's input is valid. This method should
-   * have no side effects. It returns a boolean indicating the status
-   * of the argument's input.
-   *
-   * @param input the JComponent to verify
-   * @return <code>true</code> when valid, <code>false</code> when invalid
-   * @see JComponent#setInputVerifier
-   * @see JComponent#getInputVerifier
-   *
-   */
+    /**
+     * Checks whether the JComponent's input is valid. This method should
+     * have no side effects. It returns a boolean indicating the status
+     * of the argument's input.
+     *
+     * @param input the JComponent to verify
+     * @return {@code true} when valid, {@code false} when invalid
+     * @see JComponent#setInputVerifier
+     * @see JComponent#getInputVerifier
+     */
+    public abstract boolean verify(JComponent input);
 
-  public abstract boolean verify(JComponent input);
-
+    /**
+     * Calls {@code verify(input)} to ensure that the input is valid.
+     * This method can have side effects. In particular, this method
+     * is called when the user attempts to advance focus out of the
+     * argument component into another Swing component in this window.
+     * If this method returns {@code true}, then the focus is transferred
+     * normally; if it returns {@code false}, then the focus remains in
+     * the argument component.
+     *
+     * @param input the JComponent to verify
+     * @return {@code true} when valid, {@code false} when invalid
+     * @see JComponent#setInputVerifier
+     * @see JComponent#getInputVerifier
+     *
+     * @deprecated use {@link #shouldYieldFocus(JComponent, JComponent)}
+     * instead.
+     */
+    @Deprecated(since = "9")
+    public boolean shouldYieldFocus(JComponent input) {
+        return verify(input);
+    }
 
-  /**
-   * Calls <code>verify(input)</code> to ensure that the input is valid.
-   * This method can have side effects. In particular, this method
-   * is called when the user attempts to advance focus out of the
-   * argument component into another Swing component in this window.
-   * If this method returns <code>true</code>, then the focus is transfered
-   * normally; if it returns <code>false</code>, then the focus remains in
-   * the argument component.
-   *
-   * @param input the JComponent to verify
-   * @return <code>true</code> when valid, <code>false</code> when invalid
-   * @see JComponent#setInputVerifier
-   * @see JComponent#getInputVerifier
-   *
-   */
+    /**
+     * Checks whether the target JComponent that will be receiving the focus
+     * is ready to accept it. This method should be over-ridden only if it is
+     * necessary to validate the target of the focus transfer.
+     * This method should have no side effects. It returns a boolean
+     * indicating the status of the argument's input.
+     *
+     * @implSpec By default this method returns {@code true}.
+     *
+     * @param target the target JComponent to verify
+     * @return {@code true} when valid, {@code false} when invalid
+     * @see JComponent#setInputVerifier
+     * @see JComponent#getInputVerifier
+     * @since 9
+     */
+    public boolean verifyTarget(JComponent target) {
+        return true;
+    }
 
-  public boolean shouldYieldFocus(JComponent input) {
-    return verify(input);
-  }
-
+    /**
+     * Is called by Swing if this {@code InputVerifier} is assigned to the
+     * {@code source} Swing component to check whether the requested focus
+     * transfer from the {@code source} to {@code target} is allowed.
+     * This method can have side effects.
+     * If this method returns {@code true}, then the focus is transferred
+     * normally; if it returns {@code false}, then the focus remains in
+     * the first argument component.
+     *
+     * @implSpec The basic implementation of this method returns the conjunction
+     * of results obtained from {@code verify(input)} and
+     * {@code verifyTarget(input)} to ensure that both the source and the target
+     * components are in valid state.
+     *
+     * @param source the source JComponent of the focus transfer
+     * @param target the target JComponent of the focus transfer
+     * @return {@code true} when valid, {@code false} when invalid
+     * @see JComponent#setInputVerifier
+     * @see JComponent#getInputVerifier
+     * @since 9
+     */
+    public boolean shouldYieldFocus(JComponent source, JComponent target) {
+        return shouldYieldFocus(source) && verifyTarget(target);
+    }
 }
--- a/jdk/src/java.desktop/share/classes/javax/swing/JComponent.java	Tue Jun 07 11:02:21 2016 +0530
+++ b/jdk/src/java.desktop/share/classes/javax/swing/JComponent.java	Tue Jun 07 11:29:42 2016 +0300
@@ -3587,7 +3587,7 @@
                     SwingUtilities.appContextPut(INPUT_VERIFIER_SOURCE_KEY,
                                                  jFocusOwner);
                     try {
-                        return iv.shouldYieldFocus(jFocusOwner);
+                        return iv.shouldYieldFocus(jFocusOwner, target);
                     } finally {
                         if (currentSource != null) {
                             // We're already in the InputVerifier for
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/test/javax/swing/InputVerifier/VerifyTarget/VerifyTargetTest.java	Tue Jun 07 11:29:42 2016 +0300
@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+  @test
+  @bug 8154431
+  @summary Allow source and target based validation for the focus transfer
+           between two JComponents.
+  @run main VerifyTargetTest
+*/
+
+import javax.swing.*;
+import java.awt.*;
+import java.awt.event.FocusEvent;
+import java.awt.event.FocusListener;
+
+public class VerifyTargetTest extends InputVerifier implements FocusListener {
+    static boolean success;
+    private static JFrame frame;
+    private static JTextField field2;
+
+    public static void main(String[] args) throws Exception {
+        SwingUtilities.invokeAndWait(() -> setup());
+        try {
+            Robot robot = new Robot();
+            robot.waitForIdle();
+            robot.delay(200);
+            KeyboardFocusManager.getCurrentKeyboardFocusManager()
+                                                          .focusNextComponent();
+            robot.waitForIdle();
+            robot.delay(200);
+            if (!success) {
+                throw new RuntimeException("Failed");
+            } else {
+                System.out.println("ok");
+            }
+        } finally {
+            SwingUtilities.invokeLater(() -> frame.dispose());
+        }
+    }
+
+    static void setup() {
+        frame = new JFrame();
+        JTextField field1 = new JTextField("Input 1");
+        VerifyTargetTest test = new VerifyTargetTest();
+        field1.setInputVerifier(test);
+        field1.addFocusListener(test);
+        frame.getContentPane().add(field1, BorderLayout.NORTH);
+        field2 = new JTextField("Input 2");
+        frame.getContentPane().add(field2, BorderLayout.SOUTH);
+        frame.pack();
+        frame.setVisible(true);
+    }
+
+    @Override
+    public boolean verify(JComponent input) {
+        return true;
+    }
+
+    @Override
+    public boolean verifyTarget(JComponent input) {
+        success = input == field2;
+        return false;
+    }
+
+    @Override
+    public void focusGained(FocusEvent e) {}
+
+    @Override
+    public void focusLost(FocusEvent e) {
+        success = false;
+    }
+}
\ No newline at end of file