oracle.jdeveloper.ceditor
Class CodeEditor

java.lang.Object
  oracle.ide.addin.AbstractView
      oracle.ide.editor.AbstractEditor
          oracle.jdeveloper.ceditor.CodeEditor

All Implemented Interfaces:

BaseLayoutListener, javax.swing.event.CaretListener, Editor, java.util.EventListener, oracle.jdeveloper.ceditor.find.FindableEditor, Helpable, LayoutSelector, Observer, Subview, ToolTipProvider, javax.swing.event.UndoableEditListener, View

public final class CodeEditor

extends AbstractEditor

implements javax.swing.event.CaretListener, oracle.jdeveloper.ceditor.find.FindableEditor, ToolTipProvider, javax.swing.event.UndoableEditListener, BaseLayoutListener

The CodeEditor is the integration layer between the IDE and the editor components to provide a code editor inside the IDE.

There are some public methods available for getting the state of the editor component, such as where the cursor position is, and whether there is a selection. There are also public methods available for manipulating the cursor position or selection, and for mapping between offsets and lines.

Note: Public methods in this class involving line numbers are all 1-based. Contrast this with the LineMap interface in the TextBuffer which is 0-based. Do not get this mixed up! If you use both the LineMap and CodeEditor together, you will need to take this into account.

For clients that wish to install EditorPlugins to newly created editors, register an EditorPluginsFactory instance using registerFactory(). This method will be called when an editor is created.

Nested Class Summary

Nested classes inherited from class oracle.ide.editor.AbstractEditor

AbstractEditor.LayoutData

Field Summary

static javax.swing.border.Border	THIN_BEVEL_BORDER This is a bevel border that is thinner (1 pixel) than the default bevel border (2 pixels) available in Swing.
static java.lang.String	TYPE_CPP The syntax highlighting type for C++ files.
static java.lang.String	TYPE_HTML The syntax highlighting type for HTML files.
static java.lang.String	TYPE_IDL The syntax highlighting type for IDL files.
static java.lang.String	TYPE_JAVA The syntax highlighting type for Java files.
static java.lang.String	TYPE_JSP THe syntax highlighting type for JSP files.
static java.lang.String	TYPE_PLAIN The syntax highlighting type for plain files.
static java.lang.String	TYPE_PLSQL The syntax highlighting type for PL/SQL files.
static java.lang.String	TYPE_PROPERTIES The syntax highlighting type for Properties files.
static java.lang.String	TYPE_SQL The syntax highlighting type for SQL files.
static java.lang.String	TYPE_XML The syntax highlighting type for XML files.

Fields inherited from class oracle.ide.editor.AbstractEditor

_context, _editorFrame, CUSTOM_BORDER

Fields inherited from class oracle.ide.addin.AbstractView

owner, SEPARATOR, viewListeners, viewSelectionListeners

Fields inherited from interface oracle.ide.addin.View

PROJECT_PROP, VISIBLE_PROP, WORKSPACE_PROP

Constructor Summary

CodeEditor()
Constructs a new Code Editor which makes use of the editor package.

Method Summary

