How to Use the Focus Subsystem

Many components even those operated primarily with the mouse, such as buttons can be operated with the keyboard. For a key press to affect a component, the component must have the keyboard focus.

From the user 's point of view, the component with the keyboard focus is generally prominentwith a dotted or black border, for exampleand the window containing the component is more prominent than other windows onscreen. These visual cues tell the user to which component any typing will go. At most, one component in the window system can have the keyboard focus.

Exactly how a window gains the focus depends on the windowing system. There's no foolproof way, across all platforms, to ensure that a window gains the focus. On some systems, such as Microsoft Windows, the frontmost window becomes the focused window; in this case, the method Window.toFront moves the window to the front, thereby giving it the focus. However, on a system such as Solaris, some window managers choose the focused window based on cursor position; in this case, Window.toFront doesn't result in the same behavior.

A component generally gains the focus by the user clicking it, tabbing between components, or otherwise interacting with it. A component can also be given the focus programmatically, such as when its containing frame or dialog is made visible. This code snippet shows how to give a particular component the focus every time the window is activated:

 //Make textField get the focus whenever frame is activated. frame.addWindowListener(new WindowAdapter() {     public void windowActivated(WindowEvent e) {         textField.requestFocusInWindow();     } }); 

If you want to ensure that a particular component gains the focus the first time a window is activated, you can call requestFocusInWindow on the component after the component has been realized but before the frame is displayed. Here's some sample code showing how this can be done:

 JFrame frame = new JFrame("Test"); JPanel = new JPanel();  //...Create a variety of components here...  //Create the component that will have the initial focus. JButton button = new JButton("I'm first"); panel.add(button); frame.getContentPane().add(panel);  //Add it to the panel frame.pack();  //Realize the components.  //This button will have the initial focus.   button.requestFocusInWindow();  frame.setVisible(true); //Display the window. 

Version Note: This section describes the focus architecture implemented in release 1.4. Prior to 1.4, JComponent methods such as setNextFocusableComponent , getNextFocusableComponent , requestDefaultFocus , and isManagingFocus were used to manage the keyboard focus. These methods are now deprecated. Another method, requestFocus , is discouraged because it tries to give the focus to the component's window, which isn't always possible. As of v1.4, you should use requestFocusInWindow , which does not attempt to make the component's window focused and returns a boolean value indicating whether the method succeeded.

Introduction to the Focus Subsystem

The focus subsystem is designed to do the right thing as invisibly as possible. In most cases it behaves in a reasonable manner, and if it doesn't you can tweak it in various ways. Here are some common scenarios:

• The ordering is right but the first component with the focus isn't. As shown in the preceding code snippet, you can use requestFocusInWindow to set the focused component when the window becomes visible.

• The ordering is wrong. To fix this you can change the containment hierarchy, change the order in which the components are added to their containers, or create a custom focus traversal policy. For more details, see Customizing Focus Traversal (page 593).

• A component needs to be prevented from losing the focus, or you need to check a value in a component before it loses the focus. Validating Input (page 587) discusses a solution to this problem.

• A custom component isn't getting the focus. To fix this, you need to make sure that it satisfies all the requirements outlined in Making a Custom Component Focusable (page 592).

The FocusConceptsDemo example shown in Figure 25 illustrates a few concepts.

Figure 25. A screenshot of the FocusConceptsDemo example in which the second JButton has the focus.

Try This:

1. 

   Run FocusConceptsDemo using Java Web Start or compile and run the example yourself. ^[44]

   ^[44] To run FocusConceptsDemo using Java Web Start, click the FocusConceptsDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/misc/example-1dot4/index.html#FocusConceptsDemo .

2. Click the window, if necessary, to give it the focus.

3. Move the focus from component to component using the Tab key. Notice that when the focus moves into the text area, it stays there.

4. Move the focus out of the text area using Control-Tab.

5. Move the focus in the opposite direction using Shift-Tab.

6. Move the focus out of the text area in the opposite direction using Control-Shift-Tab.

