001/*
002 * $Id: AbstractAutoCompleteAdaptor.java 4045 2011-07-19 18:39:17Z kschaefe $
003 *
004 * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
005 * Santa Clara, California 95054, U.S.A. All rights reserved.
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 * 
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 * Lesser General Public License for more details.
016 * 
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this library; if not, write to the Free Software
019 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
020 */
021package org.jdesktop.swingx.autocomplete;
022
023import javax.swing.text.JTextComponent;
024
025/**
026 * This is the interface that binds the mechanism for automatic completion to
027 * a data model, a selection model (e.g. those used by JList, JComboBox and JTable)
028 * and the JTextComponent for which the automatic completion should happen.
029 * It is used to search and select a matching item and to mark the completed text
030 * inside the JTextComponent. Using this interface the mechanism for automatic
031 * completion is independent from the underlying data and selection model.
032 *
033 * @see ComboBoxAdaptor
034 * @see ListAdaptor
035 *
036 * @author Thomas Bierhance
037 */
038public abstract class AbstractAutoCompleteAdaptor {
039    
040    /** the string representation in use for the currently selected item*/
041    private String selectedItemAsString;
042    
043    /**
044     * Returns the currently selected item.
045     * @return the selected item
046     */
047    public abstract Object getSelectedItem();
048    
049    /**
050     * Sets the selected item.
051     * @param item the item that is to be selected
052     */
053    public abstract void setSelectedItem(Object item);
054    
055    /**
056     * Returns the string representation in use for the currently selected item.
057     * @return the string representation in use for the currently selected item
058     */
059    public String getSelectedItemAsString() {
060        return this.selectedItemAsString;
061    }
062    
063    /**
064     * Sets the string representation in use for the currently selected item.
065     * @param itemAsString the string representation in use for the currently selected item
066     */
067    public void setSelectedItemAsString(String itemAsString) {
068        this.selectedItemAsString = itemAsString;
069    }
070
071    /**
072     * Returns the number of items in the list.
073     * @return the number of items in the list
074     */
075    public abstract int getItemCount();
076    
077    /**
078     * Returns the item at a given index. It is supposed that <code>0&lt;=index&lt;<b>getItemCount()</b></code>.
079     * @param index the index of the item that is to be returned
080     * @return the item at the given <code>index</code>
081     */
082    public abstract Object getItem(int index);
083    
084    /**
085     * Returns true if the list contains the currently selected item.
086     * @return true if the list contains the currently selected item.
087     */
088    public boolean listContainsSelectedItem() {
089        Object selectedItem = getSelectedItem();
090        for (int i=0,n=getItemCount(); i<n; i++) {
091            if (getItem(i)==selectedItem) return true;
092        }
093        return false;
094    }
095    
096    /**
097     * Returns the text component that is being used for the automatic completion.
098     * @return the text component being used for the automatic completion
099     */
100    public abstract JTextComponent getTextComponent();
101    
102    /**
103     * Marks/selects the entire text that is displayed inside the text component.
104     */
105    public void markEntireText() {
106        markText(0);
107    }
108    
109    /**
110     * Marks/selects the text that is displayed inside the text component starting from the
111     * character with index <tt>start</tt>.
112     * @param start index of the first character that should be marked
113     */
114    public void markText(int start) {
115        getTextComponent().setCaretPosition(getTextComponent().getText().length());
116        getTextComponent().moveCaretPosition(start);
117    }
118}