oracle.javatools.editor.insight
Interface Insight

All Superinterfaces:

EditorPlugin, java.util.EventListener, java.beans.PropertyChangeListener

All Known Implementing Classes:

AbstractInsight

public interface Insight

extends EditorPlugin

The Insight interface describes the public API available for programmatically invoking code insight. Implementations of the Insight interface should be responsible for responding to various user input to invoke Insight features, such as responding to various character typed triggers, or to navigation commands while Insight information is up.

The Insight interface extends EditorPlugin to provide Insight implementations with well-defined places to take care of being installed into, and de-installed from a BasicEditorPane as well as to respond to property changes in the editor framework.

Note that the public methods do not pass the editor pane as a parameter. This is because each Insight instance is intended to be associated with and installed into a single BasicEditorPane.

Insight Categories:

Insight features fall into two general categories. The first category provides completion features, such as Java Member Insight or Java Class Insight. When these Insight features are engaged, a floating list of identifying names is displayed. The user may navigate through the list using the standard navigation commands (Up-Arrow, Down-Arrow, ...) as well as to accept the current selection in the list (which will place the selected name into the document.)

Since the completion insight (while a list is being displayed) will steal editor navigation commands, there should only be one completion insight active at any given time. It is the responsibility of editor clients to ensure that only one completion Insight window is displayed at any given time. Otherwise, unpredictable results may occur.

The second category provides tooltip features, such as Java Parameter Insight. This is similar to completion insight except that completion functionality (hitting Enter to accept) is not available. The displayed information is intended to be informational only as a hint, and therefore is displayed as a tooltip.

For editor clients that use more than one Insight implementation, it is their responsibility to ensure that the displayed windows do not interfere with each other - this Insight framework does not currently provide support for making sure that different Insight Windows do not overlap or obscure each other.

Insight Triggers:

Insight is generally triggered one of three ways:

• Typed Characters: Insight can be triggered in response to certain typed characters followed by a user delay to indicate that Insight help is needed. For example, the period "." and left parenthesis "(" are the typical trigger characters for Java.
• Manually Invoked: Insight can also be invoked manually by the user (i.e., Control-Space) for faster response rather then waiting for the delay timer to fire.
• Automatic Continuation: Insight may also re-invoke it self following an Insight completion (user hit Enter) if it is appropriate.

See Also:

AbstractInsight, InsightProvider, InsightData, InsightView

Method Summary

void	clearPopupTimer() Clears the delay timer for auto-popping up Insight, effectively cancelling the request.
void	hideInsight() Cancels an existing insight window that is displaying insight information.
boolean	isInsightVisible() Returns whether there is an Insight window displayed right now.
void	restartPopupTimer() Starts (or restarts) the auto-popup delay timer for this Insight feature.
void	showInsight() Instructs this insight to check whether there is insight information availble, and if so, to bring up an insight window.

Methods inherited from interface oracle.javatools.editor.plugins.EditorPlugin

deinstall, install

Methods inherited from interface java.beans.PropertyChangeListener

propertyChange

Method Detail

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.

This method may be invoked programmatically to request that Insight be brought up after a suitable delay. It is up to each Insight implementation to determine what type of user input or response is appropriate for cancelling the auto-popup request (i.e., say the user keeps on typing.)

Since this is just a request to initiate Insight at some point in the future, there is no return result available.

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.

See Also:

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.

Returns:

true if this Insight implementation has an Insight window up

showInsight

public void showInsight()

Instructs this insight to check whether there is insight information availble, and if so, to bring up an insight window. This can be called to invoke Insight programmatically without a timer delay (such as if the user hits a command to request insight.) Note that this routine does not provide a return status, so the caller does not have a way to find out if the insight query was successful or not.

This is expected to be a blocking call - the underlying document of the editor should be locked with at least a read lock for the duration of this call to ensure that the document is not modified while the Insight query is happening. If there is Insight information available, an Insight window will be displayed to provide the user with this information.

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.