com.jidesoft.hints

Class AbstractIntelliHints

java.lang.Object

com.jidesoft.hints.AbstractIntelliHints

All Implemented Interfaces:

IntelliHints

Direct Known Subclasses:

AbstractListIntelliHints

public abstract class AbstractIntelliHints
extends java.lang.Object
implements IntelliHints

AbstractIntelliHints is an abstract implementation of IntelliHints. It covers functions such as showing the hint popup at the correct position, delegating keystrokes, updating and selecting hint. The only thing that is left out to subclasses is the creation of the hint popup.

Author:

Santhosh Kumar T, JIDE Software, Inc.

Field Summary

Fields inherited from interface com.jidesoft.hints.IntelliHints

CLIENT_PROPERTY_INTELLI_HINTS

Constructor Summary

Constructors

Constructor and Description
AbstractIntelliHints(javax.swing.text.JTextComponent textComponent) Creates an IntelliHints object for a given JTextComponent.

Method Summary

Modifier and Type	Method and Description
void	acceptHint(java.lang.Object selected) After user has selected a item in the hints popup, this method will update JTextComponent accordingly to accept the hint.
void	addShowHintsKeyStroke(javax.swing.KeyStroke keyStroke) Adds a new key stroke to show hints popup.
protected JidePopup	createPopup()
javax.swing.KeyStroke[]	getAllShowHintsKeyStrokes() Gets all key strokes that will show hints popup.
protected int	getCaretPositionForPopup() Gets the caret position which is used as the anchor point to display the popup.
protected java.awt.Rectangle	getCaretRectangleForPopup(int caretPosition) Gets the caret rectangle where caret is displayed.
protected java.lang.Object	getContext() Gets the context for hints.
protected abstract javax.swing.JComponent	getDelegateComponent() Gets the delegate component in the hint popup.
protected abstract javax.swing.KeyStroke[]	getDelegateKeyStrokes() Gets the delegate keystrokes.
static IntelliHints	getIntelliHints(javax.swing.JComponent component) Gets the IntelliHints object if it was installed on the component before.
int	getShowHintsDelay() Gets the delay after the key is pressed to show hints.
protected javax.swing.KeyStroke	getShowHintsKeyStroke() Gets the keystroke that will trigger the hint popup.
javax.swing.text.JTextComponent	getTextComponent()
protected void	hideHintsPopup() Hides the hints popup.
boolean	isAutoPopup() Returns whether the hints popup is automatically displayed.
boolean	isFollowCaret() Should the hints popup follows the caret.
boolean	isHintsPopupVisible() Checks if the hints popup is visible.
protected boolean	isMultilineTextComponent() Returns whether this IntelliHints' JTextComponent supports single-line text or multi-line text.
void	removeShowHintsKeyStroke(javax.swing.KeyStroke keyStroke) Removes a key stroke from the list to show hints popup.
void	setAutoPopup(boolean autoPopup) Sets whether the popup should be displayed automatically.
void	setFollowCaret(boolean followCaret) Sets the position of the hints popup.
void	setHintsEnabled(boolean enabled) Enables or disables the hints popup.
void	setShowHintsDelay(int showHintsDelay) Sets the delay after the key is pressed to show hints.
void	showHints(boolean autoPopup) Shows the hints popup which contains the hints.
protected void	showHintsPopup(boolean autoPopup) This method will call showHints(boolean) if and only if the text component is enabled and has focus.
boolean	updateHints(java.lang.Object context) Update hints depending on the context.
boolean	updateHints(java.lang.Object context, boolean autoPopup) Update hints depending on the context.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.jidesoft.hints.IntelliHints

createHintsComponent, getSelectedHint

Constructor Detail

AbstractIntelliHints

public AbstractIntelliHints(javax.swing.text.JTextComponent textComponent)

Creates an IntelliHints object for a given JTextComponent.

Parameters:

textComponent - the text component.

Method Detail

createPopup

protected JidePopup createPopup()

getTextComponent

public javax.swing.text.JTextComponent getTextComponent()

acceptHint

public void acceptHint(java.lang.Object selected)