void	addCEToolTipProvider(CEToolTipProvider provider) Registers a CEToolTipProvider implementation to receive requests for tooltip information when the mouse travels over the code editor.
void	addCursorListener(CursorListener listener) Adds a CursorListener to the list of cursor listeners.
void	addHelpableProvider(HelpableProvider helpableProvider) Adds a HelpableProvider for this class from which the code editor can retrieve help info.
protected boolean	canCopy() Deprecated.
protected boolean	canCut() Deprecated.
protected boolean	canPaste() Deprecated.
void	caretUpdate(javax.swing.event.CaretEvent event) Called when the caret position is updated.
void	close() Close this editor - this gives us a chance to clean up any resources.
void	close(Layout layout) Close the given Layout.
static HighlightStyle	createHighlightStyle(java.lang.String internalName, java.lang.String publicName, int priority, java.awt.Color fgColor, java.awt.Color bgColor) Utility routine to create a new highlight style that is registered with the code editor - this ensures the it is available for editing in the editor options panels.
int	getCaretLine() Return the line that the caret is on.
int	getCaretPosition() Returns the position of the text insertion caret for the editor component.
Controller	getController() Gets the Controller associated with this view.
java.awt.Component	getDefaultFocusComponent() This method is used to know what component should get the focus by default.
protected BasicEditorPane	getEditorComponent() Primarily for the controller to use to get access to the component to do cut/copy/paste
protected java.lang.String	getEditorText() Get the contents of the editor as a String for refreshing the IDE buffer.
BasicEditorPane	getFocusedEditorPane() Fetches the focused (active) editor pane embedded in the editor in which to perform Find operations on.
java.awt.Component	getGUI() Get the view's root graphical user interface component.
CodeEditorGutter	getGutter() Fetches the gutter associated with this editor on the left margin.
HelpableProvider	getHelpableProvider() Deprecated.
HelpInfo	getHelpInfo() Fetch the HelpInfo topic to display for this view.
int	getLineCount() Fetches the number of lines in this TextBuffer.
int	getLineEndOffset(int line) Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.
int	getLineFromOffset(int offset) Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias.
int	getLineStartOffset(int line) Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.
java.lang.String	getSelectedText() Returns the selected text contained in this TextComponent.
int	getSelectionEnd() Returns the end position of the current text selection.
int	getSelectionStart() Returns the start position of the current text selection.
javax.swing.Icon	getTabIcon() Get the Icon to use when displaying this View as a tab in a JTabbedPane host such as the EditorFrame.
java.lang.String	getText(int offset, int length) Fetches a portion of the text represented by the component.
java.lang.String	getToolTipText(BasicEditorPane editorPane, java.awt.event.MouseEvent mouseEvent, int offset) Requests from the editor client an appropriate tooltip to display for the given editor.
boolean	gotoLine(int line, int column, boolean highlightLine) Moves the current cursor position to the beginning of the indicated line, and highlight the line if it is requested.
boolean	gotoOffset(int offset, int selectionLength) Moves the current cursor position to the given offset, and selects up to the given length after that offset.
boolean	hasSelectedText() Return whether or not there is any text selected.
void	init(Layout layout) Initialize this editor's layout information from the given Layout instance.
void	moveCaretPosition(int offset) Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called.
void	open() Open this editor on the context set by a prior call to setContext.
static void	registerDocumentType(java.lang.Class documentClass, java.lang.String highlightingType) Registers the given document class for the given syntax highlighting type to use.
static void	registerFactory(EditorPluginsFactory factory) Registers an EditorPluginsFactory with the CodeEditor so that when a new Code Editor is created, the factory is given a chance to create EditorPlugins to be installed into the editor based on the node type that the Code Editor was created with.
void	removeCEToolTipProvider(CEToolTipProvider provider) Deregisters a previously registered CEToolTipProvider implementation when it no longer wants to handle tooltip requests.
void	removeCursorListener(CursorListener listener) Removes a CursorListener from the list of cursor listeners.
void	removeHelpableProvider(HelpableProvider helpableProvider) Removes a previously registered HelpableProvider.
void	replaceSelection(java.lang.String content) Replaces the currently selected content with the new content represented by the given String.
void	save(Layout layout) Save this editor's layout information to the given Layout instance.
void	setCaretPosition(int offset) Sets the position of the text insertion caret for the editor component.
void	setContext(Context context) Set the context behind this editor.
void	setHelpableProvider(HelpableProvider helpableProvider) Deprecated.
void	setHelpInfo(HelpInfo helpInfo) Sets the default help info topic that this code editor displays.
void	setSelectionEnd(int selectionEnd) Sets the end of the selection to the specified position.
void	setSelectionStart(int selectionStart) Sets the start of the selection to the specified position.
void	undoableEditHappened(javax.swing.event.UndoableEditEvent event) An UndoableEdit happened in the editor.
void	update(java.lang.Object observed, UpdateMessage change) Notification message.

