Added source for ByteEdit

src/org/fife/ui/autocomplete/CompletionProvider.java

@@ -0,0 +1,213 @@
+/*
+ * 12/21/2008
+ *
+ * CompletionProvider.java - Provides autocompletion values based on the
+ * text currently in a text component.
+ * 
+ * This library is distributed under a modified BSD license.  See the included
+ * AutoComplete.License.txt file for details.
+ */
+package org.fife.ui.autocomplete;
+
+import java.awt.Point;
+import java.util.List;
+
+import javax.swing.ListCellRenderer;
+import javax.swing.text.JTextComponent;
+
+
+/**
+ * Provides autocompletion values to an {@link AutoCompletion}.<p>
+ *
+ * Completion providers can have an optional parent.  Parents are searched for
+ * completions when their children are.  This allows for chaining of completion
+ * providers.
+ *
+ * @author Robert Futrell
+ * @version 1.0
+ */
+public interface CompletionProvider {
+
+
+	/**
+	 * Clears the values used to identify and insert "parameterized completions"
+	 * (e.g. functions or methods).  After this method is called, functions and
+	 * methods will not have their parameters auto-completed.
+	 *
+	 * @see #setParameterizedCompletionParams(char, String, char)
+	 */
+	public void clearParameterizedCompletionParams();
+
+
+	/**
+	 * Returns the text just before the current caret position that could be
+	 * the start of something auto-completable.
+	 *
+	 * @param comp The text component.
+	 * @return The text.  A return value of <code>null</code> means nothing
+	 *         should be auto-completed; a value of an empty string
+	 *         (<code>""</code>) means auto-completion should still be
+	 *         considered (i.e., all possible choices are valid).
+	 */
+	public String getAlreadyEnteredText(JTextComponent comp);
+
+
+	/**
+	 * Gets the possible completions for the text component at the current
+	 * caret position.
+	 *
+	 * @param comp The text component.
+	 * @return The list of {@link Completion}s.  If no completions are
+	 *         available, this method should return an empty list.
+	 */
+	public List<Completion> getCompletions(JTextComponent comp);
+
+
+	/**
+	 * Returns the completions that have been entered at the specified visual
+	 * location.  This can be used for tool tips when the user hovers the
+	 * mouse over completed text.
+	 * 
+	 * @param comp The text component.
+	 * @param p The position, usually from a <tt>MouseEvent</tt>.
+	 * @return The completions, or an empty list if there are none.
+	 */
+	public List<Completion> getCompletionsAt(JTextComponent comp, Point p);
+
+
+	/**
+	 * Returns the cell renderer for completions returned from this provider.
+	 *
+	 * @return The cell renderer, or <code>null</code> if the default should
+	 *         be used.
+	 * @see #setListCellRenderer(ListCellRenderer)
+	 */
+	public ListCellRenderer getListCellRenderer();
+
+
+	/**
+	 * Returns an object that can return a list of completion choices for
+	 * parameters.  This is used when a user code-completes a parameterized
+	 * completion, such as a function or method.  For any parameter to the
+	 * function/method, this object can return possible completions.
+	 *
+	 * @return The parameter choices provider, or <code>null</code> if
+	 *         none is installed.
+	 */
+	public ParameterChoicesProvider getParameterChoicesProvider();
+
+
+	/**
+	 * Returns a list of parameterized completions that have been entered
+	 * at the current caret position of a text component (and thus can have
+	 * their completion choices displayed).
+	 * 
+	 * @param tc The text component.
+	 * @return The list of {@link ParameterizedCompletion}s.  If no completions
+	 *         are available, this may be <code>null</code>.
+	 */
+	public List<ParameterizedCompletion> getParameterizedCompletions(JTextComponent tc);
+
+
+	/**
+	 * Returns the text that marks the end of a list of parameters to a
+	 * function or method.
+	 *
+	 * @return The text for a parameter list end, for example,
+	 *         '<code>)</code>'.
+	 * @see #getParameterListStart()
+	 * @see #getParameterListSeparator()
+	 * @see #setParameterizedCompletionParams(char, String, char)
+	 */
+	public char getParameterListEnd();
+
+
+	/**
+	 * Returns the text that separates parameters to a function or method.
+	 *
+	 * @return The text that separates parameters, for example,
+	 *         "<code>, </code>".
+	 * @see #getParameterListStart()
+	 * @see #getParameterListEnd()
+	 * @see #setParameterizedCompletionParams(char, String, char)
+	 */
+	public String getParameterListSeparator();
+
+
+	/**
+	 * Returns the text that marks the start of a list of parameters to a
+	 * function or method.
+	 *
+	 * @return The text for a parameter list start, for example,
+	 *         "<code>(</code>".
+	 * @see #getParameterListEnd()
+	 * @see #getParameterListSeparator()
+	 * @see #setParameterizedCompletionParams(char, String, char)
+	 */
+	public char getParameterListStart();
+
+
+	/**
+	 * Returns the parent completion provider.
+	 *
+	 * @return The parent completion provider.
+	 * @see #setParent(CompletionProvider)
+	 */
+	public CompletionProvider getParent();
+
+
+	/**
+	 * This method is called if auto-activation is enabled in the parent
+	 * {@link AutoCompletion} after the user types a single character.  This
+	 * provider should check the text at the current caret position of the
+	 * text component, and decide whether auto-activation would be appropriate
+	 * here.  For example, a <code>CompletionProvider</code> for Java might
+	 * want to return <code>true</code> for this method only if the last
+	 * character typed was a '<code>.</code>'.
+	 *
+	 * @param tc The text component.
+	 * @return Whether auto-activation would be appropriate.
+	 */
+	public boolean isAutoActivateOkay(JTextComponent tc);
+
+
+	/**
+	 * Sets the renderer to use when displaying completion choices.
+	 *
+	 * @param r The renderer to use.
+	 * @see #getListCellRenderer()
+	 */
+	public void setListCellRenderer(ListCellRenderer r);
+
+
+	/**
+	 * Sets the values used to identify and insert "parameterized completions"
+	 * (e.g. functions or methods).  If this method isn't called, functions
+	 * and methods will not have their parameters auto-completed.
+	 *
+	 * @param listStart The character that marks the beginning of a list of
+	 *        parameters, such as '<tt>(</tt>' in C or Java.
+	 * @param separator Text that should separate parameters in a parameter
+	 *        list when one is inserted.  For example, "<tt>, </tt>".
+	 * @param listEnd The character that marks the end of a list of parameters,
+	 *        such as '<tt>)</tt>' in C or Java.
+	 * @throws IllegalArgumentException If either <tt>listStart</tt> or
+	 *         <tt>listEnd</tt> is not printable ASCII, or if
+	 *         <tt>separator</tt> is <code>null</code> or an empty string.
+	 * @see #clearParameterizedCompletionParams()
+	 */
+	public void setParameterizedCompletionParams(char listStart,
+										String separator, char listEnd);
+
+
+	/**
+	 * Sets the parent completion provider.
+	 *
+	 * @param parent The parent provider.  <code>null</code> means there will
+	 *        be no parent provider.
+	 * @see #getParent()
+	 */
+	public void setParent(CompletionProvider parent);
+
+
+}