org.fife.ui.autocomplete
Class AutoCompletion

java.lang.Object
  org.fife.ui.autocomplete.AutoCompletion

All Implemented Interfaces:

java.util.EventListener, java.awt.event.HierarchyListener

public class AutoCompletion

extends java.lang.Object

implements java.awt.event.HierarchyListener

Adds autocompletion to a text component. Provides a popup window with a list of autocomplete 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 tooltip describing the arguments they have to enter to the completion. Also, the arguments can be navigated via tab and shift+tab (ala Eclipse and NetBeans).

Version:

1.0

Author:

Robert Futrell

Constructor Summary

AutoCompletion(CompletionProvider provider)
Constructor.

Method Summary

void	doCompletion() Displays the popup window.
boolean	getAutoCompleteSingleChoices() Returns whether, if a single autocomplete choice is available, it should be automatically inserted, without displaying the popup menu.
CompletionProvider	getCompletionProvider() Returns the completion provider.
static javax.swing.KeyStroke	getDefaultTriggerKey() Returns the default autocomplete "trigger key" for this OS.
ExternalURLHandler	getExternalURLHandler() Returns the handler to use when an external URL is clicked in the description window.
javax.swing.ListCellRenderer	getListCellRenderer() Returns the default list cell renderer used when a completion provider does not supply its own.
protected java.lang.String	getReplacementText(Completion c, javax.swing.text.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.
javax.swing.text.JTextComponent	getTextComponent() Returns the text component for which autocompletion is enabled.
javax.swing.KeyStroke	getTriggerKey() Returns the "trigger key" used for autocomplete.
boolean	hideChildWindows() Hides any child windows being displayed by the auto-completion system.
void	hierarchyChanged(java.awt.event.HierarchyEvent e) Called when the component hierarchy for our text component changes.
void	install(javax.swing.text.JTextComponent c) Installs this autocompletion on a text component.
boolean	isAutoCompleteEnabled() Returns whether autocompletion is enabled.
boolean	isParameterAssistanceEnabled() Returns whether parameter assistance is enabled.
protected int	refreshPopupWindow() Refreshes the popup window.
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.
void	setListCellRenderer(javax.swing.ListCellRenderer renderer) Sets the default list cell renderer to use when a completion provider does not supply its own.
void	setParameterAssistanceEnabled(boolean enabled) Sets whether parameter assistance is enabled.
void	setShowDescWindow(boolean show) Sets whether the "description window" should be shown beside the completion window.
void	setTriggerKey(javax.swing.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.
void	updateUI() Updates the LookAndFeel of the popup window.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AutoCompletion

public AutoCompletion(CompletionProvider provider)

Constructor.

Parameters:

provider - The completion provider. This cannot be null.

Method Detail

doCompletion

public void doCompletion()

Displays the popup window. Hosting applications can call this method to programmatically begin an auto-completion operation.

getAutoCompleteSingleChoices

public boolean getAutoCompleteSingleChoices()

Returns whether, if a single autocomplete choice is available, it should be automatically inserted, without displaying the popup menu.

Returns:

Whether to autocomplete single choices.

See Also:

setAutoCompleteSingleChoices(boolean)

getCompletionProvider

public CompletionProvider getCompletionProvider()

Returns the completion provider.

Returns:

The completion provider.

getDefaultTriggerKey

public static javax.swing.KeyStroke getDefaultTriggerKey()

Returns the default autocomplete "trigger key" for this OS. For Windows, for example, it is Ctrl+Space.

Returns:

The default autocomplete 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)

getListCellRenderer

public javax.swing.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)

getReplacementText

protected java.lang.String getReplacementText(Completion c,
                                              javax.swing.text.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)

getTextComponent

public javax.swing.text.JTextComponent getTextComponent()

Returns the text component for which autocompletion is enabled.

Returns:

The text component, or null if this AutoCompletion is not installed on any text component.

See Also:

install(JTextComponent)

getTriggerKey

public javax.swing.KeyStroke getTriggerKey()

Returns the "trigger key" used for autocomplete.

Returns:

The trigger key.

See Also:

setTriggerKey(KeyStroke)

hierarchyChanged

public void hierarchyChanged(java.awt.event.HierarchyEvent e)

Called when the component hierarchy for our text component changes. When the text component is added to a new Window, this method registers listeners on that Window.

Specified by:

hierarchyChanged in interface java.awt.event.HierarchyListener

Parameters:

e - The event.

hideChildWindows

public boolean hideChildWindows()

Hides any child windows being displayed by the auto-completion system.

Returns:

Whether any windows were visible.

install

public void install(javax.swing.text.JTextComponent c)

Installs this autocompletion on a text component. If this AutoCompletion is already installed on another text component, it is uninstalled first.

Parameters:

c - The text component.

See Also:

uninstall()

isAutoCompleteEnabled

public boolean isAutoCompleteEnabled()

Returns whether autocompletion is enabled.

Returns:

Whether autocompletion is enabled.

See Also:

setAutoCompleteEnabled(boolean)

isParameterAssistanceEnabled

public boolean isParameterAssistanceEnabled()

Returns whether parameter assistance is enabled.

Returns:

Whether parameter assistance is enabled.

See Also:

setParameterAssistanceEnabled(boolean)

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.

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 be null.

Throws:

java.lang.IllegalArgumentException - If provider is null.

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, you will have to install your own handler to do so.

Parameters:

handler - The new handler.

See Also:

getExternalURLHandler()

setListCellRenderer

public void setListCellRenderer(javax.swing.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 is null, a default renderer is used.

See Also:

getListCellRenderer()

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()

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(javax.swing.KeyStroke ks)

Sets the keystroke that should be used to trigger the auto-complete popup window.

Parameters:

ks - The keystroke.

Throws:

java.lang.IllegalArgumentException - If ks is null.

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)

updateUI

public void updateUI()

Updates the LookAndFeel of the popup window. Applications can call this method as appropriate if they support changing the LookAndFeel at runtime.