oracle.javatools.editor.highlight

Class HighlightLayer

java.lang.Object

oracle.javatools.editor.highlight.HighlightLayer

public final class HighlightLayer
extends java.lang.Object

A HighlightedLayer is a container for highlights added to an editor pane. Highlights are segments of text are created in a specific highlight layer rather than directly in the editor pane. This allows different modules to maintain and manipulate their highlights in separate layers without affect each other.

Let's visit an example of how to highlight text - take the example of the selected text maintained by the caret. In order for the caret to have the selected text highlighted, it needs to create a highlight layer and add it to the editor pane. Once the layer is added, it can add, change, or remove highlights using the highlight layer directly. The highlight layer will take care of making sure the editor view is kept up-to-date as far as painting is concerned.

There are certain highlights that track a line, such as a caret line, or breakpoint line. Use addLineHighlight() for creating such a line highlight. Line highlights cannot be changed to non-line highlights once created.

Note that highlighted text are created using buffer OffsetMarks and will track those offsets when the buffer changes.

In end of line cases, background attributes and underlines are handled and painted differently. Note that text-based applies to highlighted regions through addHighlight(), while line-based applies to highlighted regions through addLineHighlight:

• When applying text-based background attributes at the end of a line, the background will be painted across the full width of the editor if the region includes the end of line character. At the end of a file (very last line), text-based background attributes do not extend across the full width of the editor.
• When applying line-based background attributes, background will always be painted across the full width of the editor, including the last line (end of file) of the editor.
• When applying text-based underline (including separator) attributes, the underline will never be painted across the full width of the editor.
• When applying line-based underline (including separator) attributes, the underline will always be painted across the full-width of the editor, including the last line (end of file) of the editor.

Clients should be aware of this behavior, particularly with underlines and separators, to get the desired effect at an end of line location.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FETCH_ALL_HIGHLIGHTS Constant for all highlight types, whether offset-range, or line-based.
static int	FETCH_LINE_HIGHLIGHTS Constant for line-based highlights only (excludes offset range-based).
static int	FETCH_RANGE_HIGHLIGHTS Constant for offset-range based highlights only (excludes line-based).

Constructor Summary

Constructors

Constructor and Description
HighlightLayer(BasicEditorPane editor) Constructs a new highlight layer associated with the given editor.

Method Summary

Methods

Modifier and Type	Method and Description
HighlightedText	addHighlight(HighlightStyle style, int startOffset, boolean startOffsetBias, int endOffset, boolean endOffsetBias) Adds a highlight to the editor pane using the specified style and offsets.
HighlightedText	addHighlight(HighlightStyle style, int startOffset, int endOffset) Adds a highlight to the editor pane using the specified style and offsets.
HighlightedText	addLineHighlight(HighlightStyle style, int line) Adds a highlight to the editor pane using the specified style and offsets.
void	beginBlockUpdate() Begins a block update.
void	changeHighlight(HighlightedText highlightedText, HighlightStyle newHighlightStyle) Changes the highlight style of the previously created highlighted region of text.
void	changeHighlight(HighlightedText highlightedText, HighlightStyle newHighlightStyle, int newStartOffset, int newEndOffset) Moves the highlight region to a new set of offsets in the editor, and changes the highlight style used.
void	changeHighlight(HighlightedText highlightedText, int newStartOffset, int newEndOffset) Moves the highlight region to a new set of offsets in the editor.
void	changeLineHighlight(HighlightedText highlightedLine, HighlightStyle newHighlightStyle, int newLine) Moves the highlighted line to the new line in the editor, and sets a new highlight to use.
void	destroy() Destroy this layer in it's editor.
void	endBlockUpdate() Ends a block update.
BasicEditorPane	getEditor()
void	removeAllHighlights() Removes all highlights in this layer from the associated editor pane.
void	removeHighlight(HighlightedText highlightedText) Removes the given highlight from the editor pane.
void	renderHighlights(HighlightFragmentsList fragmentsList, int startOffset, int endOffset) This routine is used by the editor view to obtain all of the highlights in this highlight layer in the given offset range.
void	renderHighlights(HighlightFragmentsList fragmentsList, int fetchPolicy, int startOffset, int endOffset) This routine is used by the editor view to obtain all of the highlights in this highlight layer in the given offset range.

Methods inherited from class java.lang.Object

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

Field Detail

FETCH_ALL_HIGHLIGHTS

public static final int FETCH_ALL_HIGHLIGHTS

Constant for all highlight types, whether offset-range, or line-based.

See Also:

Constant Field Values

FETCH_RANGE_HIGHLIGHTS

public static final int FETCH_RANGE_HIGHLIGHTS

Constant for offset-range based highlights only (excludes line-based). For this case, HighlightedText,isLineHighlight() will return false.

