Class TextEditor
- java.lang.Object
-
- com.adobe.xfa.text.TextEditor
-
public class TextEditor extends java.lang.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 Description static boolean
LOGICAL_DEFAULT
-
Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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(TextStream oInsert, boolean bKeepRange)
Insert or replace the selection with rich text.void
replace(java.lang.String sInsert, boolean bKeepRange)
Insert or replace the selection with text.void
replacePara()
Insert or replace the selection with a paragraph mark.int
selectCount()
Count the number of characters currently selected.java.lang.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.
-
-
-
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 classTextPosnBase
).- 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 classTextPosnBase
).
-
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 java.lang.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(java.lang.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 classTextPosnBase
).
-
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()
-
-