Methods inherited from class oracle.ide.editor.AbstractEditor

addPreferredLayoutListener, getContext, getContext, getContextMenu, getDependentDocuments, getDisplayName, getEditorFrame, getPreferredLayoutBaseName, getPreferredLayoutMap, getPreferredLayoutURL, getTabDescription, getTabLabel, getTitleLabel, getType, initializeActiveLayout, isReady, newId, onPreferredLayoutActivate, owner, removePreferredLayoutListener, setOwner, setPreferredLayoutBaseName, setPreferredLayoutMap, setPreferredLayoutURL, setType

Methods inherited from class oracle.ide.addin.AbstractView

activate, addViewListener, addViewSelectionListener, deactivate, fireViewActivated, fireViewClosed, fireViewDeactivated, fireViewSelectionChanged, getId, getSelection, getToolbar, isVisible, loadToolbar, loadToolbar, removeViewListener, removeViewSelectionListener, setId, setOwner, show, updateTitle

Methods inherited from class java.lang.Object

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

Methods inherited from interface oracle.ide.addin.View

activate, addViewListener, addViewSelectionListener, deactivate, getId, getSelection, getToolbar, removeViewListener, removeViewSelectionListener, updateTitle

Methods inherited from interface oracle.ide.addin.Subview

isVisible, show

Field Detail

TYPE_PLAIN

public static final java.lang.String TYPE_PLAIN

The syntax highlighting type for plain files.

TYPE_JAVA

public static final java.lang.String TYPE_JAVA

The syntax highlighting type for Java files.

TYPE_SQL

public static final java.lang.String TYPE_SQL

The syntax highlighting type for SQL files. Currently the same as PL/SQL.

TYPE_PLSQL

public static final java.lang.String TYPE_PLSQL

The syntax highlighting type for PL/SQL files.

TYPE_JSP

public static final java.lang.String TYPE_JSP

THe syntax highlighting type for JSP files.

TYPE_HTML

public static final java.lang.String TYPE_HTML

The syntax highlighting type for HTML files.

TYPE_XML

public static final java.lang.String TYPE_XML

The syntax highlighting type for XML files.

TYPE_PROPERTIES

public static final java.lang.String TYPE_PROPERTIES

The syntax highlighting type for Properties files.

TYPE_IDL

public static final java.lang.String TYPE_IDL

The syntax highlighting type for IDL files.

TYPE_CPP

public static final java.lang.String TYPE_CPP

The syntax highlighting type for C++ files.

THIN_BEVEL_BORDER

public static final javax.swing.border.Border THIN_BEVEL_BORDER

This is a bevel border that is thinner (1 pixel) than the default bevel border (2 pixels) available in Swing.

Constructor Detail

CodeEditor

public CodeEditor()

Constructs a new Code Editor which makes use of the editor package.

Method Detail

registerFactory

public static void registerFactory(EditorPluginsFactory factory)

Registers an EditorPluginsFactory with the CodeEditor so that when a new Code Editor is created, the factory is given a chance to create EditorPlugins to be installed into the editor based on the node type that the Code Editor was created with.

Parameters:

factory - the EditorPluginsFactory to register

registerDocumentType

public static void registerDocumentType(java.lang.Class documentClass,
                                        java.lang.String highlightingType)

Registers the given document class for the given syntax highlighting type to use. The syntax highlighting type specified should be one of the TYPE_* public constants specified in this class. The provided document class MUST implement the TextDocument interface, as only TextDocument implementations are editable by the code editor.

Parameters:

documentClass - the class of the document to register

highlightingType - the syntax highlighting type to use

createHighlightStyle

public static HighlightStyle createHighlightStyle(java.lang.String internalName,
                                                  java.lang.String publicName,
                                                  int priority,
                                                  java.awt.Color fgColor,
                                                  java.awt.Color bgColor)

Utility routine to create a new highlight style that is registered with the code editor - this ensures the it is available for editing in the editor options panels.

Parameters:

internalName - the (unique) name of the style used internally for registration purposes

