Package org.fife.ui.autocomplete
Class AutoCompletion
java.lang.Object
org.fife.ui.autocomplete.AutoCompletion
- Direct Known Subclasses:
RoundRobinAutoCompletion
Adds auto-completion to a text component. Provides a popup window with a
list of auto-complete choices on a given keystroke, such as Ctrl+Space.
Depending on the CompletionProvider
installed, the following
auto-completion features may be enabled:
- An auto-complete choices list made visible via e.g. Ctrl+Space
- A "description" window displayed alongside the choices list that provides documentation on the currently selected completion choice (as seen in Eclipse and NetBeans).
- Parameter assistance. If this is enabled, if the user enters a "parameterized" completion, such as a method or a function, then they will receive a tool tip describing the arguments they have to enter to the completion. Also, the arguments can be navigated via tab and shift+tab (a la Eclipse and NetBeans).
- Version:
- 1.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
Listens for events in the text component to auto-activate the code completion popup.protected class
TheAction
that displays the popup window if auto-completion is enabled.private class
Listens for LookAndFeel changes and updates the various popup windows involved in auto-completion accordingly.private class
Action that starts a parameterized completion, e.g.private class
Listens for events in the parent window of the text component with auto-completion enabled.private class
Listens for events from the popup window.private class
Listens for events from the text component we're installed on. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
Whether the auto-activation of auto-complete (after a delay, after the user types an appropriate character) is enabled.Listens for events in the text component that cause the popup windows to automatically activate.private boolean
Whether auto-complete is enabled.private boolean
Whether, when there is only a single auto-complete option that matches the text at the current text position, that text should be auto-inserted, instead of the completion window displaying.private static final boolean
Whether debug messages should be printed to stdout as AutoCompletion runs.private Color
The background color of the description window.private static final String
Fired byJTextComponent
s when theirDocument
changes.private ExternalURLHandler
The handler to use when an external URL is clicked in the help documentation.private boolean
Whether the popup should be hidden when the CompletionProvider changes.private boolean
Whether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").Listens for LAF changes so the auto-complete windows automatically update themselves accordingly.private static LinkRedirector
An optional redirector that converts URL's to some other location before being handed over toexternalURLHandler
.private EventListenerList
All listeners registered on this component.private Action
The action previously assigned to the parameter completion key, so we can reset it when we uninstall.private Object
The previous key in the text component'sInputMap
for the parameter completion trigger key.private Action
The action previously assigned totrigger
, so we can reset it if the user disables auto-completion.private Object
The previous key in the text component'sInputMap
for the trigger key.private static final String
Key used in the input map for the parameter completion action.private static final String
The key used in the input map for the AutoComplete action.private ListCellRenderer
<Object> A renderer used forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed).private boolean
Whether parameter assistance is enabled.private int
The maximum length to attempt to display the 'full' parameter description for before truncating.private Window
The parent window oftextComponent
.Listens for events in the parent window that affect the visibility of the popup windows.private ParameterizedCompletionContext
Manages any parameterized completions that are inserted.private AutoCompletePopupWindow
The popup window containing completion choices.Listens for events from the popup window.private Dimension
The preferred size of the completion choices window.private Dimension
The preferred size of the optional description window.private CompletionProvider
Provides the completion options relevant to the current caret position.private ListCellRenderer
<Object> The renderer to use for the completion choices.private boolean
Whether the description window should be displayed along with the completion choice window.private static final AutoCompletionStyleContext
Stores how to render auto-completion-specific highlights in text components.private JTextComponent
The text component we're providing completion for.Listens for events from the text component that affect the visibility of the popup windows.private KeyStroke
The keystroke that triggers the completion window. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds a listener interested in popup window events from this instance.protected Action
Creates and returns the action to call when the user presses the auto-completion trigger key (e.g.void
Displays the popup window.protected void
Fires anAutoCompletionEvent
of the specified type.int
Returns the delay between when the user types a character and when the code completion popup should automatically appear (if applicable).boolean
Returns whether, if a single auto-complete choice is available, it should be automatically inserted, without displaying the popup menu.Returns the completion provider.(package private) static boolean
getDebug()
Returns whether debug is enabled for AutoCompletion.static KeyStroke
Returns the default auto-complete "trigger key" for this OS.Returns the background color for the description window.Returns the handler to use when an external URL is clicked in the description window.(package private) int
static LinkRedirector
Returns the link redirector, if any.Returns the default list cell renderer used when a completion provider does not supply its own.Returns the renderer to use forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed).int
Returns the maximum number of characters that theParameterizedCompletionDescriptionToolTip
will attempt to display on one line before truncating to a short-form representation.protected String
getReplacementText
(Completion c, Document doc, int start, int len) Returns the text to replace with in the document.boolean
Returns whether the "description window" should be shown alongside the completion window.static AutoCompletionStyleContext
Returns the style context describing how auto-completion related highlights in the editor are rendered.Returns the text component for which auto-completion is enabled.(package private) ComponentOrientation
Returns the orientation of the text component we're installed to.Returns the "trigger key" used for auto-complete.boolean
Hides any child windows being displayed by the auto-completion system.private boolean
Hides and disposes of any parameter completion-related popups.protected boolean
Hides the popup window, if it is visible.private static boolean
Determines whether debug should be enabled for the AutoCompletion library.protected final void
Inserts a completion.protected void
insertCompletion
(Completion c, boolean typedParamListStartChar) Inserts a completion.void
Installs this auto-completion on a text component.private void
Installs a "trigger key" action onto the current text component.boolean
Returns whether auto-activation is enabled (that is, whether the completion popup will automatically appear after a delay when the user types an appropriate character).boolean
Returns whether auto-completion is enabled.protected boolean
Whether the popup should be hidden when the CompletionProvider changes.protected boolean
Whether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").boolean
Returns whether parameter assistance is enabled.boolean
Returns whether the completion popup window is visible.protected int
Refreshes the popup window.void
Removes a listener interested in popup window events from this instance.void
setAutoActivationDelay
(int ms) Sets the delay between when the user types a character and when the code completion popup should automatically appear (if applicable).void
setAutoActivationEnabled
(boolean enabled) Toggles whether auto-activation is enabled.void
setAutoCompleteEnabled
(boolean enabled) Sets whether auto-completion is enabled.void
setAutoCompleteSingleChoices
(boolean autoComplete) Sets whether, if a single auto-complete choice is available, it should be automatically inserted, without displaying the popup menu.void
setChoicesWindowSize
(int w, int h) Sets the size of the completion choices window.void
setCompletionProvider
(CompletionProvider provider) Sets the completion provider being used.void
Sets the color of the description window.void
setDescriptionWindowSize
(int w, int h) Sets the size of the description window.void
setExternalURLHandler
(ExternalURLHandler handler) Sets the handler to use when an external URL is clicked in the description window.protected void
setHideOnCompletionProviderChange
(boolean hideOnCompletionProviderChange) Sets whether the popup should be hidden when the CompletionProvider changes.protected void
setHideOnNoText
(boolean hideOnNoText) Sets whether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").static void
setLinkRedirector
(LinkRedirector linkRedirector) Sets the redirector for external URL's found in code completion documentation.void
setListCellRenderer
(ListCellRenderer<Object> renderer) Sets the default list cell renderer to use when a completion provider does not supply its own.void
Sets the renderer to use forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed).void
setParameterAssistanceEnabled
(boolean enabled) Sets whether parameter assistance is enabled.void
setParameterDescriptionTruncateThreshold
(int truncateThreshold) Sets the maximum number of characters that theParameterizedCompletionDescriptionToolTip
will attempt to display on one line before truncating to a short-form representation.protected void
setPopupVisible
(boolean visible) Toggles the visibility of the auto-completion popup window.void
setShowDescWindow
(boolean show) Sets whether the "description window" should be shown beside the completion window.void
Sets the keystroke that should be used to trigger the auto-complete popup window.private void
startParameterizedCompletionAssistance
(ParameterizedCompletion pc, boolean typedParamListStartChar) Displays a "tool tip" detailing the inputs to the function just entered.void
Uninstalls this auto-completion from its text component.private void
Replaces the "trigger key" action with the one that was there before auto-completion was installed.private void
updateUI()
Updates the LookAndFeel of the popup window.
-
Field Details
-
textComponent
The text component we're providing completion for. -
parentWindow
The parent window oftextComponent
. -
popupWindow
The popup window containing completion choices. -
preferredChoicesWindowSize
The preferred size of the completion choices window. This field exists because the user will likely set the preferred size of the window before it is actually created. -
preferredDescWindowSize
The preferred size of the optional description window. This field only exists because the user may (and usually will) set the size of the description window before it exists (it must be parented to a Window). -
descWindowColor
The background color of the description window. -
pcc
Manages any parameterized completions that are inserted. -
provider
Provides the completion options relevant to the current caret position. -
renderer
The renderer to use for the completion choices. If this isnull
, then a default renderer is used. -
externalURLHandler
The handler to use when an external URL is clicked in the help documentation. -
linkRedirector
An optional redirector that converts URL's to some other location before being handed over toexternalURLHandler
. -
showDescWindow
private boolean showDescWindowWhether the description window should be displayed along with the completion choice window. -
autoCompleteEnabled
private boolean autoCompleteEnabledWhether auto-complete is enabled. -
autoActivationEnabled
private boolean autoActivationEnabledWhether the auto-activation of auto-complete (after a delay, after the user types an appropriate character) is enabled. -
autoCompleteSingleChoices
private boolean autoCompleteSingleChoicesWhether, when there is only a single auto-complete option that matches the text at the current text position, that text should be auto-inserted, instead of the completion window displaying. -
parameterAssistanceEnabled
private boolean parameterAssistanceEnabledWhether parameter assistance is enabled. -
parameterDescriptionTruncateThreshold
private int parameterDescriptionTruncateThresholdThe maximum length to attempt to display the 'full' parameter description for before truncating. -
paramChoicesRenderer
A renderer used forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed). If this isn't set, a default renderer is used. -
trigger
The keystroke that triggers the completion window. -
oldTriggerKey
The previous key in the text component'sInputMap
for the trigger key. -
oldTriggerAction
The action previously assigned totrigger
, so we can reset it if the user disables auto-completion. -
oldParenKey
The previous key in the text component'sInputMap
for the parameter completion trigger key. -
oldParenAction
The action previously assigned to the parameter completion key, so we can reset it when we uninstall. -
parentWindowListener
Listens for events in the parent window that affect the visibility of the popup windows. -
textComponentListener
Listens for events from the text component that affect the visibility of the popup windows. -
autoActivationListener
Listens for events in the text component that cause the popup windows to automatically activate. -
lafListener
Listens for LAF changes so the auto-complete windows automatically update themselves accordingly. -
popupWindowListener
Listens for events from the popup window. -
listeners
All listeners registered on this component. -
hideOnNoText
private boolean hideOnNoTextWhether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions"). Defaults to true. -
hideOnCompletionProviderChange
private boolean hideOnCompletionProviderChangeWhether the popup should be hidden when the CompletionProvider changes. If set to false, caller has to ensure refresh of the popup content. Defaults to true. -
PARAM_TRIGGER_KEY
The key used in the input map for the AutoComplete action.- See Also:
-
PARAM_COMPLETE_KEY
Key used in the input map for the parameter completion action.- See Also:
-
STYLE_CONTEXT
Stores how to render auto-completion-specific highlights in text components. -
DEBUG
private static final boolean DEBUGWhether debug messages should be printed to stdout as AutoCompletion runs. -
DOCUMENT_CHANGED_PROPERTY
Fired byJTextComponent
s when theirDocument
changes.- See Also:
-
-
Constructor Details
-
AutoCompletion
Constructor.- Parameters:
provider
- The completion provider. This cannot benull
-
-
Method Details
-
addAutoCompletionListener
Adds a listener interested in popup window events from this instance.- Parameters:
l
- The listener to add.- See Also:
-
doCompletion
public void doCompletion()Displays the popup window. Hosting applications can call this method to programmatically begin an auto-completion operation. -
fireAutoCompletionEvent
Fires anAutoCompletionEvent
of the specified type.- Parameters:
type
- The type of event to fire.
-
getAutoActivationDelay
public int getAutoActivationDelay()Returns the delay between when the user types a character and when the code completion popup should automatically appear (if applicable).- Returns:
- The delay, in milliseconds.
- See Also:
-
getAutoCompleteSingleChoices
public boolean getAutoCompleteSingleChoices()Returns whether, if a single auto-complete choice is available, it should be automatically inserted, without displaying the popup menu.- Returns:
- Whether to auto-complete single choices.
- See Also:
-
getCompletionProvider
Returns the completion provider.- Returns:
- The completion provider.
-
getDebug
static boolean getDebug()Returns whether debug is enabled for AutoCompletion.- Returns:
- Whether debug is enabled.
-
getDefaultTriggerKey
Returns the default auto-complete "trigger key" for this OS. For Windows, for example, it is Ctrl+Space.- Returns:
- The default auto-complete trigger key.
-
getExternalURLHandler
Returns the handler to use when an external URL is clicked in the description window.- Returns:
- The handler.
- See Also:
-
getLineOfCaret
int getLineOfCaret() -
getLinkRedirector
Returns the link redirector, if any.- Returns:
- The link redirector, or
null
if none. - See Also:
-
getListCellRenderer
Returns the default list cell renderer used when a completion provider does not supply its own.- Returns:
- The default list cell renderer.
- See Also:
-
getParamChoicesRenderer
Returns the renderer to use forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed). If this returnsnull
, a default renderer is used.- Returns:
- The renderer to use.
- See Also:
-
getReplacementText
Returns the text to replace with in the document. This is a "last-chance" hook for subclasses to make special modifications to the completion text inserted. The default implementation simply returnsc.getReplacementText()
. You usually will not need to modify this method.- Parameters:
c
- The completion being inserted.doc
- The document being modified.start
- The start of the text being replaced.len
- The length of the text being replaced.- Returns:
- The text to replace with.
-
getShowDescWindow
public boolean getShowDescWindow()Returns whether the "description window" should be shown alongside the completion window.- Returns:
- Whether the description window should be shown.
- See Also:
-
getStyleContext
Returns the style context describing how auto-completion related highlights in the editor are rendered.- Returns:
- The style context.
-
getDescWindowColor
Returns the background color for the description window.- Returns:
- The color.
-
getParameterDescriptionTruncateThreshold
public int getParameterDescriptionTruncateThreshold()Returns the maximum number of characters that theParameterizedCompletionDescriptionToolTip
will attempt to display on one line before truncating to a short-form representation.- Returns:
- The number of characters.
- See Also:
-
getTextComponent
Returns the text component for which auto-completion is enabled.- Returns:
- The text component, or
null
if thisAutoCompletion
is not installed on any text component. - See Also:
-
getTextComponentOrientation
ComponentOrientation getTextComponentOrientation()Returns the orientation of the text component we're installed to.- Returns:
- The orientation of the text component, or
null
if we are not installed on one.
-
getTriggerKey
Returns the "trigger key" used for auto-complete.- Returns:
- The trigger key.
- See Also:
-
hideChildWindows
public boolean hideChildWindows()Hides any child windows being displayed by the auto-completion system.- Returns:
- Whether any windows were visible.
-
hideParameterCompletionPopups
private boolean hideParameterCompletionPopups()Hides and disposes of any parameter completion-related popups.- Returns:
- Whether any such windows were visible (and thus hidden).
-
hidePopupWindow
protected boolean hidePopupWindow()Hides the popup window, if it is visible.- Returns:
- Whether the popup window was visible.
-
initDebug
private static boolean initDebug()Determines whether debug should be enabled for the AutoCompletion library. This method checks a system property, but takes care ofSecurityException
s in case we're in an applet or WebStart.- Returns:
- Whether debug should be enabled.
-
insertCompletion
Inserts a completion. Any time a code completion event occurs, the actual text insertion happens through this method.- Parameters:
c
- A completion to insert. This cannot benull
.
-
insertCompletion
Inserts a completion. Any time a code completion event occurs, the actual text insertion happens through this method.- Parameters:
c
- A completion to insert. This cannot benull
.typedParamListStartChar
- Whether the parameterized completion start character was typed (typically'('
).
-
install
Installs this auto-completion on a text component. If thisAutoCompletion
is already installed on another text component, it is uninstalled first.- Parameters:
c
- The text component.- See Also:
-
installTriggerKey
Installs a "trigger key" action onto the current text component.- Parameters:
ks
- The keystroke that should trigger the action.- See Also:
-
createAutoCompleteAction
Creates and returns the action to call when the user presses the auto-completion trigger key (e.g. ctrl+space). This is a hook for subclasses that want to provide their own behavior in this scenario. The default implementation returns anAutoCompletion.AutoCompleteAction
.- Returns:
- The action to use.
- See Also:
-
isAutoActivationEnabled
public boolean isAutoActivationEnabled()Returns whether auto-activation is enabled (that is, whether the completion popup will automatically appear after a delay when the user types an appropriate character). Note that this parameter will be ignored if auto-completion is disabled.- Returns:
- Whether auto-activation is enabled.
- See Also:
-
isAutoCompleteEnabled
public boolean isAutoCompleteEnabled()Returns whether auto-completion is enabled.- Returns:
- Whether auto-completion is enabled.
- See Also:
-
isHideOnCompletionProviderChange
protected boolean isHideOnCompletionProviderChange()Whether the popup should be hidden when the CompletionProvider changes. If set to false, caller has to ensure refresh of the popup content.- Returns:
- Whether the popup should be hidden when the completion provider changes.
- See Also:
-
isHideOnNoText
protected boolean isHideOnNoText()Whether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").- Returns:
- Whether the popup should be hidden when the completion list is reset to show all completions.
- See Also:
-
isParameterAssistanceEnabled
public boolean isParameterAssistanceEnabled()Returns whether parameter assistance is enabled.- Returns:
- Whether parameter assistance is enabled.
- See Also:
-
isPopupVisible
public boolean isPopupVisible()Returns whether the completion popup window is visible.- Returns:
- Whether the completion popup window is visible.
-
refreshPopupWindow
protected int refreshPopupWindow()Refreshes the popup window. First, this method gets the possible completions for the current caret position. If there are none, and the popup is visible, it is hidden. If there are some completions and the popup is hidden, it is made visible and made to display the completions. If there are some completions and the popup is visible, its list is updated to the current set of completions.- Returns:
- The current line number of the caret.
-
removeAutoCompletionListener
Removes a listener interested in popup window events from this instance.- Parameters:
l
- The listener to remove.- See Also:
-
setAutoActivationDelay
public void setAutoActivationDelay(int ms) Sets the delay between when the user types a character and when the code completion popup should automatically appear (if applicable).- Parameters:
ms
- The delay, in milliseconds. This should be greater than zero.- See Also:
-
setAutoActivationEnabled
public void setAutoActivationEnabled(boolean enabled) Toggles whether auto-activation is enabled. Note that auto-activation also depends on auto-completion itself being enabled.- Parameters:
enabled
- Whether auto-activation is enabled.- See Also:
-
setAutoCompleteEnabled
public void setAutoCompleteEnabled(boolean enabled) Sets whether auto-completion is enabled.- Parameters:
enabled
- Whether auto-completion is enabled.- See Also:
-
setAutoCompleteSingleChoices
public void setAutoCompleteSingleChoices(boolean autoComplete) Sets whether, if a single auto-complete choice is available, it should be automatically inserted, without displaying the popup menu.- Parameters:
autoComplete
- Whether to auto-complete single choices.- See Also:
-
setCompletionProvider
Sets the completion provider being used.- Parameters:
provider
- The new completion provider. This cannot benull
.- Throws:
IllegalArgumentException
- Ifprovider
isnull
.
-
setChoicesWindowSize
public void setChoicesWindowSize(int w, int h) Sets the size of the completion choices window.- Parameters:
w
- The new width.h
- The new height.- See Also:
-
setDescriptionWindowSize
public void setDescriptionWindowSize(int w, int h) Sets the size of the description window.- Parameters:
w
- The new width.h
- The new height.- See Also:
-
setDescriptionWindowColor
Sets the color of the description window.- Parameters:
c
- The new color.
-
setExternalURLHandler
Sets the handler to use when an external URL is clicked in the description window. This handler can perform some action, such as open the URL in a web browser. The default implementation will open the URL in a browser, but only if running in Java 6. If you want browser support for Java 5 and below, or otherwise want to respond to hyperlink clicks, you will have to install your own handler to do so.- Parameters:
handler
- The new handler.- See Also:
-
setHideOnCompletionProviderChange
protected void setHideOnCompletionProviderChange(boolean hideOnCompletionProviderChange) Sets whether the popup should be hidden when the CompletionProvider changes. If set to false, caller has to ensure refresh of the popup content.- Parameters:
hideOnCompletionProviderChange
- Whether the popup should be hidden when the completion provider changes.- See Also:
-
setHideOnNoText
protected void setHideOnNoText(boolean hideOnNoText) Sets whether the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").- Parameters:
hideOnNoText
- Whether the popup should be hidden when the completion list is reset to show all completions.- See Also:
-
setLinkRedirector
Sets the redirector for external URL's found in code completion documentation. When a non-local link in completion popups is clicked, this redirector is given the chance to modify the URL fetched and displayed.- Parameters:
linkRedirector
- The link redirector, ornull
for none.- See Also:
-
setListCellRenderer
Sets the default list cell renderer to use when a completion provider does not supply its own.- Parameters:
renderer
- The renderer to use. If this isnull
, a default renderer is used.- See Also:
-
setParamChoicesRenderer
Sets the renderer to use forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed). If this isn't set, a default renderer is used.- Parameters:
r
- The renderer to use.- See Also:
-
setParameterAssistanceEnabled
public void setParameterAssistanceEnabled(boolean enabled) Sets whether parameter assistance is enabled. If parameter assistance is enabled, and a "parameterized" completion (such as a function or method) is inserted, the user will get "assistance" in inserting the parameters in the form of a popup window with documentation and easy tabbing through the arguments (as seen in Eclipse and NetBeans).- Parameters:
enabled
- Whether parameter assistance should be enabled.- See Also:
-
setPopupVisible
protected void setPopupVisible(boolean visible) Toggles the visibility of the auto-completion popup window. This fires anAutoCompletionEvent
of the appropriate type.- Parameters:
visible
- Whether the window should be made visible or hidden.- See Also:
-
setShowDescWindow
public void setShowDescWindow(boolean show) Sets whether the "description window" should be shown beside the completion window.- Parameters:
show
- Whether to show the description window.- See Also:
-
setTriggerKey
Sets the keystroke that should be used to trigger the auto-complete popup window.- Parameters:
ks
- The keystroke.- Throws:
IllegalArgumentException
- Ifks
isnull
.- See Also:
-
startParameterizedCompletionAssistance
private void startParameterizedCompletionAssistance(ParameterizedCompletion pc, boolean typedParamListStartChar) Displays a "tool tip" detailing the inputs to the function just entered.- Parameters:
pc
- The completion.typedParamListStartChar
- Whether the parameterized completion list starting character was typed.
-
uninstall
public void uninstall()Uninstalls this auto-completion from its text component. If it is not installed on any text component, nothing happens.- See Also:
-
uninstallTriggerKey
private void uninstallTriggerKey()Replaces the "trigger key" action with the one that was there before auto-completion was installed.- See Also:
-
updateUI
private void updateUI()Updates the LookAndFeel of the popup window. Applications can call this method as appropriate if they support changing the LookAndFeel at runtime. -
setParameterDescriptionTruncateThreshold
public void setParameterDescriptionTruncateThreshold(int truncateThreshold) Sets the maximum number of characters that theParameterizedCompletionDescriptionToolTip
will attempt to display on one line before truncating to a short-form representation.- Parameters:
truncateThreshold
- The number of characters before truncation occurs.- See Also:
-