Package 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
    Description
    static final 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

    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(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.
    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 Details

  • Constructor Details

    • 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 Details

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