After user has selected a item in the hints popup, this method will update JTextComponent accordingly to accept the hint.

For JTextArea, the default implementation will insert the hint into current caret position. For JTextField, by default it will replace the whole content with the item user selected. Subclass can always choose to override it to accept the hint in a different way. For example, FileIntelliHints will append the selected item at the end of the existing text in order to complete a full file path.

Specified by:

acceptHint in interface IntelliHints

Parameters:

selected - the hint to be accepted.

isMultilineTextComponent

protected boolean isMultilineTextComponent()

Returns whether this IntelliHints' JTextComponent supports single-line text or multi-line text.

Returns:

true if the component supports multiple text lines, false otherwise

showHintsPopup

protected void showHintsPopup(boolean autoPopup)

This method will call showHints(boolean) if and only if the text component is enabled and has focus.

Parameters:

autoPopup -

updateHints

public boolean updateHints(java.lang.Object context)

Description copied from interface: IntelliHints

Update hints depending on the context. This method will be triggered for every key typed event in the text component. Subclass can override it to provide your own list of hints and call setListData to set it and returns true after that.

Specified by:

updateHints in interface IntelliHints

Parameters:

context - the current context

Returns:

true or false. If it is false, hint popup will not be shown.

updateHints

public boolean updateHints(java.lang.Object context,
                           boolean autoPopup)

Description copied from interface: IntelliHints

Update hints depending on the context. This method will be triggered for every key typed event in the text component. Subclass can override it to provide your own list of hints and call setListData to set it and returns true after that.

Specified by:

updateHints in interface IntelliHints

Parameters:

context - the current context

autoPopup - true or false. If true, it means this method was called through the auto-popup feature because of the show hint timer is triggered. If false, it means user pressed the show hint key stroke to show the popup.

Returns:

true or false. If it is false, hint popup will not be shown.

showHints

public void showHints(boolean autoPopup)

Shows the hints popup which contains the hints. It will call updateHints(Object, boolean). Only if it returns true, the popup will be shown. You can call this method to fore the hints to be displayed.

Parameters:

autoPopup -

getCaretRectangleForPopup

protected java.awt.Rectangle getCaretRectangleForPopup(int caretPosition)
                                                throws javax.swing.text.BadLocationException

Gets the caret rectangle where caret is displayed. The popup will be show around the area so that the returned rectangle area is always visible. This method will be called twice.

Parameters:

caretPosition - the caret position.

Returns:

the popup position relative to the text component.
Please note, this position is actually a rectangle area. The reason is the popup could be shown below or above the rectangle. Usually, the popup will be shown below the rectangle. In this case, the x and y of the rectangle will be the top-left corner of the popup. However if there isn't enough space for the popup because it's close to screen bottom border, we will show the popup above the rectangle. In this case, the bottom-left corner of the popup will be at x and (y - height). Simply speaking, the popup will never cover the area specified by the rectangle (either below it or above it).

Throws:

javax.swing.text.BadLocationException - if the given position does not represent a valid location in the associated document.

getCaretPositionForPopup

protected int getCaretPositionForPopup()

Gets the caret position which is used as the anchor point to display the popup. By default, it isFollowCaret() is true, it will return caret position. Otherwise it will return the caret position at the beginning of the caret line. Subclass can override to return any caret position.

Returns:

the caret position which is used as the anchor point to display the popup.

getContext

protected java.lang.Object getContext()

Gets the context for hints. The context is the information that IntelliHints needs in order to generate a list of hints. For example, for code-completion, the context is current word the cursor is on. for file completion, the context is the full string starting from the file system root.

We provide a default context in AbstractIntelliHints. If it's a JTextArea, the context will be the string at the caret line from line beginning to the caret position. If it's a JTextField, the context will be whatever string in the text field. Subclass can always override it to return the context that is appropriate.

Returns:

the context.

hideHintsPopup

protected void hideHintsPopup()

Hides the hints popup.

setHintsEnabled

public void setHintsEnabled(boolean enabled)

Enables or disables the hints popup.

Parameters:

enabled - true to enable the hints popup. Otherwise false.

isHintsPopupVisible

