com.adobe.xfa.text

Class TextEditor

java.lang.Object

com.adobe.xfa.text.TextEditor

public class TextEditor
extends Object

A text editor provides interactive access to a text stream, with methods that map to user-interface events.

The text editor contains a text range, which is its key into the underlying text stream. Text editor methods manipulate the underlying text through that range, as well as the range itself. When the range is non-empty it corresponds to a selected range of text in the application. When the range is empty, it corresponds to a caret. The text range interacts with XTG Graphic Services to ensure that it displays these states properly. It also interprets method calls based on the range's state. For example, inserting a character in caret mode simply inserts the character at the (empty) range location. Inserting a character in selected range mode deletes the contents of the range before the insertion occurs.

A text editor also may carry a reference to a graphic environment. In an interactive application, this is important, as it allows for scrolling and invalidation.

This class supports a number of text unit movement operations, for example, move by character or word. These operations include the notion of a forward or backward move, which can be interpreted in either a logical or a visual sense. Logical moves apply to the underlying text stream data. Moving forward operation increases the position's stream index, while moving back operation decreases it. For visual moves, forward implies to the right and backward to the left. In right-to-left text, forward is synonomous with decreasing index and backward with increasing index. In right-to-left text, forward corresoponds to increasing index and backward corresponds to decreasing index. The caller choses logical or visual mode in the parameter list of movement operations. For visual moves to be effective, there must be a text display associated with the stream. Note that a text editor defaults to visual moves on Mac and logical on Windows, while a text position always defaults to logical moves.

Many text editor methods are declared virtual. While not necessarily call-backs, they do allow the application to trap operations in a common place, its derived object.

For more information, please see the extenral documentation.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	LOGICAL_DEFAULT

Constructor Summary

Constructors

Constructor and Description
TextEditor() Default constructor.
TextEditor(GFXEnv poGfxEnv) Constructor with graphic environment.
TextEditor(TextEditor oSource) Copy constructor.
TextEditor(TextPosnBase oPosn, GFXEnv poGfxEnv) Constructor with position and graphic environment.
TextEditor(TextRange oRange, GFXEnv poGfxEnv) Constructor with range and graphic environment.
TextEditor(TextStream poStream, GFXEnv poGfxEnv, boolean bSelectAll) Constructor with text stream and graphic environment.

Method Summary

