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 }