public boolean isHintsPopupVisible()

Checks if the hints popup is visible.

Returns:

true if it's visible. Otherwise, false.

isFollowCaret

public boolean isFollowCaret()

Should the hints popup follows the caret.

Returns:

true if the popup shows up right below the caret. False if the popup always shows at the bottom-left corner (or top-left if there isn't enough on the bottom of the screen) of the JTextComponent.

setFollowCaret

public void setFollowCaret(boolean followCaret)

Sets the position of the hints popup. If followCaret is true, the popup shows up right below the caret. Otherwise, it will stay at the bottom-left corner (or top-left if there isn't enough on the bottom of the screen) of JTextComponent.

Parameters:

followCaret - true or false.

isAutoPopup

public boolean isAutoPopup()

Returns whether the hints popup is automatically displayed. Default is true

Returns:

true if the popup should be automatically displayed. False will never show it automatically and then need the user to manually activate it via the getShowHintsKeyStroke() key binding.

See Also:

setAutoPopup(boolean)

setAutoPopup

public void setAutoPopup(boolean autoPopup)

Sets whether the popup should be displayed automatically. If autoPopup is true then is the popup automatically displayed whenever updateHints() return true. If autoPopup is false it's not automatically displayed and will need the user to activate the key binding defined by getShowHintsKeyStroke().

Parameters:

autoPopup - true or false

getDelegateKeyStrokes

protected abstract javax.swing.KeyStroke[] getDelegateKeyStrokes()

Gets the delegate keystrokes.

When hint popup is visible, the keyboard focus never leaves the text component. However the hint popup usually contains a component that user will try to use navigation key to select an item. For example, use UP and DOWN key to navigate the list. Those keystrokes, if the popup is visible, will be delegated to the the component that returns from getDelegateComponent().

NOTE: Since this method would be invoked inside the constructor of AbstractIntelliHints, please do not try to return a field because the field is not initiated yet at this time.

Returns:

an array of keystrokes that will be delegate to getDelegateComponent() when hint popup is shown.

getDelegateComponent

protected abstract javax.swing.JComponent getDelegateComponent()

Gets the delegate component in the hint popup.

Returns:

the component that will receive the keystrokes that are delegated to hint popup.

getShowHintsKeyStroke

protected javax.swing.KeyStroke getShowHintsKeyStroke()

Gets the keystroke that will trigger the hint popup. Usually the hints popup will be shown automatically when user types. Only when the hint popup is hidden accidentally, this keystroke will show the popup again.

By default, it's the DOWN key for JTextField and CTRL+SPACE for JTextArea.

Returns:

the keystroke that will trigger the hint popup.

getShowHintsDelay

public int getShowHintsDelay()

Gets the delay after the key is pressed to show hints.

Returns:

the delay time on milliseconds.

See Also:

setShowHintsDelay(int)

setShowHintsDelay

public void setShowHintsDelay(int showHintsDelay)

Sets the delay after the key is pressed to show hints.

By default, the delay time is 200ms.

Parameters:

showHintsDelay - the delay time

addShowHintsKeyStroke

public void addShowHintsKeyStroke(javax.swing.KeyStroke keyStroke)

Adds a new key stroke to show hints popup.

Parameters:

keyStroke - the key stroke

Since:

3.2.2

See Also:

removeShowHintsKeyStroke(javax.swing.KeyStroke), getAllShowHintsKeyStrokes()

removeShowHintsKeyStroke

public void removeShowHintsKeyStroke(javax.swing.KeyStroke keyStroke)

Removes a key stroke from the list to show hints popup.

Parameters:

keyStroke - the key stroke

Since:

3.2.2

getAllShowHintsKeyStrokes

public javax.swing.KeyStroke[] getAllShowHintsKeyStrokes()

Gets all key strokes that will show hints popup.

Returns:

the key stroke array.

Since:

3.2.2

getIntelliHints

public static IntelliHints getIntelliHints(javax.swing.JComponent component)

Gets the IntelliHints object if it was installed on the component before.

Parameters:

component - the component that has IntelliHints installed

Returns:

the IntelliHints.