Modifier and Type	Method and Description
CoordPair	absToRel(GFXEnv poGfxEnv, CoordPair oPoint) Call-back: Absolute to relative coordinate conversion.
void	associate(int nIndexStart, int nIndexEnd) Change the editor's range by index number.
void	associate(TextPosnBase oPosn) Associate the editor with a new position.
void	associate(TextRange oRange) Associate the editor with a new text range.
void	associate(TextStream poStream, boolean bSelectAll) Associate the editor with a new text stream.
TextAttr	attributeGet() Obtain the attributes in effect.
void	attributeSet(TextAttr oNewAttr) Change text attributes.
TextEditor	cloneEditor() Call-back: Create a duplicate of this editor.
void	complete()
void	deleteAll(boolean bForward) Delete the entire stream content.
void	deleteChar(boolean bForward) Delete one characer.
void	deleteLine(boolean bForward) Delete the current line(s).
void	deletePara(boolean bForward) Delete the current paragraph(s).
void	deleteSelect() Delete the current selection.
void	deleteWord(boolean bForward)
void	deleteWord(boolean bForward, int eWordMode) Delete the current word(s).
void	getUserPosition(IntegerHolder nIndexStart, IntegerHolder nIndexEnd) Query the current user indexes associated with the stream.
GFXEnv	gfxEnv() Query the graphic environment currently in use.
void	gfxEnv(GFXEnv poNewGfxEnv) Change the graphic environment.
void	grabAll() Select the entire text stream.
void	grabLine() Extend the editor's range to include complete lines.
void	grabPara() Extend the editor's range to include complete paragraphs.
void	grabWord()
void	grabWord(int eWordMode) Extend the editor's range to include complete words.
boolean	moveAll(boolean bAbsolute, boolean bForward, boolean bSelect)
boolean	moveAll(boolean bAbsolute, boolean bForward, boolean bSelect, boolean bLogical) Move to start/end of line/text.
boolean	moveChar(boolean bForward, boolean bSelect)
boolean	moveChar(boolean bForward, boolean bSelect, boolean bLogical) Move ahead/back one character in the underlying text stream.
boolean	moveLine(boolean bForward, boolean bSelect) Move ahead/back one line in the underlying text stream.
boolean	movePara(boolean bForward, boolean bSelect) Move ahead/back one paragraph in the underlying text stream.
boolean	moveWord(boolean bForward, boolean bSelect, boolean bLogical, int eWordMode) Move ahead/back one word in the underlying text stream.
boolean	moveWord(boolean bForward, boolean bSelect, int eWordMode)
void	onTextChanged(boolean bExtentChanged) Call-back: Text content change notification.
TextRange	range() Obtain the editor's current range.
void	range(TextRange oNewRange) Change the editor's range.
CoordPair	relToAbs(GFXEnv poGfxEnv, CoordPair oPoint) Call-back: Relative to absolute coordinate conversion.
void	replace(char cInsert, boolean bKeepRange) Insert or replace the selection with a single character.
void	replace(String sInsert, boolean bKeepRange) Insert or replace the selection with text.
void	replace(TextStream oInsert, boolean bKeepRange) Insert or replace the selection with rich text.
void	replacePara() Insert or replace the selection with a paragraph mark.
int	selectCount() Count the number of characters currently selected.
String	selectText() Obtain the selected (plain) text.
void	selectText(TextStream oSelect) Obtain the selected (rich) text.
void	showCaret() Call-back: Show/hide the caret.
boolean	updateDisplay() Query the status of the UpdateDisplay flag.
void	updateDisplay(boolean bNewUpdateDisplay) Change the UpdateDisplay flag.
void	userAssociate(TextStream poStream, int nIndexStart, int nIndexEnd) Associate the editor by stream and user indexes.

Methods inherited from class java.lang.Object

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

Field Detail

LOGICAL_DEFAULT

public static final boolean LOGICAL_DEFAULT

See Also:

Constant Field Values

Constructor Detail

TextEditor

public TextEditor()

Default constructor.

Create a text editor that has no stream association and no graphic environment.

TextEditor

public TextEditor(TextEditor oSource)

Copy constructor.

Copy all data from the source editor, including range and graphic environment reference.

Parameters:

oSource - - Source text editor to copy.

TextEditor

public TextEditor(GFXEnv poGfxEnv)

Constructor with graphic environment.

The editor will be associated with the graphic environment, but its range will be initially unassociated.

Parameters:

poGfxEnv - - Graphic environment. May be NULL, in which case there is no initial graphic environment.

TextEditor

public TextEditor(TextStream poStream,
                  GFXEnv poGfxEnv,
                  boolean bSelectAll)

Constructor with text stream and graphic environment.

The editor will be associated with the given stream (through its range) and the given graphic environment.

Parameters:

poStream - - Stream to associate range with. May be NULL indicating no initial association.

poGfxEnv - - (optional) Graphic environment. May be NULL (default) indicating no initial graphic environment association.

bSelectAll - - (optional) If TRUE, set up the editor's range to initially select the entire stream. Note that if the stream is empty, the editor starts out in caret mode. If FALSE (default), the range starts out in caret mode, at the end of the stream.

TextEditor

public TextEditor(TextRange oRange,
                  GFXEnv poGfxEnv)

Constructor with range and graphic environment.

The editor's range will be copied from the given range, and its graphic environment will be set from the given parameter.

Parameters:

oRange - - Source text range to copy for this editor's range.

poGfxEnv - - (optional) Graphic environment. May be NULL (default) indicating no initial graphic environment association.

TextEditor

