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

Nested Classes

Modifier and Type	Class and Description
static class	TextTabber.InvalidRangeAction
class	TextTabber.TabTextRange A TextRange that also contains a key to identify it to clients

Field Summary

Fields

Modifier and Type	Field and Description
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.
static java.lang.String	PROPERTY_RANGE_CHANGE_PENDING Property for when the active range is about to be changed.
static java.lang.String	PROPERTY_SELECT Property for when the user selects a field of the TextTabber.

Constructor Summary

Constructors

Constructor and Description
TextTabber(BasicEditorPane editor) Create a TextTabber for the specified editor

Method Summary

Modifier and Type	Method and Description
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).
boolean	getEnterIsSelect()
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	selectRange(TextTabber.TabTextRange range) Select (move the highlight) to the indicated range.
void	setActive(boolean isActive) Start or stop the tabbing effect.
void	setEnterIsSelect(boolean enterIsSelect) Set the ability for the TextTabber to consume Enter key presses and fire a PROPERTY_SELECT property change event instead.
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_SELECT

public static final java.lang.String PROPERTY_SELECT

Property for when the user selects a field of the TextTabber. e.g. The EnterIsSelect property is true and the user presses 'Enter'

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

PROPERTY_RANGE_CHANGE_PENDING

public static final java.lang.String PROPERTY_RANGE_CHANGE_PENDING

Property for when the active range is about to be 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

setEnterIsSelect

public void setEnterIsSelect(boolean enterIsSelect)

Set the ability for the TextTabber to consume Enter key presses and fire a PROPERTY_SELECT property change event instead. By default it does not do this.

Parameters:

enterIsSelect -

getEnterIsSelect

public boolean getEnterIsSelect()

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()

selectRange

public void selectRange(TextTabber.TabTextRange range)

Select (move the highlight) to the indicated range. If called before the tabber is active, will be ineffective (as starting the tabber will move the selection to the first range).

Parameters:

range - Range to be selected

Throws:

java.lang.IllegalArgumentException - if range is null or not a member of text tabber's ranges

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