Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 2000, 2005, 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   package java.awt;
   26   
   27   /**
   28    * A FocusTraversalPolicy defines the order in which Components with a
   29    * particular focus cycle root are traversed. Instances can apply the policy to
   30    * arbitrary focus cycle roots, allowing themselves to be shared across
   31    * Containers. They do not need to be reinitialized when the focus cycle roots
   32    * of a Component hierarchy change.
   33    * <p>
   34    * The core responsibility of a FocusTraversalPolicy is to provide algorithms
   35    * determining the next and previous Components to focus when traversing
   36    * forward or backward in a UI. Each FocusTraversalPolicy must also provide
   37    * algorithms for determining the first, last, and default Components in a
   38    * traversal cycle. First and last Components are used when normal forward and
   39    * backward traversal, respectively, wraps. The default Component is the first
   40    * to receive focus when traversing down into a new focus traversal cycle.
   41    * A FocusTraversalPolicy can optionally provide an algorithm for determining
   42    * a Window's initial Component. The initial Component is the first to receive
   43    * focus when a Window is first made visible.
   44    * <p>
   45    * FocusTraversalPolicy takes into account <a
   46    * href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
   47    * policy providers</a>.  When searching for first/last/next/previous Component,
   48    * if a focus traversal policy provider is encountered, its focus traversal
   49    * policy is used to perform the search operation.
   50    * <p>
   51    * Please see
   52    * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">
   53    * How to Use the Focus Subsystem</a>,
   54    * a section in <em>The Java Tutorial</em>, and the
   55    * <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
   56    * for more information.
   57    *
   58    * @author David Mendenhall
   59    *
   60    * @see Container#setFocusTraversalPolicy
   61    * @see Container#getFocusTraversalPolicy
   62    * @see Container#setFocusCycleRoot
   63    * @see Container#isFocusCycleRoot
   64    * @see Container#setFocusTraversalPolicyProvider
   65    * @see Container#isFocusTraversalPolicyProvider
   66    * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
   67    * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
   68    * @since 1.4
   69    */
   70   public abstract class FocusTraversalPolicy {
   71   
   72       /**
   73        * Returns the Component that should receive the focus after aComponent.
   74        * aContainer must be a focus cycle root of aComponent or a focus traversal
   75        * policy provider.
   76        *
   77        * @param aContainer a focus cycle root of aComponent or focus traversal
   78        *        policy provider
   79        * @param aComponent a (possibly indirect) child of aContainer, or
   80        *        aContainer itself
   81        * @return the Component that should receive the focus after aComponent, or
   82        *         null if no suitable Component can be found
   83        * @throws IllegalArgumentException if aContainer is not a focus cycle
   84        *         root of aComponent or a focus traversal policy provider, or if
   85        *         either aContainer or aComponent is null
   86        */
   87       public abstract Component getComponentAfter(Container aContainer,
   88                                                   Component aComponent);
   89   
   90       /**
   91        * Returns the Component that should receive the focus before aComponent.
   92        * aContainer must be a focus cycle root of aComponent or a focus traversal
   93        * policy provider.
   94        *
   95        * @param aContainer a focus cycle root of aComponent or focus traversal
   96        *        policy provider
   97        * @param aComponent a (possibly indirect) child of aContainer, or
   98        *        aContainer itself
   99        * @return the Component that should receive the focus before aComponent,
  100        *         or null if no suitable Component can be found
  101        * @throws IllegalArgumentException if aContainer is not a focus cycle
  102        *         root of aComponent or a focus traversal policy provider, or if
  103        *         either aContainer or aComponent is null
  104        */
  105       public abstract Component getComponentBefore(Container aContainer,
  106                                                    Component aComponent);
  107   
  108       /**
  109        * Returns the first Component in the traversal cycle. This method is used
  110        * to determine the next Component to focus when traversal wraps in the
  111        * forward direction.
  112        *
  113        * @param aContainer the focus cycle root or focus traversal policy provider
  114        *        whose first Component is to be returned
  115        * @return the first Component in the traversal cycle of aContainer,
  116        *         or null if no suitable Component can be found
  117        * @throws IllegalArgumentException if aContainer is null
  118        */
  119       public abstract Component getFirstComponent(Container aContainer);
  120   
  121       /**
  122        * Returns the last Component in the traversal cycle. This method is used
  123        * to determine the next Component to focus when traversal wraps in the
  124        * reverse direction.
  125        *
  126        * @param aContainer the focus cycle root or focus traversal policy
  127        *        provider whose last Component is to be returned
  128        * @return the last Component in the traversal cycle of aContainer,
  129        *         or null if no suitable Component can be found
  130        * @throws IllegalArgumentException if aContainer is null
  131        */
  132       public abstract Component getLastComponent(Container aContainer);
  133   
  134       /**
  135        * Returns the default Component to focus. This Component will be the first
  136        * to receive focus when traversing down into a new focus traversal cycle
  137        * rooted at aContainer.
  138        *
  139        * @param aContainer the focus cycle root or focus traversal policy
  140        *        provider whose default Component is to be returned
  141        * @return the default Component in the traversal cycle of aContainer,
  142        *         or null if no suitable Component can be found
  143        * @throws IllegalArgumentException if aContainer is null
  144        */
  145       public abstract Component getDefaultComponent(Container aContainer);
  146   
  147       /**
  148        * Returns the Component that should receive the focus when a Window is
  149        * made visible for the first time. Once the Window has been made visible
  150        * by a call to <code>show()</code> or <code>setVisible(true)</code>, the
  151        * initial Component will not be used again. Instead, if the Window loses
  152        * and subsequently regains focus, or is made invisible or undisplayable
  153        * and subsequently made visible and displayable, the Window's most
  154        * recently focused Component will become the focus owner. The default
  155        * implementation of this method returns the default Component.
  156        *
  157        * @param window the Window whose initial Component is to be returned
  158        * @return the Component that should receive the focus when window is made
  159        *         visible for the first time, or null if no suitable Component can
  160        *         be found
  161        * @see #getDefaultComponent
  162        * @see Window#getMostRecentFocusOwner
  163        * @throws IllegalArgumentException if window is null
  164        */
  165       public Component getInitialComponent(Window window) {
  166           if ( window == null ){
  167               throw new IllegalArgumentException("window cannot be equal to null.");
  168           }
  169           Component def = getDefaultComponent(window);
  170           if (def == null && window.isFocusableWindow()) {
  171               def = window;
  172           }
  173           return def;
  174       }
  175   }

Home » openjdk-7 » java » awt » [javadoc | source]