oracle.javatools.editor.insight
Class AbstractInsight

java.lang.Object
  oracle.javatools.editor.insight.AbstractInsight

All Implemented Interfaces:

ActionHookInvoker, java.awt.event.ActionListener, javax.swing.event.CaretListener, CharacterTypedListener, EditorPlugin, java.util.EventListener, java.awt.event.FocusListener, Insight, oracle.javatools.editor.popup.PopupWindowListener, java.beans.PropertyChangeListener

public abstract class AbstractInsight

extends java.lang.Object

implements ActionHookInvoker, java.awt.event.ActionListener, javax.swing.event.CaretListener, CharacterTypedListener, java.awt.event.FocusListener, Insight, oracle.javatools.editor.popup.PopupWindowListener

The AbstractInsight class provides some of the common functionality of all Insight implementations, such as handling the delayed timer, trapping of editor commands, displaying of the Insight window, and so on.

Notes on when to update Insight:

The following are the ways that the source file can be modified, requiring Insight to be updated:

1. Moving the caret position forward or backward by navigation (arrow keys, mouse click.) This generates a CaretEvent, but not a DocumentEvent.
2. Typing in text at the current cursor position. This will generate both a CaretEvent as well as a DocumentEvent. There is NO guarantee of order between the two events.
3. Deleting the text prior to the cursor position by hitting backspace. This generates both a CaretEvent and a DocumentEvent. Handling "delete-previous-word" functionality is similar.
4. Deleting the text after the caret position by hitting the delete key. This will only generate a DocumentEvent. Handling "delete-next-word" functionality is similar.
5. Performing an action that causes text to be removed or added (cut, paste, ...) These will generate a DocumentEvent, and generally a CaretEvent as well (depends on the action.)

The main problem is that the CaretEvent and DocumentEvent are not ordered with respective to each other - because of this, there is no way to know which one will fire first. It is undesirable to update Insight twice (especially if it causes "flashing".)

Another possibility is to fire a delayed timer when either of these events are generated so that we only update once - the problem with this is that it is possible for the user to issue a command (i.e., hitting "Enter" to complete Insight) before the timer fires, which could potentially cause incorrect results. This is also undesirable.

So what if we choose to listen to just one of the events? Listening to just DocumentEvents will cause us to miss case (1), while listening to just CaretEvents will cause us to miss case (4). Missing case (1) is bad because the user may navigate out of the insight critical area using the mouse. Missing case (4) is not a huge deal as the Insight information is generated primarily using the information before the cursor.

If you combine the use of OffsetMarks with the CaretEvent, you could guess the approximate location of the document change (if any.)

This implementation will take care of locking when InsightProvider.getInsightData() and InsightProvider.updateInsightData() are called.

Completion implementations should return COMPLETION_TYPE in getInsightType(), while Tooltip implementations should return TOOLTIP_TYPE. This will ensure that the correct action redirection occurs. Currently, for API compatibility, this abstract class always returns COMPLETION_TYPE for getInsightType(). This will be changed to an abstract method at some point in the future, so clients should update their implementations accordingly.

See Also:

Insight, InsightProvider, InsightData, InsightView

Field Summary

protected static int[]	COMPLETION_LOCATIONS The preferred positions for a COMPLETION_TYPE insight.
static int	COMPLETION_TYPE Constant describing an Insight completion type implementation.
protected static int[]	TOOLTIP_LOCATIONS The preferred positions for a TOOLTIP_TYPE insight.
static int	TOOLTIP_TYPE Constant describing an Insight tooltype type implementation.

Fields inherited from interface oracle.javatools.editor.popup.PopupWindowListener

CLOSED_AUTO, CLOSED_NORMAL

Constructor Summary

AbstractInsight()

Method Summary