public TextEditor(TextPosnBase oPosn,
                  GFXEnv poGfxEnv)

Constructor with position and graphic environment.

Initialize the editor's range in caret mode at the specified position.

Parameters:

oPosn - - Source position object.

poGfxEnv - - (optional) Graphic environment. May be NULL (default) indicating no initial graphic environment association.

Method Detail

associate

public void associate(TextStream poStream,
                      boolean bSelectAll)

Associate the editor with a new text stream.

The editor will be associated with the given stream (through its range). Does not change the graphic environment.

Parameters:

poStream - - Stream to associate range with. May be NULL indicating no association.

bSelectAll - - (optional) If TRUE, set up the editor's range to initially select the entire stream. Note that if the stream is empty, the editor starts out in caret mode. If FALSE (default), the range starts out in caret mode, at the end of the stream.

associate

public void associate(TextRange oRange)

Associate the editor with a new text range.

The editor's range will be copied from the given range. This may simply be a new range in the current stream or it may refer to a different stream. Does not change the graphic environment.

Parameters:

oRange - - Source text range to copy for this editor's range.

associate

public void associate(TextPosnBase oPosn)

Associate the editor with a new position.

Assign the editor's range from the given text position object, setting it up in caret mode. Does not change the graphic environment.

Parameters:

oPosn - - Source position object. This may be a position in the same stream or it may refer to a new stream altogether.

associate

public void associate(int nIndexStart,
                      int nIndexEnd)

Change the editor's range by index number.

Change the range's start and end index number, maintaining the association with its current stream.

Parameters:

nIndexStart - - New starting index number for the range. If too large, it will be truncated.

nIndexEnd - - New endting index number for the range. If too large, it will be truncated. Note that the caller may give these numbers in the wrong order and the editor will sort it out

userAssociate

public void userAssociate(TextStream poStream,
                          int nIndexStart,
                          int nIndexEnd)

Associate the editor by stream and user indexes.

A user index corresponds to a position where a caret may be placed. While there are distinct positions surrounding an embedded attribute change, there is only a single user index there.

Parameters:

poStream - - Stream to associate with.

nIndexStart - - New starting user index number for the range. If too large, it will be truncated.

nIndexEnd - - New ending user index number for the range. If too large, it will be truncated. Note that the caller may give these numbers in the wrong order and the editor will sort it out

getUserPosition

public void getUserPosition(IntegerHolder nIndexStart,
                            IntegerHolder nIndexEnd)

Query the current user indexes associated with the stream.

A user index corresponds to a position where a caret may be placed. While there are distinct positions surrounding an embedded attribute change, there is only a single user index there.

Parameters:

nIndexStart - - Current starting user index number for the range.

nIndexEnd - - Current ending user index number for the range.

range

public TextRange range()

Obtain the editor's current range.

Returns:

Current text range represented by this editor.

range

public void range(TextRange oNewRange)

Change the editor's range.

This method is identical to the overload of Associate() that takes a text range parameter.

Parameters:

oNewRange - - New range to use.

gfxEnv

public GFXEnv gfxEnv()

Query the graphic environment currently in use.

Returns:

Pointer to graphic environment currently held by this text editor. May be NULL.

gfxEnv

public void gfxEnv(GFXEnv poNewGfxEnv)

Change the graphic environment.

Parameters:

poNewGfxEnv - - Pointer to new graphic environment to use. May be NULL.

updateDisplay

public boolean updateDisplay()

Query the status of the UpdateDisplay flag.

For information on this flag, please see the second UpdateDisplay() overload.

Returns:

Current value of the UpdateDisplay flag.

updateDisplay

public void updateDisplay(boolean bNewUpdateDisplay)

Change the UpdateDisplay flag.

Each editor instance carries an UpdateDisplay flag which indicates whether the editor should attempt to make changes to the graphic display as it manipulates the underlying text stream. These updates include invalidation on changes as well as showing and hiding the caret. To have any effect, there must be an associated graphic environment. To get invalidation, there must be an associated stream, and it must have a text display. The default value of this flag is TRUE, indicating that display updates are intended.

