Package org.fife.ui.autocomplete
Class AutoCompletion
- java.lang.Object
-
- org.fife.ui.autocomplete.AutoCompletion
-
- Direct Known Subclasses:
RoundRobinAutoCompletion
public class AutoCompletion extends Object
Adds auto-completion to a text component. Provides a popup window with a list of auto-complete choices on a given keystroke, such as Crtrl+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
- Author:
- Robert Futrell
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected class
AutoCompletion.AutoCompleteAction
TheAction
that displays the popup window if auto-completion is enabled.
-
Constructor Summary
Constructors Constructor Description AutoCompletion(CompletionProvider provider)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addAutoCompletionListener(AutoCompletionListener l)
Adds a listener interested in popup window events from this instance.protected Action
createAutoCompleteAction()
Creates and returns the action to call when the user presses the auto-completion trigger key (e.g. ctrl+space).void
doCompletion()
Displays the popup window.protected void
fireAutoCompletionEvent(AutoCompletionEvent.Type type)
Fires anAutoCompletionEvent
of the specified type.int
getAutoActivationDelay()
Returns the delay between when the user types a character and when the code completion popup should automatically appear (if applicable).boolean
getAutoCompleteSingleChoices()
Returns whether, if a single auto-complete choice is available, it should be automatically inserted, without displaying the popup menu.CompletionProvider
getCompletionProvider()
Returns the completion provider.static KeyStroke
getDefaultTriggerKey()
Returns the default auto-complete "trigger key" for this OS.ExternalURLHandler
getExternalURLHandler()
Returns the handler to use when an external URL is clicked in the description window.static LinkRedirector
getLinkRedirector()
Returns the link redirector, if any.ListCellRenderer
getListCellRenderer()
Returns the default list cell renderer used when a completion provider does not supply its own.ListCellRenderer
getParamChoicesRenderer()
Returns the renderer to use forCompletion
s in the optional parameter choices popup window (displayed when aParameterizedCompletion
is code-completed).protected String
getReplacementText(Completion c, Document doc, int start, int len)
Returns the text to replace with in the document.boolean
getShowDescWindow()
Returns whether the "description window" should be shown alongside the completion window.static AutoCompletionStyleContext
getStyleContext()
Returns the style context describing how auto-completion related highlights in the editor are rendered.JTextComponent
getTextComponent()
Returns the text component for which auto-completion is enabled.KeyStroke
getTriggerKey()
Returns the "trigger key" used for auto-complete.boolean
hideChildWindows()
Hides any child windows being displayed by the auto-completion system.protected boolean
hidePopupWindow()
Hides the popup window, if it is visible.protected void
insertCompletion(Completion c)
Inserts a completion.protected void
insertCompletion(Completion c, boolean typedParamListStartChar)
Inserts a completion.void
install(JTextComponent c)
Installs this auto-completion on a text component.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).boolean
isAutoCompleteEnabled()
Returns whether auto-completion is enabled.protected boolean
isHideOnCompletionProviderChange()
Whether or not the popup should be hidden when the CompletionProvider changes.protected boolean
isHideOnNoText()
Whether or not the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").boolean
isParameterAssistanceEnabled()
Returns whether parameter assistance is enabled.boolean
isPopupVisible()
Returns whether the completion popup window is visible.protected int
refreshPopupWindow()
Refreshes the popup window.void
removeAutoCompletionListener(AutoCompletionListener l)
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
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 or not the popup should be hidden when the CompletionProvider changes.protected void
setHideOnNoText(boolean hideOnNoText)
Sets whether or not 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 renderer)
Sets the default list cell renderer to use when a completion provider does not supply its own.void
setParamChoicesRenderer(ListCellRenderer r)
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.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
setTriggerKey(KeyStroke ks)
Sets the keystroke that should be used to trigger the auto-complete popup window.void
uninstall()
Uninstalls this auto-completion from its text component.
-
-
-
Constructor Detail
-
AutoCompletion
public AutoCompletion(CompletionProvider provider)
Constructor.- Parameters:
provider
- The completion provider. This cannot benull
-
-
Method Detail
-
addAutoCompletionListener
public void addAutoCompletionListener(AutoCompletionListener l)
Adds a listener interested in popup window events from this instance.- Parameters:
l
- The listener to add.- See Also:
removeAutoCompletionListener(AutoCompletionListener)
-
doCompletion
public void doCompletion()
Displays the popup window. Hosting applications can call this method to programmatically begin an auto-completion operation.
-
fireAutoCompletionEvent
protected void fireAutoCompletionEvent(AutoCompletionEvent.Type type)
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:
setAutoActivationDelay(int)
-
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:
setAutoCompleteSingleChoices(boolean)
-
getCompletionProvider
public CompletionProvider getCompletionProvider()
Returns the completion provider.- Returns:
- The completion provider.
-
getDefaultTriggerKey
public static KeyStroke 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
public ExternalURLHandler getExternalURLHandler()
Returns the handler to use when an external URL is clicked in the description window.- Returns:
- The handler.
- See Also:
setExternalURLHandler(ExternalURLHandler)
,getLinkRedirector()
-
getLinkRedirector
public static LinkRedirector getLinkRedirector()
Returns the link redirector, if any.- Returns:
- The link redirector, or
null
if none. - See Also:
setLinkRedirector(LinkRedirector)
-
getListCellRenderer
public ListCellRenderer 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:
setListCellRenderer(ListCellRenderer)
-
getParamChoicesRenderer
public ListCellRenderer 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:
setParamChoicesRenderer(ListCellRenderer)
,isParameterAssistanceEnabled()
-
getReplacementText
protected String getReplacementText(Completion c, Document doc, int start, int len)
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 returns c.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:
setShowDescWindow(boolean)
-
getStyleContext
public static AutoCompletionStyleContext getStyleContext()
Returns the style context describing how auto-completion related highlights in the editor are rendered.- Returns:
- The style context.
-
getTextComponent
public JTextComponent 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:
install(JTextComponent)
-
getTriggerKey
public KeyStroke getTriggerKey()
Returns the "trigger key" used for auto-complete.- Returns:
- The trigger key.
- See Also:
setTriggerKey(KeyStroke)
-
hideChildWindows
public boolean hideChildWindows()
Hides any child windows being displayed by the auto-completion system.- Returns:
- Whether any windows were visible.
-
hidePopupWindow
protected boolean hidePopupWindow()
Hides the popup window, if it is visible.- Returns:
- Whether the popup window was visible.
-
insertCompletion
protected final void insertCompletion(Completion c)
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
protected void insertCompletion(Completion c, boolean typedParamListStartChar)
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
public void install(JTextComponent c)
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:
uninstall()
-
createAutoCompleteAction
protected Action 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:
AutoCompletion.AutoCompleteAction
-
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:
setAutoActivationEnabled(boolean)
,getAutoActivationDelay()
,isAutoCompleteEnabled()
-
isAutoCompleteEnabled
public boolean isAutoCompleteEnabled()
Returns whether auto-completion is enabled.- Returns:
- Whether auto-completion is enabled.
- See Also:
setAutoCompleteEnabled(boolean)
-
isHideOnCompletionProviderChange
protected boolean isHideOnCompletionProviderChange()
Whether or not the popup should be hidden when the CompletionProvider changes. If set to false, caller has to ensure refresh of the popup content.
-
isHideOnNoText
protected boolean isHideOnNoText()
Whether or not the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").- See Also:
setHideOnNoText(boolean)
-
isParameterAssistanceEnabled
public boolean isParameterAssistanceEnabled()
Returns whether parameter assistance is enabled.- Returns:
- Whether parameter assistance is enabled.
- See Also:
setParameterAssistanceEnabled(boolean)
-
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
public void removeAutoCompletionListener(AutoCompletionListener l)
Removes a listener interested in popup window events from this instance.- Parameters:
l
- The listener to remove.- See Also:
addAutoCompletionListener(AutoCompletionListener)
-
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:
getAutoActivationDelay()
-
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:
isAutoActivationEnabled()
,setAutoActivationDelay(int)
-
setAutoCompleteEnabled
public void setAutoCompleteEnabled(boolean enabled)
Sets whether auto-completion is enabled.- Parameters:
enabled
- Whether auto-completion is enabled.- See Also:
isAutoCompleteEnabled()
-
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:
getAutoCompleteSingleChoices()
-
setCompletionProvider
public void setCompletionProvider(CompletionProvider provider)
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(int, int)
-
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:
setChoicesWindowSize(int, int)
-
setExternalURLHandler
public void setExternalURLHandler(ExternalURLHandler handler)
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:
getExternalURLHandler()
-
setHideOnCompletionProviderChange
protected void setHideOnCompletionProviderChange(boolean hideOnCompletionProviderChange)
Sets whether or not the popup should be hidden when the CompletionProvider changes. If set to false, caller has to ensure refresh of the popup content.- See Also:
isHideOnCompletionProviderChange()
-
setHideOnNoText
protected void setHideOnNoText(boolean hideOnNoText)
Sets whether or not the popup should be hidden when user types a space (or any character that resets the completion list to "all completions").- See Also:
isHideOnNoText()
-
setLinkRedirector
public static void setLinkRedirector(LinkRedirector linkRedirector)
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:
getLinkRedirector()
-
setListCellRenderer
public void setListCellRenderer(ListCellRenderer renderer)
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:
getListCellRenderer()
-
setParamChoicesRenderer
public void setParamChoicesRenderer(ListCellRenderer r)
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:
getParamChoicesRenderer()
,setParameterAssistanceEnabled(boolean)
-
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:
isParameterAssistanceEnabled()
-
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:
isPopupVisible()
-
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:
getShowDescWindow()
-
setTriggerKey
public void setTriggerKey(KeyStroke ks)
Sets the keystroke that should be used to trigger the auto-complete popup window.- Parameters:
ks
- The keystroke.- Throws:
IllegalArgumentException
- Ifks
isnull
.- See Also:
getTriggerKey()
-
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:
install(JTextComponent)
-
-