void	actionPerformed(java.awt.event.ActionEvent event) This is invoked when an action is performed.
void	caretUpdate(javax.swing.event.CaretEvent event) Called when the caret position is updated.
void	characterTyped(BasicEditorPane editorPane, int offset, char typedChar) Providers notification that a character was typed by the user and inserted into the editor pane.
void	clearPopupTimer() Clears the delay timer for auto-popping up Insight, effectively cancelling the request.
protected abstract InsightProvider	createInsightProvider() Creates an InsightProvider to be used with this Insight instance.
void	deinstall(BasicEditorPane editor) Called when the plugin is being removed from the BasicEditorPane (for example when the editor is closed.) This is used to notify plugins that they should unregister any listeners that were attached.
void	editorFocusGained(oracle.javatools.editor.popup.PopupWindow popupWindow) Notifies the listener that the editor (or one of its popups) have regained focus.
void	editorFocusLost(oracle.javatools.editor.popup.PopupWindow popupWindow, boolean isTemporary) Notifies the listener that the editor and any managed popups have lost focus.
void	focusGained(java.awt.event.FocusEvent event) Invoked when a component gains the keyboard focus.
void	focusLost(java.awt.event.FocusEvent event) Invoked when a component loses the keyboard focus.
int	getCaretPosition() Utility routine to fetch the caret position in the text buffer associated with a particular pane.
BasicDocument	getDocument() Fetch the underlying document of the editor pane that this Insight instance is installed in.
BasicEditorPane	getEditorPane() Fetches the editor pane that this Insight instance is installed in.
protected int	getInsightType() Fetches the Insight implementation type, whether completion or tooltip.
protected int[]	getPreferredLocations() Fetch an array of preferred locations where this insight implementation would like to display its view.
java.awt.Rectangle	getShowRectangle() Get the rectangle (relative to editor) where the insight window should be shown.
TextBuffer	getTextBuffer() Utility routine to fetch the text buffer associated with the particular editor pane.
void	hideInsight() Cancels an existing insight window that is displaying insight information.
void	install(BasicEditorPane editor) Called when this plugin is being installed into the BasicEditorPane.
boolean	invokeAction(java.lang.String actionKey) Invokes the Action corresponding to the given actionKey.
protected boolean	invokeCompletionTypeAction(int command) Implementation specific routine to invoke the given action that was trapped by the editor.
protected boolean	invokeTooltipTypeAction(int command) Implementation specific routine to invoke the given action that was trapped by the editor.
protected boolean	isExactMatch(InsightData data) Fetch whether the current insight data instance represents an exact match.
protected boolean	isExactMatchSupported(InsightData data) Fetch whether exact match completion should be enabled for the given insight data instance.
abstract boolean	isInsightTriggerChar(char typedChar) Returns whether the given typed character should be treated as a trigger for firing the auto-popup timer for Insight.
boolean	isInsightVisible() Returns whether there is an Insight window displayed right now.
protected static int	lookupCommand(java.lang.String actionKey) Utility routine which maps an action name (such as "caret-down") to one of our private constants (like UP_COMMAND.)
void	popupClosed(oracle.javatools.editor.popup.PopupWindow popupWindow, int how) Notifies the listener that the popup window has been closed.
void	propertyChange(java.beans.PropertyChangeEvent event) This method gets called when a bound property is changed.
protected void	propertyChangeImpl(java.beans.PropertyChangeEvent event) Version of propertyChange() for implementations to override if they choose.
void	restartPopupTimer() Starts (or restarts) the auto-popup delay timer for this Insight feature.
void	setAccessibleName(java.lang.String name)
void	showInsight() Instructs this insight to check whether there is insight information availble, and if so, to bring up an insight window.
protected void	updateInsight() Utility routine which takes care of updating the Insight information which is currently displayed.

Methods inherited from class java.lang.Object

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

Field Detail

COMPLETION_TYPE

public static final int COMPLETION_TYPE

Constant describing an Insight completion type implementation.

See Also:

Constant Field Values

TOOLTIP_TYPE

public static final int TOOLTIP_TYPE

Constant describing an Insight tooltype type implementation.

See Also:

Constant Field Values

COMPLETION_LOCATIONS

protected static final int[] COMPLETION_LOCATIONS

The preferred positions for a COMPLETION_TYPE insight.

TOOLTIP_LOCATIONS

protected static final int[] TOOLTIP_LOCATIONS

The preferred positions for a TOOLTIP_TYPE insight.

Constructor Detail

AbstractInsight

public AbstractInsight()

Method Detail

createInsightProvider

protected abstract InsightProvider createInsightProvider()

Creates an InsightProvider to be used with this Insight instance.

Returns:

an InsightProvider for use here

isInsightTriggerChar

public abstract boolean isInsightTriggerChar(char typedChar)

Returns whether the given typed character should be treated as a trigger for firing the auto-popup timer for Insight.

Parameters:

typedChar - the character that was typed

Returns:

true if the character is an Insight trigger

isExactMatchSupported

protected boolean isExactMatchSupported(InsightData data)

Fetch whether exact match completion should be enabled for the given insight data instance. This allows implementations to override this and disable exact-match completion for specific use cases (like attributes in XML editing.)

Note that there global property for whether exact match is enabled still overrides language implementations - if exact-match is disabled globally, this method will never get called.

Parameters:

data - the current insight data instance

Returns:

true if exact match completion is supported

isExactMatch

protected boolean isExactMatch(InsightData data)

Fetch whether the current insight data instance represents an exact match. This allows implementations to override this in case multiple data items will complete the same information. For example, this allows Java insight to treat a case where the list contains a method that is overloaded (all w/ the same return types) as a single exact-match.

If this indicates that there is a single exact match, and exact-match completion is on, the completion will be performed automatically on the *default* data item.

Parameters:

data - the current insight data instance

Returns:

whether the current data contents have a single exact match.

getInsightType

protected int getInsightType()

Fetches the Insight implementation type, whether completion or tooltip.

Returns:

the Insight type, COMPLETION_TYPE or TOOLTIP_TYPE

getEditorPane

public final BasicEditorPane getEditorPane()

Fetches the editor pane that this Insight instance is installed in. This is defined so that Insight implementations can get at the editor pane.

Returns:

the editor pane

getDocument

public final BasicDocument getDocument()

Fetch the underlying document of the editor pane that this Insight instance is installed in. This is defined so that Insight implementations can get at the editor pane.

Returns:

the document

getTextBuffer

public TextBuffer getTextBuffer()

Utility routine to fetch the text buffer associated with the particular editor pane. This is defined here for implementations that need to "massage" the text buffer that completion insight sees. For example, Insight implementations for JSP may wish to translate the buffer to Java first.

Returns:

the text buffer which insight should use as its input

getCaretPosition

public int getCaretPosition()

Utility routine to fetch the caret position in the text buffer associated with a particular pane. This is defined here for implementations that need to "massage" the text buffer that completion insight sees (which would "change" the caret position.) For example, Insight implementations for JSP may wish to translate the buffer to Java first.

Returns:

the caret position in the text buffer which insight should use

setAccessibleName

public void setAccessibleName(java.lang.String name)

characterTyped

public void characterTyped(BasicEditorPane editorPane,
                           int offset,
                           char typedChar)

Providers notification that a character was typed by the user and inserted into the editor pane.

Specified by:

characterTyped in interface CharacterTypedListener

Parameters:

editorPane - the editor pane where the character was typed

offset - the offset where the character was inserted

typedChar - the character that was typed

invokeAction

public boolean invokeAction(java.lang.String actionKey)

Invokes the Action corresponding to the given actionKey.

Specified by:

invokeAction in interface ActionHookInvoker

Parameters:

actionKey - the published key for the action

Returns:

true if the action is handled, false otherwise

invokeCompletionTypeAction

protected boolean invokeCompletionTypeAction(int command)

Implementation specific routine to invoke the given action that was trapped by the editor.

Parameters:

command - the internal command id, such as UP_COMMAND

Returns:

true if the action can be handled (even if it is a nop), or false if it does not apply to the implementation

invokeTooltipTypeAction

protected boolean invokeTooltipTypeAction(int command)

Implementation specific routine to invoke the given action that was trapped by the editor.

Parameters:

command - the internal command id, such as UP_COMMAND

Returns:

true if the action can be handled (even if it is a nop), or false if it does not apply to the implementation

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent event)

This is invoked when an action is performed. In this case, it should only be a Timer event.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

Parameters:

event - the action event

install

public void install(BasicEditorPane editor)

Called when this plugin is being installed into the BasicEditorPane.

Specified by:

install in interface EditorPlugin

Parameters:

editor - the editor pane

deinstall

public void deinstall(BasicEditorPane editor)

Called when the plugin is being removed from the BasicEditorPane (for example when the editor is closed.) This is used to notify plugins that they should unregister any listeners that were attached.

Specified by:

deinstall in interface EditorPlugin

Parameters:

editor - the editor pane

propertyChange

public final void propertyChange(java.beans.PropertyChangeEvent event)

This method gets called when a bound property is changed.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

event - A PropertyChangeEvent object describing the event source and the property that has changed.

propertyChangeImpl