publicName - the (translated) name of the style that can be used for UI purposes to identify the style

priority - the priority of the highlight when rendering, from 1 to 100

fgColor - the color to use for the foreground of the text, null not to change the foreground of the text

bgColor - the color to use for the background of the text, null not to change the background of the text

getText

public java.lang.String getText(int offset,
                                int length)
                         throws javax.swing.text.BadLocationException

Fetches a portion of the text represented by the component. Returns an empty String if the length is 0.

Parameters:

offset - the starting offset >= 0

length - the length to retrieve >= 0

Returns:

the text requested

Throws:

javax.swing.text.BadLocationException - if the offset or length are invalid

setCaretPosition

public void setCaretPosition(int offset)

Sets the position of the text insertion caret for the editor component. The caret tracks change, so it may move if the underlying text of the component is changed.

Parameters:

offset - the new caret position to set

moveCaretPosition

public void moveCaretPosition(int offset)

Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called. This forms a selection.

Parameters:

offset - the offset to move the caret to

See Also:

setCaretPosition(int)

getCaretPosition

public int getCaretPosition()

Returns the position of the text insertion caret for the editor component.

Returns:

the caret position of the editor

getCaretLine

public int getCaretLine()

Return the line that the caret is on. This will map the offset of the caret position to the given line in the document. Note that the line number is one-based and that the caret position biases to the right - this means if the caret is between a new line and a character, the line number returned is for the line of the character. This will return 0 if there is no document, or an error has occurred.

Returns:

the line number that the caret is on (1-based)

replaceSelection

public void replaceSelection(java.lang.String content)

Replaces the currently selected content with the new content represented by the given String. We override the implementation of JTextComponent so that the whole replace can be a single undoable operation.

Parameters:

content - the new content to replace the current selection

hasSelectedText

public boolean hasSelectedText()

Return whether or not there is any text selected.

Returns:

true if there is a text selection, false otherwise

getSelectedText

public java.lang.String getSelectedText()

Returns the selected text contained in this TextComponent. If the selection is null or the document empty, returns null.

Returns:

the currently selected text if any

Throws:

java.lang.IllegalArgumentException - if the selection doesn't have a valid mapping into the document for some reason

getSelectionStart

public int getSelectionStart()

Returns the start position of the current text selection. Returns 0 for an empty document, or the current caret offset if there is no selection.

Returns:

the start of the selection or the current caret position

getSelectionEnd

public int getSelectionEnd()

Returns the end position of the current text selection. Returns 0 for an empty document, or the current caret offset if there is no selection.

Returns:

the end of the selection or the current caret position

setSelectionStart

public void setSelectionStart(int selectionStart)

Sets the start of the selection to the specified position. The new starting point is constrained to be before or at the current selection end.

Parameters:

selectionStart - the new start of the selection

setSelectionEnd

public void setSelectionEnd(int selectionEnd)

Sets the end of the selection to the specified position. The new ending point is constrained to be at or after the current selection start.

Parameters:

selectionEnd - the new end of the selection

addCursorListener

public void addCursorListener(CursorListener listener)

Adds a CursorListener to the list of cursor listeners.

Parameters:

listener - the listener to add

removeCursorListener

public void removeCursorListener(CursorListener listener)

Removes a CursorListener from the list of cursor listeners.

Parameters:

listener - the listener to remove

getGutter

public CodeEditorGutter getGutter()

Fetches the gutter associated with this editor on the left margin. This can be used for placing icons there.

Returns:

the gutter

addCEToolTipProvider

public void addCEToolTipProvider(CEToolTipProvider provider)

Registers a CEToolTipProvider implementation to receive requests for tooltip information when the mouse travels over the code editor. Note that only a single tooltip provider can be registered at any given time. The LAST provider to register for tooltips will be the one to be notified of requests.

Parameters:

provider - the tooltip provider to register

removeCEToolTipProvider

public void removeCEToolTipProvider(CEToolTipProvider provider)

