1 /*
   2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing;
  27 
  28 import java.util.*;
  29 
  30 /**
  31  * The purpose of this class is to help clients support smooth focus
  32  * navigation through GUIs with text fields. Such GUIs often need
  33  * to ensure that the text entered by the user is valid (for example,
  34  * that it's in
  35  * the proper format) before allowing the user to navigate out of
  36  * the text field. To do this, clients create a subclass of
  37  * {@code InputVerifier} and, using {@code JComponent}'s
  38  * {@code setInputVerifier} method,
  39  * attach an instance of their subclass to the {@code JComponent} whose input they
  40  * want to validate. Before focus is transfered to another Swing component
  41  * that requests it, the input verifier's {@code shouldYieldFocus} method is
  42  * called.  Focus is transfered only if that method returns {@code true}.
  43  * <p>
  44  * The following example has two text fields, with the first one expecting
  45  * the string "pass" to be entered by the user. If that string is entered in
  46  * the first text field, then the user can advance to the second text field
  47  * either by clicking in it or by pressing TAB. However, if another string
  48  * is entered in the first text field, then the user will be unable to
  49  * transfer focus to the second text field.
  50  *
  51  * <pre>
  52  * import java.awt.*;
  53  * import java.util.*;
  54  * import java.awt.event.*;
  55  * import javax.swing.*;
  56  *
  57  * // This program demonstrates the use of the Swing InputVerifier class.
  58  * // It creates two text fields; the first of the text fields expects the
  59  * // string "pass" as input, and will allow focus to advance out of it
  60  * // only after that string is typed in by the user.
  61  *
  62  * public class VerifierTest extends JFrame {
  63  *     public VerifierTest() {
  64  *         JTextField tf1 = new JTextField ("Type \"pass\" here");
  65  *         getContentPane().add (tf1, BorderLayout.NORTH);
  66  *         tf1.setInputVerifier(new PassVerifier());
  67  *
  68  *         JTextField tf2 = new JTextField ("TextField2");
  69  *         getContentPane().add (tf2, BorderLayout.SOUTH);
  70  *
  71  *         WindowListener l = new WindowAdapter() {
  72  *             public void windowClosing(WindowEvent e) {
  73  *                 System.exit(0);
  74  *             }
  75  *         };
  76  *         addWindowListener(l);
  77  *     }
  78  *
  79  *     class PassVerifier extends InputVerifier {
  80  *         public boolean verify(JComponent input) {
  81  *             JTextField tf = (JTextField) input;
  82  *             return "pass".equals(tf.getText());
  83  *         }
  84  *     }
  85  *
  86  *     public static void main(String[] args) {
  87  *         Frame f = new VerifierTest();
  88  *         f.pack();
  89  *         f.setVisible(true);
  90  *     }
  91  * }
  92  * </pre>
  93  *
  94  *  @since 1.3
  95  */
  96 
  97 
  98 public abstract class InputVerifier {
  99 
 100   /**
 101    * Checks whether the JComponent's input is valid. This method should
 102    * have no side effects. It returns a boolean indicating the status
 103    * of the argument's input.
 104    *
 105    * @param input the JComponent to verify
 106    * @return {@code true} when valid, {@code false} when invalid
 107    * @see JComponent#setInputVerifier
 108    * @see JComponent#getInputVerifier
 109    *
 110    */
 111 
 112   public abstract boolean verify(JComponent input);
 113 
 114 
 115   /**
 116    * Calls {@code verify(input)} to ensure that the input is valid.
 117    * This method can have side effects. In particular, this method
 118    * is called when the user attempts to advance focus out of the
 119    * argument component into another Swing component in this window.
 120    * If this method returns {@code true}, then the focus is transfered
 121    * normally; if it returns {@code false}, then the focus remains in
 122    * the argument component.
 123    *
 124    * @param input the JComponent to verify
 125    * @return {@code true} when valid, {@code false} when invalid
 126    * @see JComponent#setInputVerifier
 127    * @see JComponent#getInputVerifier
 128    *
 129    */
 130 
 131   public boolean shouldYieldFocus(JComponent input) {
 132     return verify(input);
 133   }
 134 
 135 }
--- EOF ---