1 /*
   2  * Copyright (c) 2010, 2014, 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 javafx.scene.control;
  27 
  28 import javafx.beans.property.ReadOnlyIntegerProperty;
  29 import javafx.beans.property.ReadOnlyIntegerWrapper;
  30 import javafx.beans.property.ReadOnlyObjectProperty;
  31 import javafx.beans.property.ReadOnlyObjectWrapper;
  32 
  33 /**
  34  * The abstract base class for FocusModel implementations.
  35  * @since JavaFX 2.0
  36  */
  37 public abstract class FocusModel<T> {
  38 
  39     /***********************************************************************
  40      *                                                                     *
  41      * Constructors                                                        *
  42      *                                                                     *
  43      **********************************************************************/
  44 
  45     /**
  46      * Creates a default FocusModel instance.
  47      */
  48     public FocusModel() {
  49         focusedIndexProperty().addListener(valueModel -> {
  50             // we used to lazily retrieve the focused item, but now we just
  51             // do it when the focused index changes.
  52             setFocusedItem(getModelItem(getFocusedIndex()));
  53         });
  54     }
  55 
  56 
  57 
  58     /***************************************************************************
  59      *                                                                         *
  60      * Focus Properties                                                        *
  61      *                                                                         *
  62      **************************************************************************/
  63 
  64     /**
  65      * The index of the current item in the FocusModel which has the focus. It
  66      * is possible that this will be -1, but only if the control is empty.
  67      * If the control is not itself focused, this property will still
  68      * reference the row index that would receive the keyboard focus if the control
  69      * itself were focused.
  70      */
  71     private ReadOnlyIntegerWrapper focusedIndex = new ReadOnlyIntegerWrapper(this, "focusedIndex", -1);
  72     public final ReadOnlyIntegerProperty focusedIndexProperty() { return focusedIndex.getReadOnlyProperty();  }
  73     public final int getFocusedIndex() { return focusedIndex.get(); }
  74     final void setFocusedIndex(int value) { focusedIndex.set(value); }
  75 
  76 
  77 
  78     /**
  79      * The current item in the FocusModel which has the focus. It
  80      * is possible that this will be null, but only if the control is empty.
  81      * If the control is not itself focused, this property will still
  82      * reference the item that would receive the keyboard focus if the control
  83      * itself were focused.
  84      */
  85     private ReadOnlyObjectWrapper<T> focusedItem = new ReadOnlyObjectWrapper<T>(this, "focusedItem");
  86     public final ReadOnlyObjectProperty<T> focusedItemProperty() { return focusedItem.getReadOnlyProperty(); }
  87     public final T getFocusedItem() { return focusedItemProperty().get(); }
  88     final void setFocusedItem(T value) { focusedItem.set(value); }
  89 
  90 
  91 
  92     /***********************************************************************
  93      *                                                                     *
  94      * Public Focus API                                                    *
  95      *                                                                     *
  96      **********************************************************************/
  97 
  98 
  99     /**
 100      * Returns the number of items in the data model that underpins the control.
 101      * An example would be that a ListView focus model would likely return
 102      * <code>listView.getItems().size()</code>. The valid range of focusable
 103      * indices is between 0 and whatever is returned by this method.
 104      */
 105     protected abstract int getItemCount();
 106 
 107     /**
 108      * Returns the item at the given index. An example using ListView would be
 109      * <code>listView.getItems().get(index)</code>.
 110      *
 111      * @param index The index of the item that is requested from the underlying
 112      *      data model.
 113      * @return Returns null if the index is out of bounds, or an element of type
 114      *      T that is related to the given index.
 115      */
 116     protected abstract T getModelItem(int index);
 117 
 118     /**
 119      * <p>Convenience method to inform if the given index is currently focused
 120      * in this SelectionModel. Is functionally equivalent to calling
 121      * <pre><code>getFocusedIndex() == index</code></pre>.
 122      *
 123      * @param index The index to check as to whether it is currently focused
 124      *      or not.
 125      * @return True if the given index is focused, false otherwise.
 126      */
 127     public boolean isFocused(int index) {
 128         if (index < 0 || index >= getItemCount()) return false;
 129 
 130         return getFocusedIndex() == index;
 131     }
 132 
 133     /**
 134      * Causes the item at the given index to receive the focus. This does not
 135      * cause the current selection to change. Updates the focusedItem and
 136      * focusedIndex properties such that <code>focusedIndex = -1</code> unless
 137      * <code>0 &lt;= index &lt; model size</code>.
 138      *
 139      * @param index The index of the item to get focus.
 140      */
 141     public void focus(int index) {
 142         if (index < 0 || index >= getItemCount()) {
 143             setFocusedIndex(-1);
 144         } else {
 145             int oldFocusIndex = getFocusedIndex();
 146             setFocusedIndex(index);
 147 
 148             if (oldFocusIndex == index) {
 149                 // manually update the focus item to ensure consistency
 150                 setFocusedItem(getModelItem(index));
 151             }
 152         }
 153     }
 154 
 155     /**
 156      * Attempts to give focus to the row previous to the currently focused row.
 157      * If the current focus owner is the first row, or is -1 (representing that
 158      * there is no current focus owner), calling this method will have no result.
 159      */
 160     public void focusPrevious() {
 161         if (getFocusedIndex() == -1) {
 162             focus(0);
 163         } else if (getFocusedIndex() > 0) {
 164             focus(getFocusedIndex() - 1);
 165         }
 166     }
 167 
 168     /**
 169      * Attempts to give focus to the row after to the currently focused row.
 170      * If the current focus owner is the last row, calling this method will have
 171      * no result.
 172      */
 173     public void focusNext() {
 174         if (getFocusedIndex() == -1) {
 175             focus(0);
 176         } else if (getFocusedIndex() != getItemCount() -1) {
 177             focus(getFocusedIndex() + 1);
 178         }
 179     }
 180 }