Deregisters a previously registered CEToolTipProvider implementation when it no longer wants to handle tooltip requests. Note that if the specified provider is not the current active registered provider, then the request is ignored.

Parameters:

provider - the provider to deregister

gotoOffset

public boolean gotoOffset(int offset,
                          int selectionLength)

Moves the current cursor position to the given offset, and selects up to the given length after that offset. If the offset specified is invalid, it will attempt to move to the closest position to the offset. If the offset is valid but the selection length is invalid, it will not select anything.

Parameters:

offset - the offset to move the cursor to (zero-based)

selectionLength - the length of the selection, 0 if not desired.

Returns:

true if the offset and selectionLength specified is valid

gotoLine

public boolean gotoLine(int line,
                        int column,
                        boolean highlightLine)

Moves the current cursor position to the beginning of the indicated line, and highlight the line if it is requested. If the line specified is invalid, it will attempt to move to the closest position and return false. If the line is offscreen, this will recenter the editor view on the line.

Parameters:

line - the line to go to (one-based)

column - the column to go to (one-based)

highlightLine - whether to highlight the specified line

Returns:

true if the line specified is valid

getFocusedEditorPane

public BasicEditorPane getFocusedEditorPane()

Fetches the focused (active) editor pane embedded in the editor in which to perform Find operations on. If there is more than one editor pane, the one with focus should be returned. If the focus is not currently on an editor pane, then null should be returned.

Specified by:

getFocusedEditorPane in interface oracle.jdeveloper.ceditor.find.FindableEditor

Returns:

the instance of the embedded BasicEditorPane that currently has focus

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

getLineCount

public int getLineCount()

Fetches the number of lines in this TextBuffer. For example, a 5-line TextBuffer has lines 0 through 4.

Returns:

number of lines in TextBuffer

getLineFromOffset

public int getLineFromOffset(int offset)

Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias. This means if line A starts with offset B, and previous line A-1 ends with offset B, getLineFromOffset(B) will return line A.

Returns:

the line containing an offset

getLineStartOffset

public int getLineStartOffset(int line)

Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.

Parameters:

line - a line in the TextBuffer

Returns:

the starting offset of the specified line

getLineEndOffset

public int getLineEndOffset(int line)

Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.

Parameters:

line - a line in the TextBuffer

Returns:

the ending offset of the specified line

setContext

public void setContext(Context context)

Set the context behind this editor.

Specified by:

setContext in interface Editor

Overrides:

setContext in class AbstractEditor

open

public void open()

Open this editor on the context set by a prior call to setContext.

Specified by:

open in interface Editor

See Also:

Editor.setContext(oracle.ide.addin.Context)

getDefaultFocusComponent

public java.awt.Component getDefaultFocusComponent()

This method is used to know what component should get the focus by default. The returned component should be a child of the component returned by getGUI() or getGUI() itself and should be requestFocusable. By contract, getGUI() will always be called before getDefaultFocusComponent()

Specified by:

getDefaultFocusComponent in interface Editor

Overrides:

getDefaultFocusComponent in class AbstractEditor

Returns:

the component that should take the focus

close

public void close()

Close this editor - this gives us a chance to clean up any resources. Note, although the editor is closed, the UndoableEdits continue to survive in the CommandProcessor queue! This means that we cannot clean out anything that that functionality (undo) depends on.

Specified by:

close in interface Subview

Overrides:

close in class AbstractEditor

getController

public Controller getController()

Gets the Controller associated with this view.

Specified by:

getController in interface Subview

Overrides:

getController in class AbstractView

Returns:

the controller associated with this view.

getGUI

public java.awt.Component getGUI()

Get the view's root graphical user interface component.

Specified by:

getGUI in interface Subview

Returns:

the root graphical user component

getTabIcon

public javax.swing.Icon getTabIcon()

Get the Icon to use when displaying this View as a tab in a JTabbedPane host such as the EditorFrame.

Specified by:

getTabIcon in interface Editor

Overrides:

getTabIcon in class AbstractEditor

See Also:

EditorFrame