At the heart of the focus subsystem is the KeyboardFocusManager , which manages state and initiates changes. The keyboard manager tracks the focus owner the component that receives typing from the keyboard. The focused window is the window that contains the focus owner.

Note: If you happen to use a JWindow in your GUI, you should know that JWindow 's owning frame must be visible for any components in the window to get the focus. By default, if you don't specify an owning frame for a JWindow , an invisible owning frame is created for it. The result is that components in JWindow s might not be able to get the focus. The solution is to either specify a visible owning frame when creating the JWindow , or use an undecorated JFrame instead of JWindow .

A focus cycle (or focus traversal cycle ) is a set of components that typically share a common ancestor in the containment hierarchy. The focus cycle root is the container that is the root for a particular focus traversal cycle. By default, every Window and JInternalFrame is a focus cycle root. Any Container (remember that all Swing components are containers) can be a focus cycle root as well; a focus cycle root can itself contain one or more focus cycle roots. The following Swing objects are focus cycle roots: JApplet , JDesktopPane , JDialog , JEditorPane , JFrame , JInternalFrame , and JWindow . While it might appear that JTable and JTree are focus cycle roots, they aren't.

A focus traversal policy determines the order in which a group of components are navigated. Swing provides the LayoutFocusTraversalPolicy ^[45] class, which decides the order of navigation based on layout manager-dependent factors such as size , location, and orientation of components. Within a focus cycle, components can be navigated in a forward or backward direction. In a hierarchy of focus cycle roots, upward traversal takes the focus out of the current cycle into the parent cycle.

^[45] LayoutFocusTraversalPolicy API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/LayoutFocusTraversalPolicy.html.

In most look and feels, components are navigated with the Tab and Shift-Tab keys. These are the default focus traversal keys and can be changed programmatically. You can, for example, add Enter as a forward focus traversal key with the following four lines of code:

 Set forwardKeys = getFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS); Set newForwardKeys = new HashSet(forwardKeys); newForwardKeys.add(KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, 0)); setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,                       newForwardKeys); 

Tab shifts the focus forward. Shift-Tab moves it backward. For example, in FocusConceptsDemo the first button has the initial focus. Tabbing moves the focus through the buttons into the text area. Additional tabbing moves the cursor within the text area but not out of it because inside a text area Tab is not a focus traversal key. However, Control-Tab moves the focus out of the text area and into the first text field. Likewise, Control-Shift-Tab moves the focus out of the text area and into the previous component. The Control key is used by convention to move the focus out of any component that treats Tab as special, such as JTable .

We've just given you a brief introduction to the focus architecture. If you want more details, see the specification for the Focus Subsystem at: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/doc-files/FocusSpec.html.

Validating Input

A common requirement of GUI design is a component that restricts the user's inputfor example, a text field that allows only numeric input in decimal format (e.g., money) or a text field that allows only 5 digits for a zip code. Release 1.4 provides an easy-to-use formatted text field component that allows input to be restricted to a variety of localizable formats. ^[46] You can also specify a custom formatter for the text field that can perform special checking such as determining whether values are not just formatted correctly but also whether they are reasonable.

^[46] See also How to Use Formatted Text Fields (page 221) in Chapter 7.

When you have a component that isn't a text field, or as an alternative to a custom formatter, you can use an input verifier. An input verifier allows you to reject specific values, such as a properly formatted but invalid zip code, or values outside of a desired range, such as a body temperature higher than 110F. To use it, create a subclass of InputVerifier ^[47] (a class introduced in release 1.3), create an instance of your subclass, and set the instance as the input verifier for one or more components.

^[47] InputVerifier API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/InputVerifier.html.

A component's input verifier is consulted whenever the component is about to lose the focus. If the component's value isn't acceptable, the input verifier can take appropriate action, such as refusing to yield the focus on the component or replacing the user's input with the last valid value and then allowing the focus to transfer to the next component.

Figures 26 and 27 show mortgage calculators . One uses input verification with standard text fields, and the other uses formatted text fields.

Figure 26. A screenshot of the InputVerificationDemo example.

Figure 27. A screenshot of the FormattedTextFieldDemo example.

