oracle.javatools.editor
Class TextTabber

java.lang.Object
  oracle.javatools.editor.TextTabber

public final class TextTabber
extends java.lang.Object

A class to highlight a number of sections of text in an editor. The user can then quickly tab forward and backwards through these sections with each section becoming the editor selection in turn.

To use: create an instance, add ranges of text to it via calls to addRange, then call setActive(true) to start the tabbing effect.

The effect is automatically removed when either:
- The caret is repositioned before the start offset of the valid range
- The caret is repositioned after the end offset of the valid range
- or by a call to setActive(false).
- or by the user hitting cancel (the escape key by default)


The sections of text can be added in any order, the TextTabber works out the order of tabbing based on current caret location and start offset.

The offsets for the ranges are automatically adjusted if the text in the editor is changed.

Internally the class uses editor resources. Once created a TextTabber must either be started or manually disposed otherwise the resources will not be freed.

Ranges are currently not allowed to touch. If a change in the document occurs such that two ranges are immediately adjacent then the InvalidRangeAction occurs, this can be set to either stop the tabber, or to remove invalid ranges.

Nested Class Summary

static class	TextTabber.InvalidRangeAction
class	TextTabber.TabTextRange A TextRange that also contains a key to identify it to clients

Field Summary

static java.lang.String	PROPERTY_ACTIVE Property for when the TextTabber becomes active or not
static java.lang.String	PROPERTY_RANGE_CHANGE Property for when the active range is changed.

Constructor Summary

TextTabber(BasicEditorPane editor)
Create a TextTabber for the specified editor

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener)
TextTabber.TabTextRange	addRange(int startOffset, int endOffset) Add a range of text to the TextTabber so that is involved in the tabbing.
TextTabber.TabTextRange	addRange(java.lang.Object key, int startOffset, int endOffset) Add a range of text to the TextTabber so that is involved in the tabbing.
void	dispose() As the TextTabber uses editor resources these resources need to be released when no longer needed. Note: disposal is automatic once the TextTabber has been activated via setActive(true).
TextTabber.InvalidRangeAction	getInvalidRangeAction()
java.util.Collection<TextTabber.TabTextRange>	getTextRanges()
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener)
void	removeRange(TextTabber.TabTextRange textRange) Remove a previously added TabTextRange, This range no longer participates in the tabbing.
void	setActive(boolean isActive) Start or stop the tabbing effect.
void	setInvalidRangeAction(TextTabber.InvalidRangeAction invalidRangeAction) The action to take when the TextTabber discovers a change in the document that makes at least one range invalid (e.g.
void	setValidRange(int startValidOffset, int endValidOffset) Manually set the first and last offset between which the TextTabber will remain active.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_ACTIVE

public static final java.lang.String PROPERTY_ACTIVE

Property for when the TextTabber becomes active or not

See Also:

Constant Field Values

PROPERTY_RANGE_CHANGE

public static final java.lang.String PROPERTY_RANGE_CHANGE

Property for when the active range is changed. The old range value currently isn't reported in these events. If the new range is null then the user has tabbed past the end field to a non-existing field, and the tabber is about to stop. This would be a good opportunity to set a final post-tabber location offset.

See Also:

Constant Field Values

Constructor Detail

TextTabber

public TextTabber(BasicEditorPane editor)

Create a TextTabber for the specified editor

Parameters:

editor -

Method Detail

addRange

public TextTabber.TabTextRange addRange(int startOffset,
                                        int endOffset)

Add a range of text to the TextTabber so that is involved in the tabbing. The added range has no key

Parameters:

startOffset -

endOffset -

Returns:

a TextRange, useful if the range needs to be removed.

addRange

public TextTabber.TabTextRange addRange(java.lang.Object key,
                                        int startOffset,
                                        int endOffset)

Add a range of text to the TextTabber so that is involved in the tabbing.

Parameters:

key - the key is set in the returned TabTextRange for clients to identify the range

startOffset -

endOffset -

Returns:

a TextRange, useful if the range needs to be removed.

removeRange

public void removeRange(TextTabber.TabTextRange textRange)

Remove a previously added TabTextRange, This range no longer participates in the tabbing.

Parameters:

textRange -

setValidRange

public void setValidRange(int startValidOffset,
                          int endValidOffset)

Manually set the first and last offset between which the TextTabber will remain active. If the caret moves outside of these marks the tabbing is automatically stopped.

Note: The valid range is automatically set by the text tabber to match the first and last offsets in the added ranges. This method is only needed to be called if wider valid offset bounds are needed.

Parameters:

startValidOffset -

endValidOffset -

setActive

public void setActive(boolean isActive)

Start or stop the tabbing effect. Once stopped the tabbing cannot be restarted. by this instance.

Parameters:

isActive -

getTextRanges

public java.util.Collection<TextTabber.TabTextRange> getTextRanges()

Returns:

a collection of active ranges sorted by increasing start offsets.

dispose

public void dispose()

As the TextTabber uses editor resources these resources need to be released when no longer needed.
Note: disposal is automatic once the TextTabber has been activated via setActive(true). Manual disposal is only needed if the TextTabber was never started.

setInvalidRangeAction

public void setInvalidRangeAction(TextTabber.InvalidRangeAction invalidRangeAction)

The action to take when the TextTabber discovers a change in the document that makes at least one range invalid (e.g. it overlaps or touches another range). Defaults to InvalidRangeAction.REMOVE_RANGES

Parameters:

invalidRangeAction -

getInvalidRangeAction

public TextTabber.InvalidRangeAction getInvalidRangeAction()

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object