Parameters:

bNewUpdateDisplay - - New value for the UpdateDisplay flag.

moveChar

public boolean moveChar(boolean bForward,
                        boolean bSelect,
                        boolean bLogical)

Move ahead/back one character in the underlying text stream.

This corresponds to the right and left arrow keys in the Windows user-interface.

Parameters:

bForward - - (optional) If TRUE (default) move forward one character. if FALSE, move back that amount.

bSelect - - (optional) If TRUE, start or extend the selection represented by this editor. In other words, the range's anchor is not changed; its loose end moves ahead/back one character. If FALSE (default) move both anchor and loose positions to the new location. This may deselect text. In the Windows user-interface, the use of the shift key would influence this parameter value.

bLogical - - TRUE to perform a logical move; FALSE to perform a visual move.

Returns:

TRUE if the move succeeded; FALSE if not;

moveChar

public boolean moveChar(boolean bForward,
                        boolean bSelect)

moveWord

public boolean moveWord(boolean bForward,
                        boolean bSelect,
                        boolean bLogical,
                        int eWordMode)

Move ahead/back one word in the underlying text stream.

This corresponds to right and left arrow keys with the ctrl key being pressed the in the Windows user-interface.

Parameters:

bForward - - (optional) If TRUE (default) move forward one word. if FALSE, move back that amount.

bSelect - - (optional) If TRUE, start or extend the selection represented by this editor. In other words, the range's anchor is not changed; its loose end moves ahead/back one word. If FALSE (default) move both anchor and loose positions to the new location. This may deselect text. In the Windows user-interface, the use of the shift key would influence this parameter value.

bLogical - - TRUE to perform a logical move; FALSE to perform a visual move.

eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).

Returns:

TRUE if the move succeeded; FALSE if not;

moveWord

public boolean moveWord(boolean bForward,
                        boolean bSelect,
                        int eWordMode)

moveLine

public boolean moveLine(boolean bForward,
                        boolean bSelect)

Move ahead/back one line in the underlying text stream.

This corresponds to the down and up arrow keys in the Windows user-interface.

Parameters:

bForward - - (optional) If TRUE (default) move forward one line. if FALSE, move back that amount.

bSelect - - (optional) If TRUE, start or extend the selection represented by this editor. In other words, the range's anchor is not changed; its loose end moves ahead/back one line. If FALSE (default) move both anchor and loose positions to the new location. This may deselect text. In the Windows user-interface, the use of the shift key would influence this parameter value.

Returns:

TRUE if the move succeeded; FALSE if not;

movePara

public boolean movePara(boolean bForward,
                        boolean bSelect)

Move ahead/back one paragraph in the underlying text stream.

There is no corresponding keyboard action in the Windows user-interface.

Parameters:

bForward - - (optional) If TRUE (default) move forward one paragraph. if FALSE, move back that amount.

bSelect - - (optional) If TRUE, start or extend the selection represented by this editor. In other words, the range's anchor is not changed; its loose end moves ahead/back one paragraph. If FALSE (default) move both anchor and loose positions to the new location. This may deselect text. In the Windows user-interface, the use of the shift key would influence this parameter value.

Returns:

TRUE if the move succeeded; FALSE if not;

moveAll

public boolean moveAll(boolean bAbsolute,
                       boolean bForward,
                       boolean bSelect,
                       boolean bLogical)

Move to start/end of line/text.

This corresponds to the home and end keys (with optional ctrl key) in the Windows user-interface.

Parameters:

bAbsolute - - (optional) If TRUE (default) move to the start or end of the text. If FALSE, move to the start or end of the current line.

bForward - - (optional) If TRUE (default) move to the end of the line/text. if FALSE, move to the start of the line/text.

bSelect - - (optional) If TRUE, start or extend the selection represented by this editor. In other words, the range's anchor is not changed; its loose end moves. If FALSE (default) move both anchor and loose positions to the new location. This may deselect text. In the Windows user-interface, the use of the shift key would influence this parameter value.