Try This:

1. 

   Run InputVerificationDemo using Java Web Start or compile and run the example yourself. ^[48]

   ^[48] To run InputVerificationDemo using Java Web Start, click the InputVerificationDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/components/example-1dot4/index.html#InputVerificationDemo .

2. 

   Run FormattedTextFieldDemo using Java Web Start or compile and run the example yourself. ^[49]

   ^[49] To run FormattedTextFieldDemo using Java Web Start, click the FormattedTextFieldDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/components/example-1dot4/index.html#FormattedTextFieldDemo .

3. Compare the two mortgage calculators side by side. You'll see that the input verification demo specifies valid input values in the associated label for each editable text field. Try entering badly formatted values in both examples to observe behavior. Then try entering a properly formatted but unreasonable value.

You can find the code in InputVerificationDemo.java . Here's the code for the Input-Verifier subclass, MyVerifier :

 class MyVerifier extends InputVerifier implements ActionListener {     double MIN_AMOUNT = 10000.0;     double MAX_AMOUNT = 10000000.0;     double MIN_RATE = 0.0;     int MIN_PERIOD = 1;     int MAX_PERIOD = 40;    public boolean shouldYieldFocus(JComponent input) {         boolean inputOK = verify(input);         makeItPretty(input);         updatePayment();         if (inputOK) {             return true;         } else {             Toolkit.getDefaultToolkit().beep();             return false;         }     }     protected void updatePayment() {         double amount = DEFAULT_AMOUNT;         double rate = DEFAULT_RATE;         int numPeriods = DEFAULT_PERIOD;         double payment = 0.0;         //Parse the values.         try {             amount = moneyFormat.parse(amountField.getText()).                               doubleValue();         } catch (ParseException pe) {}         try {             rate = percentFormat.parse(rateField.getText()).                                  doubleValue();         } catch (ParseException pe) {}         try {             numPeriods =decimalFormat.parse(numPeriodsField.getText()).intValue();         } catch (ParseException pe) {}         //Calculate the result and update the GUI.         payment = computePayment(amount, rate, numPeriods);         paymentField.setText(paymentFormat.format(payment));     }     //This method checks input, but should cause no side effects.     public boolean verify(JComponent input) {         return checkField(input, false);     }     protected void makeItPretty(JComponent input) {         checkField(input, true);     }     protected boolean checkField(JComponent input, boolean changeIt) {         if (input == amountField) {             return checkAmountField(changeIt);         } else if (input == rateField) {             return checkRateField(changeIt);         } else if (input == numPeriodsField) {             return checkNumPeriodsField(changeIt);         } else {             return true; //shouldn't happen         }     }     //Checks that the amount field is valid.  If it is valid,     //it returns true; otherwise, returns false.  If the     //change argument is true, this method reigns in the     //value if necessary and (even if not) sets it to the     //parsed number so that it looks good--no letters,     //for example.     protected boolean checkAmountField(boolean change) {         boolean wasValid = true;         double amount = DEFAULT_AMOUNT;         //Parse the value.         try {             amount = moneyFormat.parse(amountField.getText()).                               doubleValue();         } catch (ParseException pe) {             wasValid = false;         }         //Value was invalid.         if ((amount < MIN_AMOUNT)  (amount > MAX_AMOUNT)) {             wasValid = false;             if (change) {                 if (amount < MIN_AMOUNT) {                     amount = MIN_AMOUNT;                 } else { // amount is greater than MAX_AMOUNT                     amount = MAX_AMOUNT;                 }             }         }         //Whether value was valid or not, format it nicely.         if (change) {             amountField.setText(moneyFormat.format(amount));             amountField.selectAll();         }         return wasValid;     }     //Checks that the rate field is valid.  If it is valid,     //it returns true; otherwise, returns false.  If the     //change argument is true, this method reigns in the     //value if necessary and (even if not) sets it to the     //parsed number so that it looks good--no letters,     //for example.     protected boolean checkRateField(boolean change) {  ...//Similar to checkAmountField...  }     //Checks that the numPeriods field is valid.  If it is valid,     //it returns true; otherwise, returns false.  If the     //change argument is true, this method reigns in the     //value if necessary and (even if not) sets it to the     //parsed number so that it looks good--no letters,     //for example.     protected boolean checkNumPeriodsField(boolean change) {  ...//Similar to checkAmountField...  }     public void actionPerformed(ActionEvent e) {         JTextField source = (JTextField)e.getSource();         shouldYieldFocus(source); //ignore return value         source.selectAll();     } } 

The verify method is implemented to detect invalid values and does nothing else. It exists only to determine whether the input is validit should never bring up a dialog or cause any other side effects. The shouldYieldFocus method calls verify and, if the values are invalid, reigns them in. This method is allowed to cause side effects; in this case, it always formats the text field and may also change its value. In our example, shouldYieldFocus always returns true so that the transfer of the focus is never actually prevented. This is just one way verification can be implemented. We've also provided a version of this demo called InputVerificationDialogDemo ^[50] that puts up a dialog when user input is invalid and requires the user to enter a legal value.

^[50] To run InputVerificationDialogDemo using Java Web Start, click the InputVerification-DialogDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/misc/example-1dot4/index.html#InputVerificationDialogDemo .

The input verifier is installed using the JComponent setInputVerifier method. For example, InputVerificationDemo has this code:

 private MyVerifier verifier = new MyVerifier(); .. amountField.setInputVerifier(verifier); 

Making a Custom Component Focusable

To gain the focus, a component must satisfy three requirements: It must be visible, enabled, and focusable. It's also likely that you'll want to give it an input map. If you don't know what an input map is, please read How to Use Key Bindings (page 623).

The TrackFocusDemo example defines the simple component Picture . The following is its constructor:

 public Picture(Image image) {     this.image = image;     setFocusable(true);     addMouseListener(this);     addFocusListener(this); } 

The call to setFocusable(true) makes the component focusable. If you explicitly give your component key bindings in its WHEN_FOCUSED input map, you don't need to call set-Focusable . To visually show changes in the focus (by painting a red border only when the component has the focus), Picture has a focus listener. To gain the focus when the user clicks on the picture, the component has a mouse listener. The listener's mouseClicked method requests that the focus be transferred to the picture. Here's the code:

 public void mouseClicked(MouseEvent e) {     //Since the user clicked on us, now get the focus!     requestFocusInWindow(); } 

See Tracking Focus Changes to Multiple Components (page 595) for more discussion of the TrackFocusDemo ^[51] example.

^[51] You can find the TrackFocusDemo source files here: JavaTutorial/uiswing/misc/example-1dot4/index.html#TrackFocusDemo .

Customizing Focus Traversal

The focus subsystem determines a default order that's used when the focus traversal keys (such as Tab) are used to navigate. A Swing application has its policy determined by LayoutFocusTraversalPolicy . You can set a focus traversal policy on any Container , though if the container isn't a focus cycle root it may have no apparent effect.

The FocusTraversalDemo example shown in Figure 28 demonstrates how to customize focus behavior.

Figure 28. A screenshot of the FocusTraversalDemo example.

Try This:

1. 

   Run FocusTraversalDemo using Java Web Start or compile and run the example yourself. ^[52]

   ^[52] To run FocusTraversalDemo using Java Web Start, click the FocusTraversalDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/misc/example-1dot4/index.html#FocusTraversalDemo .

2. Click the window, if necessary, to give it the focus.

3. Note the focus order as you tab through the components. The focus order was determined by the order that the components were added to the content pane. Note also that the check box never gets the focus; we removed it from the focus cycle.

4. To move the focus out of the table, use Control-Tab or Control-Shift-Tab.

5. Click the Custom FocusTraversalPolicy check box. This installs a custom focus traversal policy on the frame.

6. Try tabbing through the components again. Note that the focus order is now in numeric ( left-to-right , top-down) order.

The check box was removed from the focus cycle with this line of code:

 togglePolicy.setFocusable(false); 

Here's the application's custom FocusTraversalPolicy :

 ... JTextField tf1, tf2, tf3, tf4, tf5, tf6; JTable table; ... public class MyOwnFocusTraversalPolicy              extends FocusTraversalPolicy {     public Component getComponentAfter(Container focusCycleRoot,                                        Component aComponent) {         if (aComponent.equals(tf1)) {             return tf2;         } else if (aComponent.equals(tf2)) {             return tf3;         } else if (aComponent.equals(tf3)) {             return tf4;         } else if (aComponent.equals(tf4)) {             return tf5;         } else if (aComponent.equals(tf5)) {             return tf6;         } else if (aComponent.equals(tf6)) {             return table;         } else if (aComponent.equals(table)) {             return tf1;         }         return tf1;     }     public Component getComponentBefore(Container focusCycleRoot,                                         Component aComponent) {         if (aComponent.equals(tf1)) {             return table;         } else if (aComponent.equals(tf2)) {             return tf1;         } else if (aComponent.equals(tf3)) {             return tf2;         } else if (aComponent.equals(tf4)) {             return tf3;         } else if (aComponent.equals(tf5)) {             return tf4;         } else if (aComponent.equals(tf6)) {             return tf5;         } else if (aComponent.equals(table)) {             return tf6;         }         return tf1;     }     public Component getDefaultComponent(Container focusCycleRoot) {         return tf1;     }     public Component getLastComponent(Container focusCycleRoot) {         return table;     }     public Component getFirstComponent(Container focusCycleRoot) {         return tf1;     } } 

To use a custom FocusTraversalPolicy , use code like the following on any focus cycle root.

 MyOwnFocusTraversalPolicy newPolicy = new MyOwnFocusTraversalPolicy(); frame.setFocusTraversalPolicy(newPolicy); 

You can remove the policy by setting FocusTraversalPolicy to null. This restores the default policy.

Tracking Focus Changes to Multiple Components

In some situations an application may need to track which component has the focus. This information might be used to update menus or perhaps a status bar dynamically. If you need to track the focus only on specific components, it may make sense to implement a focus event listener. (See How to Write a Focus Listener (page 665) in Chapter 10.)

If a focus listener isn't appropriate, you can register a PropertyChangeListener on the KeyboardFocusManager . The property change listener is notified of every change involving the focus, including changes to the focus owner, the focused window, and the default focus traversal policy. For a complete list, see Table 17 (page 601).

Figure 29 shows TrackFocusDemo , which tracks the focus owner by installing a property change listener on the keyboard focus manager.

Figure 29. A screenshot of the TrackFocusDemo example.

Try This:

1. 

   Run TrackFocusDemo using Java Web Start or compile and run the example yourself. ^[53]

   ^[53] To run TrackFocusDemo using Java Web Start, click the TrackFocusDemo link on the RunExamples/misc.html page on the CD. You can find the source files here: JavaTutorial/uiswing/misc/example-1dot4/index.html#TrackFocusDemo .

2. Click the window, if necessary, to give it the focus.

3. The window shows six images, each one displayed by a Picture component. The Picture that has the focus is indicated with a red border. A label at the bottom of the window describes that Picture .

4. Move the focus to another Picture by tabbing, Shift-tabbing, or clicking an image. Because a property change listener has been registered on the keyboard focus manager, the change in focus is detected and the label is updated appropriately.

You can view the demo's code in TrackFocusDemo.java . The custom component used for painting the images is in Picture.java . Here's the code that defines and installs the property change listener:

 KeyboardFocusManager focusManager =     KeyboardFocusManager.getCurrentKeyboardFocusManager(); focusManager.addPropertyChangeListener(new PropertyChangeListener() {         public void propertyChange(PropertyChangeEvent e) {             String prop = e.getPropertyName();             if (("focusOwner".equals(prop)) &&                   (e.getNewValue() != null) &&                   ((e.getNewValue()) instanceof Picture)) {                 Component comp = (Component)e.getNewValue();                 String name = comp.getName();                 Integer num = new Integer(name);                 int index = num.intValue();                 if (index < 0  index > comments.length) {                     index = 0;                 }                 info.setText(comments[index]);             }         }     }); 

The custom component, Picture , is responsible for painting the image. All six components are defined in the following manner:

 pic1 = new Picture(createImageIcon("images/" +             mayaString + ".gif", mayaString).getImage()); pic1.setName("1"); 

Timing Focus Transfers

Focus transfers are asynchronous, which can lead to some odd timing- related problems and assumptions, especially during automatic transfers of the focus. Imagine an application with a window containing a Start button, a Cancel button, and a text field. The components are added in this order:

1. Start button

2. Text field

3. Cancel button

When an application is launched, the LayoutFocusTraversalPolicy determines the focus traversal policyin this case, it's the order in which the components were added to their container. In this example, the desired behavior is that the Start button have the initial focus; when it's clicked, it's disabled and the Cancel button gets the focus. The correct way to implement this is to add the components to the container in the desired order or to create a custom focus traversal policy. If, for some reason, this isn't possible, the way to implement this is with the following code snippet:

 public void actionPerformed(ActionEvent e) {     //This works.     start.setEnabled(false);     cancel.requestFocusInWindow(); } 

As desired, the focus goes from the Start button to the Cancel button rather than to the text field. But a different result occurs if the same methods are called in the opposite order, like this:

 public void actionPerformed(ActionEvent e) {     //This doesn't work.     cancel.requestFocusInWindow();     start.setEnabled(false); } 

In this case, the focus is requested on the Cancel button before it has left the Start button. The call to requestFocusInWindow initiates the transfer, but doesn't immediately move the focus to the Cancel button. When the Start button is disabled, the focus is transferred to the next component (so there's always a component with the focus) and, in this case, it then moves the focus to the text field, not the Cancel button.

The need to make focus requests after all other changes that might affect the focus applies to

• Hiding the focus owner

• Making the focus owner nonfocusable

• Calling removeNotify on the focus owner

• Doing any of the above to the container of the focus owner, or causing changes to the focus policy so that the container no longer accepts the component as the focus owner

• Disposing of the top-level window that contains the focus owner

The Focus API

Tables 15 and 16 list the commonly used constructors and methods related to focus. Table 17 defines the bound properties for KeyboardFocusManager . A listener can be registered for these properties by calling addPropertyChangeListener . For more detailed information about the focus architecture, see the specification for the Focus Subsystem online at: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/doc-files/FocusSpec.html. In addition, you may find How to Write a Focus Listener (page 665) in Chapter 10 useful. You should also refer to the API documentation for LayoutFocusTraversalPolicy , SortingFocusTraversalPolicy , InputVerifier , and KeyboardFocusManager at:

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/LayoutFocus-TraversalPolicy.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/SortingFocus-TraversalPolicy.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/InputVerifier.html

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/KeyboardFocus-Manager.html

Table 15. Useful Methods for Components (This API was introduced in release 1.4.)

Method (in Component )	Purpose
isFocusOwner()	Return true if the component is the focus owner. This method, introduced in release 1.4, makes hasFocus obsolete.
setFocusable(boolean) isFocusable()	Set or get the focusable state of the component. A component must be focusable in order to gain focus. When a component has been removed from the focus cycle with setFocusable(false) , it can no longer be navigated with the keyboard. We prefer setRequestFocusEnabled so that your program can be run by users employing assistive technologies.
requestFocusInWindow()	Request that this component gets the focus. The component's window must be the current focused window. A subclass of JComponent must be visible, enabled, and focusable, and have an input map for this request to be granted. Don't assume that the component has focus until it fires a FOCUS_GAINED event. This method is preferred to requestFocus , which is platform- dependent.
setFocusTraversalKeys(int, Set) getFocusTraversalKeys(int) areFocusTraversalKeysSet(int) ( in java.awt.Container)	Set or get the focus traversal keys for a particular direction or determine whether any focus traversal keys have been explicitly set on this container. If no focus traversal keys have been set, they are inherited from an ancestor or from the keyboard focus manager. Focus traversal keys can be set for these directions: KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS , KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS , KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS , or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS . If you set the UP_CYCLE_TRAVERSAL_KEYS or the DOWN_CYCLE_TRAVERSAL_KEYS , you must also invoke setImplicitDown-CycleTraversal(false) on the focus traversal policy.

Table 16. Creating and Using a Custom FocusTraversalPolicy (This API was introduced in release 1.4. Unless otherwise specified, each method is defined in the FocusTraversalPolicy interface.)

Class or Method	Purpose
LayoutFocusTraversalPolicy	By default, determine the focus traversal policy for Swing components.
getComponentAfter(Container, Component)	Given the component passed in, return the component that should have the focus next.
getComponentBefore(Container, Component)	Given the component passed in, return the component that should have the focus before this one. This is used for backward tabbing.
getDefaultComponent(Container) ( in javax.swing.SortingFocusTraversalPolicy )	Return the component that should have the default focus.
GetFirstComponent(Container)	Return the first component in the traversal cycle.
getInitialComponent(Container)	Return the component that should receive the focus when a window is first made visible.
getLastComponent(Container)	Return the last component in the traversal cycle.
setFocusTraversalPolicy(FocusTraversalPolicy) getFocusTraversalPolicy(FocusTraversalPolicy) isFocusTraversalPolicySet() ( in java.awt.Container)	Set or get the focus traversal policy or determine if one has been set. Note that setting a focus traversal policy on a container not the focus cycle root may have no apparent effect. A value of null means that a policy hasn't been explicitly set. If no policy has been set, one is inherited from the parent focus cycle root.

Table 17. KeyboardFocusManager Properties This API was introduced in release 1.4.

Property	Purpose
focusOwner	The component that currently receives key events.
permanentFocusOwner	The component that most recently received a permanent FOCUS_GAINED event. Typically the same as focusOwner , unless a temporary focus change is currently in effect.
focusedWindow	The window that is or that contains the focus owner.
activeWindow	Always either a Frame or a Dialog . The active window is either the focused window or the first frame or dialog that is an owner of the focused window.
defaultFocusTraversalPolicy	The default focus traversal policy. Can be set by the Container setFocusTraversalPolicy method.
forwardDefaultFocusTraversalKeys	The set of default focus keys for a forward traversal. For multi-line text components, defaults to Control-Tab. For all other components, this defaults to Tab and Control-Tab.
backwardDefaultFocusTraversalKeys	The set of default focus keys for a backward traversal. For multi-line text components, defaults to Control-Shift-Tab. For all other components, defaults to Shift-Tab and Control-Shift-Tab.
upCycleDefaultFocusTraversalKeys	The set of default focus keys for an up cycle. These are null, by default, for Swing components. If you set these keys on the KeyboardFocusManager , or if you set the downCycleFocusTraversalKeys on a focus cycle root, you must also invoke setImplicitDownCycleTraversal(false) on the focus traversal policy.
downCycleDefaultFocusTraversalKeys	The set of default focus keys for a down cycle. These are null, by default, for Swing components. If you set these keys on the KeyboardFocusManager , or if you set the upCycleFocusTraversalKeys on a focus cycle root, you must also invoke setImplicitDownCycleTraversal(false) on the focus traversal policy.
currentFocusCycleRoot	The container that is the current focus cycle root.

Examples That Use Focus

The following table lists examples that manipulate the focus.

Example	Where Described	Notes
FocusConceptsDemo	This section (page 584)	Demonstrates basic default focus behavior.
FocusTraversalDemo	This section (page 593)	Demonstrates how to override the default focus order.
TrackFocusDemo	This section (page 592) and (page 595)	Demonstrates how to use a PropertyChangeListener to track the focus owner. Also implements a custom focusable component.
InputVerificationDemo	This section (page 587)	Demonstrates how to implement an Input- Verifier to validate user input.
InputVerificationDialogDemo	This section (page 587)	Demonstrates how to implement an Input- Verifier that puts up a dialog when user input is invalid.
FocusEventDemo	How to Write a Focus Listener (page 665)	Reports all focus events that occur on several components to demonstrate the circumstances under which focus events are fired .