View Javadoc

1   /*
2    *  XNap Commons
3    *
4    *  Copyright (C) 2005  Felix Berger
5    *
6    *  This library is free software; you can redistribute it and/or
7    *  modify it under the terms of the GNU Lesser General Public
8    *  License as published by the Free Software Foundation; either
9    *  version 2.1 of the License, or (at your option) any later version.
10   *
11   *  This library is distributed in the hope that it will be useful,
12   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   *  Lesser General Public License for more details.
15   *
16   *  You should have received a copy of the GNU Lesser General Public
17   *  License along with this library; if not, write to the Free Software
18   *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   */
20  package org.xnap.commons.gui.completion;
21  
22  import javax.swing.MutableComboBoxModel;
23  
24  /***
25   * Defines the requirements for classes implementing a CompletionModel.
26   * <p>
27   * The completion model can be queried for possible completions of a given
28   * <code>prefix</code>. There are two methods a CompletionModel has to
29   * implement:
30   * <ul>
31   * <li>complete - Find all possible completions for a given prefix and add
32   * them as a side effect to the MutableComboboxModel using {@link
33   * #addElement(Object)}.</li>
34   * <li>completeUniquePrefix - Find the largest common prefix of all possible
35   * completions and return it.</li>
36   * </ul>
37   * 
38   * The completion model interface inherits MutableComoboxModel so that
39   * possible {@link CompletionMode CompletionModes} can use it as the model for
40   * a comobobox.
41   * 
42   * @author Felix Berger
43   */
44  public interface CompletionModel extends MutableComboBoxModel
45  {
46  	/***
47  	 * Finds possible completions for a prefix.
48  	 *
49  	 * As a side effect the completions are added to the {@link
50  	 * MutableComboBoxModel}. Use {@link #getSize()} to get the number of
51  	 * completions found and retrieve them with {@link #getElementAt(int)}. 
52  	 *
53  	 * @param prefix the prefix being matched
54  	 * @return true, if completion was successful, i.e. the prefix matches 
55  	 * at least one item in the model
56  	 */
57  	boolean complete(String prefix);
58  
59  	/***
60  	 * Returns largest common prefix of all possible completions for the given
61  	 * prefix.
62  	 *
63  	 * @param prefix the prefix being matched
64  	 * @return the largest common prefix of all possible matches, the prefix
65  	 * given if no longer prefix can be found
66  	 */
67  	String completeUniquePrefix(String prefix);
68  
69  }