update

public void update(java.lang.Object observed,
                   UpdateMessage change)

Notification message. Subjects call this method when they notify their observers that the subjects state has changed.

Specified by:

update in interface Observer

Parameters:

observed - the subject whose state has changed.

change - what has changed.

getToolTipText

public java.lang.String getToolTipText(BasicEditorPane editorPane,
                                       java.awt.event.MouseEvent mouseEvent,
                                       int offset)

Requests from the editor client an appropriate tooltip to display for the given editor. The mouseEvent describes where the cursor is an what the mouse event was (i.e., mouse moved), and the offset is the location in the editor (document) corresponding to the current mouse cursor.

Specified by:

getToolTipText in interface ToolTipProvider

Parameters:

editorPane - the editor where the tooltip will be displayed

mouseEvent - the mouse event that generated the tooltip

offset - the document offset where the mouse cursor is located

Returns:

the tooltip text to display

undoableEditHappened

public void undoableEditHappened(javax.swing.event.UndoableEditEvent event)

An UndoableEdit happened in the editor. Generate a matching one in the IDE.

Specified by:

undoableEditHappened in interface javax.swing.event.UndoableEditListener

save

public void save(Layout layout)

Save this editor's layout information to the given Layout instance.

The code editor saves the caret position and the vertical scrollbar value.

Specified by:

save in interface BaseLayoutListener

Parameters:

layout - the Layout instance

init

public void init(Layout layout)

Initialize this editor's layout information from the given Layout instance.

The code editor restores the caret position and the vertical scrollbar value from the values stored in the Layout instance.

Specified by:

init in interface BaseLayoutListener

Parameters:

layout - the Layout instance

close

public void close(Layout layout)

Close the given Layout.

Specified by:

close in interface BaseLayoutListener

Parameters:

layout - the Layout instance

getHelpInfo

public HelpInfo getHelpInfo()

Fetch the HelpInfo topic to display for this view.

Specified by:

getHelpInfo in interface Helpable

Overrides:

getHelpInfo in class AbstractView

Returns:

the help info to display

setHelpInfo

public void setHelpInfo(HelpInfo helpInfo)

Sets the default help info topic that this code editor displays.

Parameters:

helpInfo - the default help info topic that should be displayed

addHelpableProvider

public void addHelpableProvider(HelpableProvider helpableProvider)

Adds a HelpableProvider for this class from which the code editor can retrieve help info. This can be used to return context-sensitive help info for the current editor caret position. Note that the code editor will query registered HelpableProvider's until it gets the first non-null help info. To change the default non-context-sensitive help topic, use setHelpInfo() instead.

Parameters:

helpableProvider - the helpable provider to register

removeHelpableProvider

public void removeHelpableProvider(HelpableProvider helpableProvider)

Removes a previously registered HelpableProvider.

Parameters:

helpableProvider - the helpableProvider to deregister

setHelpableProvider

public void setHelpableProvider(HelpableProvider helpableProvider)

Deprecated.

Sets the HelpableProvider for this class. The

Parameters:

helpableProvider - The class to delegate to for help.

getHelpableProvider

public HelpableProvider getHelpableProvider()

Deprecated.

Gets the HelpableProvider for this class if one exists, othewise null will be returned. This is deprecated and will always return null.

getEditorComponent

protected BasicEditorPane getEditorComponent()

Primarily for the controller to use to get access to the component to do cut/copy/paste

getEditorText

protected java.lang.String getEditorText()

Get the contents of the editor as a String for refreshing the IDE buffer.

Returns:

the contents of the editor document

canCut

protected boolean canCut()

Deprecated.

Determine whether we should enable the Edit->Cut menu.

Returns:

if we can perform a cut now

canCopy

protected boolean canCopy()

Deprecated.

Determine whether we should enable the Edit->Copy menu.

Returns:

if we can perform a copy now

canPaste

protected boolean canPaste()

Deprecated.

Determine whether we should enable the Edit->Paste menu.

Returns:

if we can perform a paste now