protected void propertyChangeImpl(java.beans.PropertyChangeEvent event)

Version of propertyChange() for implementations to override if they choose. This is done to guarantee that the base implementation for propertyChange gets called.

Parameters:

event - A PropertyChangeEvent object describing the event source and the property that has changed.

restartPopupTimer

public void restartPopupTimer()

Starts (or restarts) the auto-popup delay timer for this Insight feature. When the timer fires (delay elapsed), an Insight query will be initiated to see if there is any Insight assistance available. If there is, an Insight window will be displayed automatically.

Specified by:

restartPopupTimer in interface Insight

clearPopupTimer

public void clearPopupTimer()

Clears the delay timer for auto-popping up Insight, effectively cancelling the request. This will only have an effect if the timer has been started. If Insight is up already, this will have no effect. This is used mainly to cancel a previous (delayed) request to popup Insight and is probably be not much use to editor clients.

Specified by:

clearPopupTimer in interface Insight

See Also:

Insight.restartPopupTimer()

isInsightVisible

public boolean isInsightVisible()

Returns whether there is an Insight window displayed right now. This will return true only if an Insight window is actually up, not if there is an Insight query in progress.

Specified by:

isInsightVisible in interface Insight

Returns:

true if this Insight implementation has an Insight window up

getShowRectangle

public java.awt.Rectangle getShowRectangle()

Get the rectangle (relative to editor) where the insight window should be shown. May return null in case of error.

Returns:

the rectangle where the popup window should be anchored relative to

showInsight

public void showInsight()

Instructs this insight to check whether there is insight information availble, and if so, to bring up an insight window.

Specified by:

showInsight in interface Insight

hideInsight

public void hideInsight()

Cancels an existing insight window that is displaying insight information. This will put Insight back into an inactive state, as well as release any resources that might currently be held.

Specified by:

hideInsight in interface Insight

focusGained

public void focusGained(java.awt.event.FocusEvent event)

Invoked when a component gains the keyboard focus.

Specified by:

focusGained in interface java.awt.event.FocusListener

focusLost

public void focusLost(java.awt.event.FocusEvent event)

Invoked when a component loses the keyboard focus.

Specified by:

focusLost in interface java.awt.event.FocusListener

popupClosed

public void popupClosed(oracle.javatools.editor.popup.PopupWindow popupWindow,
                        int how)

Notifies the listener that the popup window has been closed.

Specified by:

popupClosed in interface oracle.javatools.editor.popup.PopupWindowListener

Parameters:

popupWindow - the popup window that this notification is being delivered for

how - how the popup was closed, either CLOSED_NORMAL or CLOSED_AUTO.

editorFocusGained

public void editorFocusGained(oracle.javatools.editor.popup.PopupWindow popupWindow)

Notifies the listener that the editor (or one of its popups) have regained focus.

Specified by:

editorFocusGained in interface oracle.javatools.editor.popup.PopupWindowListener

Parameters:

popupWindow - the popup window that this notification is being delivered for

editorFocusLost

public void editorFocusLost(oracle.javatools.editor.popup.PopupWindow popupWindow,
                            boolean isTemporary)

Notifies the listener that the editor and any managed popups have lost focus. For example, this may be because the user clicked on a menu item. This is not a notification that this particularly popup lost focus.

Specified by:

editorFocusLost in interface oracle.javatools.editor.popup.PopupWindowListener

Parameters:

popupWindow - the popup window that this notification is being delivered for

isTemporary - whether the loss of focus is temporary

caretUpdate

public void caretUpdate(javax.swing.event.CaretEvent event)

Called when the caret position is updated.

Specified by:

caretUpdate in interface javax.swing.event.CaretListener

Parameters:

event - the caret event

updateInsight

protected void updateInsight()

Utility routine which takes care of updating the Insight information which is currently displayed. This is generally called after the document is modified or caret position is changed.

getPreferredLocations

protected int[] getPreferredLocations()

Fetch an array of preferred locations where this insight implementation would like to display its view. The positions should be specified in order of decreasing preference.

Returns:

an array of preferred locations, such as { SE, SW, NW, NE }.

lookupCommand

protected static int lookupCommand(java.lang.String actionKey)

Utility routine which maps an action name (such as "caret-down") to one of our private constants (like UP_COMMAND.)

Parameters:

actionKey - the name of the action

Returns:

one of our command constants corresponding to the action