[autocomplete] 14/143: Lots of Javadoc improvements. Fixed a bug preventing "standard" cell rendering from working.
Benjamin Mesing
ben at alioth.debian.org
Sat Oct 19 12:53:09 UTC 2013
This is an automated email from the git hooks/post-receive script.
ben pushed a commit to branch master
in repository autocomplete.
commit b3ab23dfb2f752b045a38d76017d434180f16e62
Author: bobbylight <robert at fifesoft.com>
Date: Tue Jan 20 23:38:27 2009 +0000
Lots of Javadoc improvements. Fixed a bug preventing "standard" cell rendering from working.
---
.../fife/ui/autocomplete/AbstractCompletion.java | 14 +++-
.../ui/autocomplete/AutoCompletePopupWindow.java | 83 ++++++++++++++++----
src/org/fife/ui/autocomplete/AutoCompletion.java | 1 -
src/org/fife/ui/autocomplete/BasicCompletion.java | 55 +++++++++----
src/org/fife/ui/autocomplete/Completion.java | 17 +++-
.../fife/ui/autocomplete/CompletionXMLParser.java | 4 +-
.../ui/autocomplete/DefaultCompletionProvider.java | 6 +-
.../ui/autocomplete/DelegatingCellRenderer.java | 1 +
.../fife/ui/autocomplete/FunctionCompletion.java | 5 +-
.../ui/autocomplete/ParameterizedCompletion.java | 2 +-
.../fife/ui/autocomplete/ShorthandCompletion.java | 16 +++-
src/org/fife/ui/autocomplete/Util.java | 2 +-
.../fife/ui/autocomplete/VariableCompletion.java | 72 ++++++-----------
13 files changed, 185 insertions(+), 93 deletions(-)
diff --git a/src/org/fife/ui/autocomplete/AbstractCompletion.java b/src/org/fife/ui/autocomplete/AbstractCompletion.java
index bc0dbd9..4faf659 100644
--- a/src/org/fife/ui/autocomplete/AbstractCompletion.java
+++ b/src/org/fife/ui/autocomplete/AbstractCompletion.java
@@ -26,7 +26,17 @@ import javax.swing.text.JTextComponent;
/**
- * Base class for possible completions.
+ * Base class for possible completions. Most, if not all, {@link Completion}
+ * implementations can extend this class. It remembers the
+ * <tt>CompletionProvider</tt> that returns this completion, and also implements
+ * <tt>Comparable</tt>, allowing such completions to be compared
+ * lexicographically (ignoring case).<p>
+ *
+ * This implementation assumes the input text and replacement text are the
+ * same value. It also returns the input text from its {@link #toString()}
+ * method (which is what <tt>DefaultListCellRenderer</tt> uses to render
+ * objects). Subclasses that wish to override any of this behavior can simply
+ * override the corresponding method(s) needed to do so.
*
* @author Robert Futrell
* @version 1.0
@@ -50,7 +60,7 @@ public abstract class AbstractCompletion implements Completion, Comparable {
/**
- * Compares this completion to another one lexicograhically, ignoring
+ * Compares this completion to another one lexicographically, ignoring
* case.
*
* @param o Another completion instance.
diff --git a/src/org/fife/ui/autocomplete/AutoCompletePopupWindow.java b/src/org/fife/ui/autocomplete/AutoCompletePopupWindow.java
index f7fda51..d256b22 100644
--- a/src/org/fife/ui/autocomplete/AutoCompletePopupWindow.java
+++ b/src/org/fife/ui/autocomplete/AutoCompletePopupWindow.java
@@ -89,6 +89,12 @@ class AutoCompletePopupWindow extends JWindow implements CaretListener,
private boolean aboveCaret;
+ /**
+ * Constructor.
+ *
+ * @param parent The parent window (hosting the text component).
+ * @param ac The auto-completion instance.
+ */
public AutoCompletePopupWindow(Window parent, AutoCompletion ac) {
super(parent);
@@ -126,13 +132,6 @@ class AutoCompletePopupWindow extends JWindow implements CaretListener,
}
-// public void addItem(Completion item) {
-// model.addElement(item);
-// }
-public void setCompletions(List completions) {
- model.setContents(completions);
-}
-
public void caretUpdate(CaretEvent e) {
if (isVisible()) { // Should always be true
int line = ac.getLineOfCaret();
@@ -290,7 +289,7 @@ lastLine = -1;
/**
- * Positions the description window relative to the comletion choices
+ * Positions the description window relative to the completion choices
* window.
*/
private void positionDescWindow() {
@@ -322,7 +321,7 @@ lastLine = -1;
/**
- * "Puts back" the original kay/Action pair for a keystroke. This is used
+ * "Puts back" the original key/Action pair for a keystroke. This is used
* when this popup is hidden.
*
* @param im The input map.
@@ -360,7 +359,12 @@ lastLine = -1;
}
- public void selectFirstItem() {
+ /**
+ * Selects the first item in the completion list.
+ *
+ * @see #selectLastItem()
+ */
+ private void selectFirstItem() {
if (model.getSize() > 0) {
list.setSelectedIndex(0);
list.ensureIndexIsVisible(0);
@@ -368,7 +372,12 @@ lastLine = -1;
}
- public void selectLastItem() {
+ /**
+ * Selects the last item in the completion list.
+ *
+ * @see #selectFirstItem()
+ */
+ private void selectLastItem() {
int index = model.getSize() - 1;
if (index > -1) {
list.setSelectedIndex(index);
@@ -377,7 +386,12 @@ lastLine = -1;
}
- public void selectNextItem() {
+ /**
+ * Selects the next item in the completion list.
+ *
+ * @see #selectPreviousItem()
+ */
+ private void selectNextItem() {
int index = list.getSelectedIndex();
if (index > -1) {
index = (index + 1) % model.getSize();
@@ -387,7 +401,13 @@ lastLine = -1;
}
- public void selectPageDownItem() {
+ /**
+ * Selects the completion item one "page down" from the currently selected
+ * one.
+ *
+ * @see #selectPageUpItem()
+ */
+ private void selectPageDownItem() {
int visibleRowCount = list.getVisibleRowCount();
int i = Math.min(list.getModel().getSize()-1,
list.getSelectedIndex()+visibleRowCount);
@@ -396,7 +416,13 @@ lastLine = -1;
}
- public void selectPageUpItem() {
+ /**
+ * Selects the completion item one "page up" from the currently selected
+ * one.
+ *
+ * @see #selectPageDownItem()
+ */
+ private void selectPageUpItem() {
int visibleRowCount = list.getVisibleRowCount();
int i = Math.max(0, list.getSelectedIndex()-visibleRowCount);
list.setSelectedIndex(i);
@@ -404,7 +430,12 @@ lastLine = -1;
}
- public void selectPreviousItem() {
+ /**
+ * Selects the previous item in the completion list.
+ *
+ * @see #selectNextItem()
+ */
+ private void selectPreviousItem() {
int index = list.getSelectedIndex();
switch (index) {
case 0:
@@ -426,6 +457,18 @@ lastLine = -1;
/**
+ * Sets the completions to display in the choices list. The first
+ * completion is selected.
+ *
+ * @param completions The completions to display.
+ */
+ public void setCompletions(List completions) {
+ model.setContents(completions);
+ selectFirstItem();
+ }
+
+
+ /**
* Sets the default list cell renderer to use when a completion provider
* does not supply its own.
*
@@ -440,6 +483,13 @@ lastLine = -1;
}
+ /**
+ * Sets the location of this window to be "good" relative to the specified
+ * rectangle. That rectangle should be the location of the text
+ * component's caret, in screen coordinates.
+ *
+ * @param r The text component's caret position, in screen coordinates.
+ */
public void setLocationRelativeTo(Rectangle r) {
boolean showDescWindow = descWindow!=null && ac.getShowDescWindow();
@@ -470,7 +520,7 @@ lastLine = -1;
setLocation(x, y);
- // Position the description window, if neessary.
+ // Position the description window, if necessary.
if (showDescWindow) {
positionDescWindow();
}
@@ -510,6 +560,7 @@ lastLine = -1;
descWindow.setVisible(visible && ac.getShowDescWindow());
}
}
+
}
diff --git a/src/org/fife/ui/autocomplete/AutoCompletion.java b/src/org/fife/ui/autocomplete/AutoCompletion.java
index cf9cd65..bf9977a 100644
--- a/src/org/fife/ui/autocomplete/AutoCompletion.java
+++ b/src/org/fife/ui/autocomplete/AutoCompletion.java
@@ -587,7 +587,6 @@ try {
}
popupWindow.setCompletions(completions);
- popupWindow.selectFirstItem();
if (!popupWindow.isVisible()) {
Rectangle r = null;
diff --git a/src/org/fife/ui/autocomplete/BasicCompletion.java b/src/org/fife/ui/autocomplete/BasicCompletion.java
index d2894b1..55f0d5e 100644
--- a/src/org/fife/ui/autocomplete/BasicCompletion.java
+++ b/src/org/fife/ui/autocomplete/BasicCompletion.java
@@ -24,9 +24,13 @@ package org.fife.ui.autocomplete;
/**
- * A straightforward completion implementation. This implementation can be
- * used if you have a relatively short number of static completions with no
- * (or short) summaries.
+ * A straightforward {@link Completion} implementation. This implementation
+ * can be used if you have a relatively short number of static completions
+ * with no (or short) summaries.<p>
+ *
+ * This implementation uses the replacement text as the input text. It also
+ * includes a "short description" field, which (if non-<code>null</code>), is
+ * used in the completion choices list.
*
* @author Robert Futrell
* @version 1.0
@@ -91,6 +95,18 @@ public class BasicCompletion extends AbstractCompletion {
/**
+ * Returns the short description of this completion, usually used in
+ * the completion choices list.
+ *
+ * @return The short description, or <code>null</code> if there is none.
+ * @see #setShortDescription(String)
+ */
+ public String getShortDescription() {
+ return shortDesc;
+ }
+
+
+ /**
* {@inheritDoc}
*/
public String getSummary() {
@@ -99,6 +115,28 @@ public class BasicCompletion extends AbstractCompletion {
/**
+ * Sets the short description of this completion.
+ *
+ * @param shortDesc The short description of this completion.
+ * @see #getShortDescription()
+ */
+ public void setShortDescription(String shortDesc) {
+ this.shortDesc = shortDesc;
+ }
+
+
+ /**
+ * Sets the summary for this completion.
+ *
+ * @param summary The summary for this completion.
+ * @see #getSummary()
+ */
+ public void setSummary(String summary) {
+ this.summary = summary;
+ }
+
+
+ /**
* Returns a string representation of this completion. If the short
* description is not <code>null</code>, this method will return:
*
@@ -118,15 +156,4 @@ public class BasicCompletion extends AbstractCompletion {
}
- /**
- * Sets the summary for this completion.
- *
- * @param summary The summary for this completion.
- * @see #getSummary()
- */
- public void setSummary(String summary) {
- this.summary = summary;
- }
-
-
}
\ No newline at end of file
diff --git a/src/org/fife/ui/autocomplete/Completion.java b/src/org/fife/ui/autocomplete/Completion.java
index 080e450..b912ede 100644
--- a/src/org/fife/ui/autocomplete/Completion.java
+++ b/src/org/fife/ui/autocomplete/Completion.java
@@ -26,7 +26,22 @@ import javax.swing.text.JTextComponent;
/**
- * Represents a completion choice.
+ * Represents a completion choice. A {@link CompletionProvider} returns lists
+ * of objects implementing this interface. A <tt>Completion</tt> contains the
+ * following information:
+ *
+ * <ul>
+ * <li>The text the user must (begin to) input for this to be a completion
+ * choice.
+ * <li>The text that will be filled in if the user chooses this completion.
+ * Note that often, this is the same as the text the user must (begin to)
+ * enter, but this doesn't have to be the case.
+ * <li>Summary HTML that describes this completion. This is information that
+ * can be displayed in a helper "tooltip"-style window beside the
+ * completion list. This may be <code>null</code>. It may also be
+ * lazily generated to cut down on memory usage.
+ * <li>The <tt>CompletionProvider</tt> that returned this completion.
+ * </ul>
*
* @author Robert Futrell
* @version 1.0
diff --git a/src/org/fife/ui/autocomplete/CompletionXMLParser.java b/src/org/fife/ui/autocomplete/CompletionXMLParser.java
index aeb6b1f..4ce1b2e 100644
--- a/src/org/fife/ui/autocomplete/CompletionXMLParser.java
+++ b/src/org/fife/ui/autocomplete/CompletionXMLParser.java
@@ -84,7 +84,7 @@ class CompletionXMLParser extends DefaultHandler {
FunctionCompletion fc = new FunctionCompletion(provider,
name, returnType);
if (desc.length()>0) {
- fc.setDescription(desc.toString());
+ fc.setShortDescription(desc.toString());
desc.setLength(0);
}
fc.setParams(params);
@@ -114,7 +114,7 @@ class CompletionXMLParser extends DefaultHandler {
VariableCompletion vc = new VariableCompletion(provider,
name, returnType);
if (desc.length()>0) {
- vc.setDescription(desc.toString());
+ vc.setShortDescription(desc.toString());
desc.setLength(0);
}
vc.setDefinedIn(definedIn);
diff --git a/src/org/fife/ui/autocomplete/DefaultCompletionProvider.java b/src/org/fife/ui/autocomplete/DefaultCompletionProvider.java
index 364c033..c0b3c1d 100644
--- a/src/org/fife/ui/autocomplete/DefaultCompletionProvider.java
+++ b/src/org/fife/ui/autocomplete/DefaultCompletionProvider.java
@@ -44,7 +44,7 @@ import org.xml.sax.SAXException;
* A basic completion provider implementation. This provider has no
* understanding of language semantics. It simply checks the text entered up
* to the caret position for a match against known completions. This is all
- * that is needed in the marjority of cases.
+ * that is needed in the majority of cases.
*
* @author Robert Futrell
* @version 1.0
@@ -82,7 +82,7 @@ public class DefaultCompletionProvider extends AbstractCompletionProvider {
* Returns the text just before the current caret position that could be
* the start of something auto-completable.<p>
*
- * This method returns all characters before the caret that are metched
+ * This method returns all characters before the caret that are matched
* by {@link #isValidChar(char)}.
*
* @param comp The text component.
@@ -148,7 +148,7 @@ public class DefaultCompletionProvider extends AbstractCompletionProvider {
doc.getText(offs, len, s);
- // Get the identifier preceeding the '(', ignoring any whitespace
+ // Get the identifier preceding the '(', ignoring any whitespace
// between them.
offs = s.offset + len - 1;
while (offs>=s.offset && Character.isWhitespace(s.array[offs])) {
diff --git a/src/org/fife/ui/autocomplete/DelegatingCellRenderer.java b/src/org/fife/ui/autocomplete/DelegatingCellRenderer.java
index 5793d0b..d6b7111 100644
--- a/src/org/fife/ui/autocomplete/DelegatingCellRenderer.java
+++ b/src/org/fife/ui/autocomplete/DelegatingCellRenderer.java
@@ -96,6 +96,7 @@ class DelegatingCellRenderer extends DefaultListCellRenderer {
* {@inheritDoc}
*/
public void updateUI() {
+ super.updateUI();
if ((fallback instanceof JComponent) && fallback!=this) {
((JComponent)fallback).updateUI();
}
diff --git a/src/org/fife/ui/autocomplete/FunctionCompletion.java b/src/org/fife/ui/autocomplete/FunctionCompletion.java
index dd161a6..c911a33 100644
--- a/src/org/fife/ui/autocomplete/FunctionCompletion.java
+++ b/src/org/fife/ui/autocomplete/FunctionCompletion.java
@@ -117,8 +117,7 @@ public class FunctionCompletion extends VariableCompletion
// Add the return type if applicable (C macros like NULL have no type).
String type = getType();
if (type!=null) {
- appendPossibleDataType(sb, type);
- sb.append(' ');
+ sb.append(type).append(' ');
}
// Add the item being described's name.
@@ -132,7 +131,7 @@ public class FunctionCompletion extends VariableCompletion
type = param.getType();
String name = param.getName();
if (type!=null) {
- appendPossibleDataType(sb, type);
+ sb.append(type);
if (name!=null) {
sb.append(' ');
}
diff --git a/src/org/fife/ui/autocomplete/ParameterizedCompletion.java b/src/org/fife/ui/autocomplete/ParameterizedCompletion.java
index 30ee1f2..05ccc41 100644
--- a/src/org/fife/ui/autocomplete/ParameterizedCompletion.java
+++ b/src/org/fife/ui/autocomplete/ParameterizedCompletion.java
@@ -11,7 +11,7 @@ public interface ParameterizedCompletion extends Completion {
/**
- * Returns the "definition string" for this completion. For examle,
+ * Returns the "definition string" for this completion. For example,
* for the C "<code>printf</code>" function, this would return
* "<code>int printf(const char *, ...)</code>".
*
diff --git a/src/org/fife/ui/autocomplete/ShorthandCompletion.java b/src/org/fife/ui/autocomplete/ShorthandCompletion.java
index 8a4700d..38e1e47 100644
--- a/src/org/fife/ui/autocomplete/ShorthandCompletion.java
+++ b/src/org/fife/ui/autocomplete/ShorthandCompletion.java
@@ -109,8 +109,20 @@ public class ShorthandCompletion extends BasicCompletion {
*/
public String getSummary() {
String summary = super.getSummary();
- return summary!=null ? summary :
- "<html><body><tt>" + getReplacementText();
+ return summary!=null ? summary : ("<html><body>" + getSummaryBody());
+ }
+
+
+ /**
+ * Returns the "body" of the HTML returned by {@link #getSummary()} when
+ * no summary text has been set. This is defined to return the replacement
+ * text in a monospaced font.
+ *
+ * @return The summary text's body, if no other summary has been defined.
+ * @see #getReplacementText()
+ */
+ protected String getSummaryBody() {
+ return "<tt>" + getReplacementText();
}
diff --git a/src/org/fife/ui/autocomplete/Util.java b/src/org/fife/ui/autocomplete/Util.java
index e23aa40..41c3506 100644
--- a/src/org/fife/ui/autocomplete/Util.java
+++ b/src/org/fife/ui/autocomplete/Util.java
@@ -33,7 +33,7 @@ import java.net.URI;
* @author Robert Futrell
* @version 1.0
*/
-public class Util {
+class Util {
private static boolean desktopCreationAttempted;
private static Object desktop;
diff --git a/src/org/fife/ui/autocomplete/VariableCompletion.java b/src/org/fife/ui/autocomplete/VariableCompletion.java
index 7ecef75..c3fa77f 100644
--- a/src/org/fife/ui/autocomplete/VariableCompletion.java
+++ b/src/org/fife/ui/autocomplete/VariableCompletion.java
@@ -24,16 +24,27 @@ package org.fife.ui.autocomplete;
/**
- * A completion for a variable (or constant) in a programming language.
+ * A completion for a variable (or constant) in a programming language.<p>
+ *
+ * This completion type uses its <tt>shortDescription</tt> property as part of
+ * its summary returned by {@link #getSummary()}; for this reason, it may be
+ * a little longer (even much longer), if desired, than what is recommended
+ * for <tt>BasicCompletion</tt>s (where the <tt>shortDescription</tt> is used
+ * in {@link #toString()} for <tt>ListCellRenderers</tt>).
*
* @author Robert Futrell
* @version 1.0
*/
-public class VariableCompletion extends AbstractCompletion {
+public class VariableCompletion extends BasicCompletion {
- private String name;
+ /**
+ * The variable's type.
+ */
private String type;
- private String desc;
+
+ /**
+ * What library (for example) this variable is defined in.
+ */
private String definedIn;
@@ -47,8 +58,7 @@ public class VariableCompletion extends AbstractCompletion {
*/
public VariableCompletion(CompletionProvider provider, String name,
String type) {
- super(provider);
- this.name = name;
+ super(provider, name);
this.type = type;
}
@@ -59,23 +69,17 @@ public class VariableCompletion extends AbstractCompletion {
// Add the return type if applicable (C macros like NULL have no type).
if (type!=null) {
- appendPossibleDataType(sb, type);
- sb.append(' ');
+ sb.append(type).append(' ');
}
// Add the item being described's name.
- sb.append(name);
+ sb.append(getName());
sb.append("</b>");
}
- protected void appendPossibleDataType(StringBuffer sb, String type) {
- sb.append(type);
- }
-
-
/**
* Returns where this variable is defined.
*
@@ -88,25 +92,12 @@ public class VariableCompletion extends AbstractCompletion {
/**
- * Returns a short description of this variable. This should be an
- * HTML snippet.
- *
- * @return A short description of this variable. This may be
- * <code>null</code>.
- * @see #setDescription(String)
- */
- public String getDescription() {
- return desc;
- }
-
-
- /**
* Returns the name of this variable.
*
* @return The name.
*/
public String getName() {
- return name;
+ return getReplacementText();
}
@@ -133,16 +124,6 @@ public class VariableCompletion extends AbstractCompletion {
/**
- * Returns the name of this variable.
- *
- * @return The text to autocomplete with.
- */
- public String getReplacementText() {
- return getName();
- }
-
-
- /**
* Adds some HTML describing where this variable is defined, if this
* information is known.
*
@@ -163,9 +144,9 @@ public class VariableCompletion extends AbstractCompletion {
* @param sb The buffer to append to.
*/
protected void possiblyAddDescription(StringBuffer sb) {
- if (desc!=null) {
+ if (getShortDescription()!=null) {
sb.append("<hr><br>");
- sb.append(desc);
+ sb.append(getShortDescription());
sb.append("<br><br><br>");
}
}
@@ -183,15 +164,12 @@ public class VariableCompletion extends AbstractCompletion {
/**
- * Sets the short description of this variable. This should be an
- * HTML snippet.
+ * Overridden to return the name of the variable being completed.
*
- * @param desc A short description of this variable. This may be
- * <code>null</code>.
- * @see #getDescription()
+ * @return A string representation of this completion.
*/
- public void setDescription(String desc) {
- this.desc = desc;
+ public String toString() {
+ return getName();
}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/autocomplete.git
More information about the pkg-java-commits
mailing list