bLogical - - TRUE to perform a logical move; FALSE to perform a visual move.

Returns:

TRUE if the move succeeded; FALSE if not;

moveAll

public boolean moveAll(boolean bAbsolute,
                       boolean bForward,
                       boolean bSelect)

grabWord

public void grabWord(int eWordMode)

Extend the editor's range to include complete words.

The start of the editor's range moves back to the start of the word containing it. The end of the range moves forward to the end of the word that contains it. If either position is not within a word or adjacent to one, it does not move.

Parameters:

eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).

grabWord

public void grabWord()

grabLine

public void grabLine()

Extend the editor's range to include complete lines.

Note: the associated stream must have a text display for line operations to succeed. The start of the editor's range moves back to the start of the line containing it. The end of the range moves forward to the end of the line that contains it.

grabPara

public void grabPara()

Extend the editor's range to include complete paragraphs.

Note: a paragraph starts after a paragraph mark and runs until just after the next paragraph mark. If our range's end position is already just beyond a paragraph mark, we normally won't want to move it. The exception is when its start is also just after the same mark (empty range once tightened). In this case, we maintain the start and move the end after the next mark.

grabAll

public void grabAll()

Select the entire text stream.

The editor's range is adjusted to include all content of its underlying text stream.

selectCount

public int selectCount()

Count the number of characters currently selected.

Returns:

Number of characters included in the editor's range. Zero if in caret mode.

selectText

public String selectText()

Obtain the selected (plain) text.

Returns:

Text string to get a copy of the currently selected text.

selectText

public void selectText(TextStream oSelect)

Obtain the selected (rich) text.

Copy the content of the editor's range to another stream, replacing its previous content. The destination stream retains its graphic source, which may be different from that of the associated stream. All graphics objects copied are reconciled in the destination stream's graphic source. Because this is a copy, the destination stream will get clones of any embedded objects or fields.

Parameters:

oSelect - - Destination text stream. Not modified if the editor's range has no stream association.

attributeGet

public TextAttr attributeGet()

Obtain the attributes in effect.

Returns a text attribute structure describing the attributes over the range or at the current caret position. Any attribute that remains constant over the range will have an enabled value in the result. Any attribute that changes over the range will be disabled in the result.

Returns:

Text attribute object describing the attributes in effect over the range.

attributeSet

public void attributeSet(TextAttr oNewAttr)

Change text attributes.

Given a text attribute object, this method applies enabled attributes over the editor's range if in selection mode, or at the current position if in caret mode. Note: changing attributes in caret mode effectively changes them for a zero-length range surrounding the current caret location. If the next operation is a text insertion at this location, that text will inherit the new attributes. Otherwise, the stream will eventually see the attribute change as redundant and discard it. Disabled attributes in the given object are not changed.

Parameters:

oNewAttr - - Attribute object with enabled attributes to apply.

replace

public void replace(char cInsert,
                    boolean bKeepRange)

Insert or replace the selection with a single character.

This method is analogous to typing a single character. If there is a selection, it is first deleted. Then, the given character is inserted. Upon return, the editor is in caret mode, positioned after the newly inserted character.

Parameters:

cInsert - - Character to insert.

replace

public void replace(String sInsert,
                    boolean bKeepRange)

Insert or replace the selection with text.

This method is analogous to pasting plain text from the clipboard. If there is a selection, it is first deleted. Then, the given text is inserted. Upon return, the editor is in caret mode, positioned after the newly inserted text.

Parameters:

sInsert - - Text to insert.

replace

public void replace(TextStream oInsert,
                    boolean bKeepRange)

Insert or replace the selection with rich text.

This method is analogous to pasting rich text from the clipboard. If there is a selection, it is first deleted. Then, the given text is inserted. Upon return, the editor is in caret mode, positioned after the newly inserted text.

Parameters:

oInsert - - Text to insert.

replacePara

public void replacePara()