See Also:

Constant Field Values

FETCH_LINE_HIGHLIGHTS

public static final int FETCH_LINE_HIGHLIGHTS

Constant for line-based highlights only (excludes offset range-based). For this case, HighlightedText.isLineHighlight() will return true.

See Also:

Constant Field Values

Constructor Detail

HighlightLayer

public HighlightLayer(BasicEditorPane editor)

Constructs a new highlight layer associated with the given editor.

Method Detail

getEditor

public BasicEditorPane getEditor()

destroy

public void destroy()

Destroy this layer in it's editor.

beginBlockUpdate

public void beginBlockUpdate()

Begins a block update. During a block update, display updates caused by adding or removing an underline are deferred to endBlockUpdate().

endBlockUpdate

public void endBlockUpdate()

Ends a block update. Updates the display for underlines added or removed during the block update.

addHighlight

public HighlightedText addHighlight(HighlightStyle style,
                           int startOffset,
                           int endOffset)

Adds a highlight to the editor pane using the specified style and offsets.

Parameters:

style - the highlight style to use

startOffset - the start of the highlighted segment of text

endOffset - the end of the highlighted segment of text

addHighlight

public HighlightedText addHighlight(HighlightStyle style,
                           int startOffset,
                           boolean startOffsetBias,
                           int endOffset,
                           boolean endOffsetBias)

Adds a highlight to the editor pane using the specified style and offsets.

Parameters:

style - the highlight style to use

startOffset - the start of the highlighted segment of text

startOffsetBias - the OffsetMark.BIAS_* for the start offset

endOffset - the end of the highlighted segment of text

endOffsetBias - the OffsetMark.BIAS_* for the end offset

addLineHighlight

public HighlightedText addLineHighlight(HighlightStyle style,
                               int line)

Adds a highlight to the editor pane using the specified style and offsets.

Parameters:

style - the highlight style to use

line - the 0-based line to highlight

Returns:

the line highlight instance, or null if the specified line is invalid

removeHighlight

public void removeHighlight(HighlightedText highlightedText)

Removes the given highlight from the editor pane.

Parameters:

highlightedText - the highlight to remove

removeAllHighlights

public void removeAllHighlights()

Removes all highlights in this layer from the associated editor pane.

changeLineHighlight

public void changeLineHighlight(HighlightedText highlightedLine,
                       HighlightStyle newHighlightStyle,
                       int newLine)

Moves the highlighted line to the new line in the editor, and sets a new highlight to use.

Parameters:

highlightedLine - the highlighted line that was previously created

newHighlightStyle - new highlight style

newLine - the new line to move the highlight to

changeHighlight

public void changeHighlight(HighlightedText highlightedText,
                   HighlightStyle newHighlightStyle)

Changes the highlight style of the previously created highlighted region of text.

Parameters:

highlightedText - the highlight that was previously created

newHighlightStyle - the new highlight style to use

changeHighlight

public void changeHighlight(HighlightedText highlightedText,
                   int newStartOffset,
                   int newEndOffset)

Moves the highlight region to a new set of offsets in the editor.

Parameters:

highlightedText - the highlight that was previously created

newStartOffset - the new starting location for the highlight

newEndOffset - the new ending location for the highlight

changeHighlight

public void changeHighlight(HighlightedText highlightedText,
                   HighlightStyle newHighlightStyle,
                   int newStartOffset,
                   int newEndOffset)

Moves the highlight region to a new set of offsets in the editor, and changes the highlight style used.

Parameters:

highlightedText - the highlight that was previously created

newHighlightStyle - the new highlight style to use

newStartOffset - the new starting location for the highlight

newEndOffset - the new ending location for the highlight

renderHighlights

public void renderHighlights(HighlightFragmentsList fragmentsList,
                    int startOffset,
                    int endOffset)

This routine is used by the editor view to obtain all of the highlights in this highlight layer in the given offset range. Filtering for attributes are performed by the HighlightFragmentsList itself, as it has to lookup the real style configurations in the HighlightRegistry.

Parameters:

fragmentsList - the list to add the text highlight fragments to

startOffset - the start of the rendering area

endOffset - the end of the rendering area

renderHighlights

public void renderHighlights(HighlightFragmentsList fragmentsList,
                    int fetchPolicy,
                    int startOffset,
                    int endOffset)

This routine is used by the editor view to obtain all of the highlights in this highlight layer in the given offset range. Filtering for attributes are performed by the HighlightFragmentsList itself, as it has to lookup the real style configurations in the HighlightRegistry.

Parameters:

fragmentsList - the list to add the text highlight fragments to

fetchPolicy - the highlight fetch policy, such as whether to include only line highlights with FETCH_LINE_HIGHLIGHTS

startOffset - the start of the rendering area

endOffset - the end of the rendering area