org.netbeans.spi.editor.highlighting.support

Class OffsetsBag

java.lang.Object

org.netbeans.spi.editor.highlighting.support.AbstractHighlightsContainer

org.netbeans.spi.editor.highlighting.support.OffsetsBag

All Implemented Interfaces:

HighlightsContainer

public final class OffsetsBag
extends AbstractHighlightsContainer

A bag of highlighted areas specified by their offsets in a document.

The highlighted areas (highlights) are determined by their starting and ending offsets in a document and the set of attributes that should be used for rendering that area. The highlights can be arbitrarily added to and remove from this bag.

The OffsetsBag is designed to work over a single document, which is passed in to the constructor. All offsets accepted by various methods in this class must refer to positions within this document. Therefore any offsets passed in to the methods in this class have to be equal to or greater than zero and less than or equal to the document size.

The OffsetsBag can operate in two modes depending on a value passed in its construtor. The mode determines how the bag will treat newly added highlights that overlap with existing highlights in the bag.

Trimming mode: In the trimming mode the bag will trim any existing highlights that would overlap with a newly added highlight. In this mode the newly added highlights always replace the existing highlights if they overlap.

Merging mode: In the merging mode the bag will merge attributes of the overlapping highlights. The area where the new highlight overlaps with some existing highlights will then constitute a new highlight, which attributes will be a composition of the attributes of both the new and existing highlight. Should there be attributes with the same name the attribute values from the newly added highlight will take precedence.

Field Summary

Fields inherited from interface org.netbeans.spi.editor.highlighting.HighlightsContainer

ATTR_EXTENDS_EMPTY_LINE, ATTR_EXTENDS_EOL

Constructor Summary

Constructors

Constructor and Description
OffsetsBag(Document document) Creates a new instance of OffsetsBag, which trims highlights as they are added.
OffsetsBag(Document document, boolean mergeHighlights) Creates a new instance of OffsetsBag.

Method Summary

Modifier and Type	Method and Description
void	addAllHighlights(HighlightsSequence bag) Adds all highlights from the bag passed in.
void	addHighlight(int startOffset, int endOffset, AttributeSet attributes) Adds a highlight to this bag.
void	clear() Removes all highlights previously added to this bag.
void	discard() Discards this OffsetsBag.
HighlightsSequence	getHighlights(int startOffset, int endOffset) Gets highlights from an area of a document.
void	removeHighlights(int startOffset, int endOffset, boolean clip) Removes highlights in a specific area of the document.
void	setHighlights(HighlightsSequence seq) Resets this bag to use the new set of highlights.
void	setHighlights(OffsetsBag bag) Resets this bag to use the new set of highlights.

Methods inherited from class org.netbeans.spi.editor.highlighting.support.AbstractHighlightsContainer

addHighlightsChangeListener, fireHighlightsChange, removeHighlightsChangeListener

Methods inherited from class java.lang.Object

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

Constructor Detail

OffsetsBag

public OffsetsBag(Document document)

Creates a new instance of OffsetsBag, which trims highlights as they are added. It calls the OffsetsBag.OffsetsBag(Document, boolean) constructor passing false as a parameter.

Parameters:

document - The document that should be highlighted.

OffsetsBag

public OffsetsBag(Document document,
                  boolean mergeHighlights)

Creates a new instance of OffsetsBag.

Parameters:

document - The document that should be highlighted.

mergeHighlights - Determines whether highlights should be merged or trimmed.

Method Detail

discard

public void discard()

Discards this OffsetsBag. This method should be called when a client stops using the bag. After calling this method no other methods should be called. The bag is effectively empty and it is not possible to modify it.

addHighlight

public void addHighlight(int startOffset,
                         int endOffset,
                         AttributeSet attributes)

Adds a highlight to this bag. The highlight is specified by its staring and ending offset and by its attributes. Adding a highlight that overlaps with one or more existing highlights can have a different result depending on the value of the mergingHighlights parameter used for constructing this bag.

Parameters:

startOffset - The beginning of the highlighted area.

endOffset - The end of the highlighted area.

attributes - The attributes to use for highlighting.

addAllHighlights

public void addAllHighlights(HighlightsSequence bag)

Adds all highlights from the bag passed in. This method is equivalent to calling addHighlight for all the highlights in the bag except that the changes are done atomically.

Parameters:

bag - The bag of highlights that will be atomically added to this bag.

setHighlights

public void setHighlights(HighlightsSequence seq)

Resets this bag to use the new set of highlights. This method drops all the existing highlights in this bag and adds all highlights from the sequence passed in as a parameter. The changes are made atomically. The sequence passed in has to be acting on the same Document as this bag.

Parameters:

seq - New highlights to add.

setHighlights

public void setHighlights(OffsetsBag bag)

Resets this bag to use the new set of highlights. This method drops all the existing highlights in this bag and adds all highlights from the bag passed in as a parameter. The changes are made atomically. Both bags have to be acting on the same Document.

Parameters:

bag - New highlights to add.

removeHighlights

public void removeHighlights(int startOffset,
                             int endOffset,
                             boolean clip)

Removes highlights in a specific area of the document. All existing highlights that are positioned within the area specified by the startOffset and endOffset parameters are removed from this bag. The highlights that only partialy overlap with the area are treated according to the value of the clip parameter.

• If clip == true : the overlapping highlights will remain in this sequence but will be clipped so that they do not overlap anymore
• If clip == false : the overlapping highlights will be removed from this sequence

Parameters:

startOffset - The beginning of the area to clear.

endOffset - The end of the area to clear.

clip - Whether to clip the partially overlapping highlights.

getHighlights

public HighlightsSequence getHighlights(int startOffset,
                                        int endOffset)

Gets highlights from an area of a document. The HighlightsSequence is computed using all the highlights present in this bag between the startOffset and endOffset.

Specified by:

getHighlights in interface HighlightsContainer

Specified by:

getHighlights in class AbstractHighlightsContainer

Parameters:

startOffset - The beginning of the area.

endOffset - The end of the area.

Returns:

The HighlightsSequence which iterates through the highlights in the given area of this bag.

clear

public void clear()

Removes all highlights previously added to this bag.