Insert or replace the selection with a paragraph mark.

This method is analogous to pressing the enter key in an application that supports paragraphs. If there is a selection, it is first deleted. Then, the paragraph mark is inserted. Upon return, the editor is in caret mode, positioned after the newly inserted paragraph mark.

deleteChar

public void deleteChar(boolean bForward)

Delete one characer.

Delete one character at the "loose" end of the range.

Parameters:

bForward - - TRUE to delete the character immediately after the loose end of the range; FALSE to delete the character immediately before it.

deleteWord

public void deleteWord(boolean bForward,
                       int eWordMode)

Delete the current word(s).

Extend the caret position or current selection to select complete words (see GrabWord() above and then delete the selection. On return, the editor will be in caret mode at the point of deletion.

Parameters:

bForward - - Currently ignored.

eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).

deleteWord

public void deleteWord(boolean bForward)

deleteLine

public void deleteLine(boolean bForward)

Delete the current line(s).

Extend the caret position or current selection to select complete lines (see GrabLine() above and then delete the selection. On return, the editor will be in caret mode at the point of deletion.

Parameters:

bForward - - Currently ignored.

deletePara

public void deletePara(boolean bForward)

Delete the current paragraph(s).

Extend the caret position or current selection to select complete paragraphs (see GrabPara() above and then delete the selection. On return, the editor will be in caret mode at the point of deletion.

Parameters:

bForward - - Currently ignored.

deleteAll

public void deleteAll(boolean bForward)

Delete the entire stream content.

Implicitly select the entire stream and then delete it. On return, the editor will be in caret mode in an empty stream.

Parameters:

bForward - - Currently ignored.

deleteSelect

public void deleteSelect()

Delete the current selection.

Delete the selected text. If the editor is currently in caret mode, the call is ignored.

cloneEditor

public TextEditor cloneEditor()

Call-back: Create a duplicate of this editor.

Create a duplicate of this object. The derived class should create a new object of its own type and copy all additional data that it carries, including base class copy. The default implementation creates a TextEditor and copies stream association and graphic environment.

Returns:

Pointer to cloned copy.

onTextChanged

public void onTextChanged(boolean bExtentChanged)

Call-back: Text content change notification.

The editor calls this method after any operation changes the underlying text stream. The default implementation notifies the text display of the change, and should be called by any overriding implementation.

Parameters:

bExtentChanged - - TRUE if the extent of the text has changed; FALSE if not.

relToAbs

public CoordPair relToAbs(GFXEnv poGfxEnv,
                          CoordPair oPoint)

Call-back: Relative to absolute coordinate conversion.

The text editor works entirely in local text display stream coordinates (e.g., (0,0) is the top left corner if the text object). This method allows the derived class to convert local text coordinates to more global form coordinates.

Parameters:

poGfxEnv - - Graphic environment in which the conversion must occur.

oPoint - - The editor calls this method with the local point to convert; the derived class replaces its value with the converted point. The default implementation does nothing to the point.

absToRel

public CoordPair absToRel(GFXEnv poGfxEnv,
                          CoordPair oPoint)

Call-back: Absolute to relative coordinate conversion.

The text editor works entirely in local text display stream coordinates (e.g., (0,0) is the top left corner if the text object). This method allows the derived class to convert global form coordinates to local text coordinates.

Parameters:

poGfxEnv - - Graphic environment in which the conversion must occur.

oPoint - - The editor calls this method with the global point to convert; the derived class replaces its value with the converted point. The default implementation does nothing to the point.

showCaret

public void showCaret()

Call-back: Show/hide the caret.

The editor calls this method after any operation that may change the appearance of the caret. For example, going from caret mode to a selection requires that the caret be hidden. An application with special caret handling needs might want to override this method. However, the default implementation is reasonably rich: it uses the Gfx package to show/hide the caret depending on selection or caret mode, and will display the caret properly rotated for the four basic angles. If the application overrides ShowCaret(), it may still want to call the base class implementation.

complete

public void complete()