Developer

API Reference

ITextModel_ReplaceSel()

Brew Release
Brew MP 1.0.2
See Also
-Model Events
-TextInfo
-ITextModel Interface
-ITextModel_SetSel()
Description
This function replaces the current text selection in the text model with a new block of text. The selection is a range of text described in the TextInfo data structure stored by the text model. Depending on how the text in the model is selected and replaced, ITextModel_ReplaceSel() can be used to replace, insert, append, or delete text at any position within the stored text.
To replace text

  • Call ITextModel_SetSel() specifying the positions of the start and end characters in
  • the range of text to be replaced. Then call ITextModel_ReplaceSel() specifying the
  • new block of text that is to replace the selected text, growing or shrinking the
  • text as necessary. To illustrate, consider the following text, with a selection range
  • starting at position 0 and ending at position 8.

  •                                               1   1   1   1   1   1   1   1   1   1
          0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9
           ---------------------------------------------------------------------------
          | A | s | t | r | o | b | o | y |   | i | s |   | a |   | r | o | b | o | t |
           ---------------------------------------------------------------------------
          ^                               ^
        start                            end
    

    Replacing the selection with "Robby" would result in the following change to the text model.
                                                  1   1   1   1   1   1   1
          0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6
           ---------------------------------------------------------------
          | R | o | b | b | y |   | i | s |   | a |   | r | o | b | o | t |
           ---------------------------------------------------------------
                              ^
                            start
                             end
    

    Here, the text has been shrunk from 19 to 16 total characters, and the selection range moves to the end of the newly inserted text. Had a block of text longer than the selection been passed in ITextModel_ReplaceSel(), the stored text would have grown to accommodate the difference between the size of the old selection and the new text.
    To insert text

    • Call ITextModel_SetSel() specifying the position in the text where the new block of
    • text is to be inserted. Then call ITextModel_ReplaceSel() passing in the new text
    • to be inserted into the text model. To illustrate, consider the following text, with
    • the start and end of the selection pointing to the same position (14).

    •                                               1   1   1   1   1   1   1   1   1   1
            0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9
             ---------------------------------------------------------------------------
            | A | s | t | r | o | b | o | y |   | i | s |   | a |   | r | o | b | o | t |
             ---------------------------------------------------------------------------
                                                                    ^
                                                                  start
                                                                   end
      

      Inserting the text "mighty " would result in the following change to the text model.
                                                    1   1   1   1   1   1   1   1   1   1   2   2   2   2   2   2
            0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5
             ---------------------------------------------------------------------------------------------------
            | A | s | t | r | o | b | o | y |   | i | s |   | a |   | m | i | g | h | y |   | r | o | b | o | t |
             ---------------------------------------------------------------------------------------------------
                                                                                            ^
                                                                                          start
                                                                                           end
      

      Here, the text has been grown from 19 to 25 characters to accommodate the inserted text. The selection position moves from its original location (14) to the end of the newly inserted text (at position 20).
      To append text

      • Call ITextModel_SetSel() specifying the selection to be positioned at the end of the text
      • stored in the text model. Then call ITextModel_ReplaceSel() passing in the new text
      • to be appended to the stored text. To illustrate, consider the following text, with the
      • start and end of the selection pointing to the same position, both at the end of the
      • stored text (19).

      •                                               1   1   1   1   1   1   1   1   1   1
              0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9
               ---------------------------------------------------------------------------
              | A | s | t | r | o | b | o | y |   | i | s |   | a |   | r | o | b | o | t |
               ---------------------------------------------------------------------------
                                                                                          ^
                                                                                        start
                                                                                         end
        

        Appending a single period (the text ".") would result in the following change to the text model.
                                                      1   1   1   1   1   1   1   1   1   1   2
              0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9   0
               -------------------------------------------------------------------------------
              | A | s | t | r | o | b | o | y |   | i | s |   | a |   | r | o | b | o | t | . |
               -------------------------------------------------------------------------------
                                                                                              ^
                                                                                            start
                                                                                             end
        

        The text has been grown one character, from 19 to 20 characters with the selection position moving from its original location (19) to the end of the appended text (at position 20).
        To delete text

        • Call ITextModel_SetSel() specifying the positions of the start and end characters in
        • the range of text to be deleted. Then call ITextModel_ReplaceSel() specifying a NULL
        • text block of zero length. The text stored in the text model will shrink by the
        • original size of the selection range. To illustrate, consider the following text,
        • with a selection range starting at position 5 and ending at position 8.

        •                                               1   1   1   1   1   1   1   1   1   1
                0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6   7   8   9
                 ---------------------------------------------------------------------------
                | A | s | t | r | o | b | o | y |   | i | s |   | a |   | r | o | b | o | t |
                 ---------------------------------------------------------------------------
                                    ^           ^
                                  start        end
          

          Deleting the selection would result in the following change to the text model.
                                                        1   1   1   1   1   1   1
                0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5   6
                 ---------------------------------------------------------------
                | A | s | t | r | o |   | i | s |   | a |   | r | o | b | o | t |
                 ---------------------------------------------------------------
                                   ^
                                 start
                                  end
          

          The text has been shrunk from 19 to 16 characters, and the selection position moves to the start of the previous selection.
Parameters
  • po
    []:
    Pointer to the ITextModel interface object.
  • pwText
    []:
    Pointer to the text that is to replace the current selection in the text model. Pass NULL with cchText set to 0 (zero) to delete the text stored in the current selection.
  • cchText
    []:
    The length of the text, in characters, passed in 'pwText'. Pass (-1) to automatically compute the length of pwText.
Interface
Prototype
   int ITextModel_ReplaceSel(ITextModel *po, const AECHAR *pwText, int cchText); 
Return
   AEE_SUCCESS   - The text model was able to successfully replace the current text selection with
               the block of text pointer to by pwText.
   ENOMEMORY - The text model was unable to allocate enough memory to accommodate the change to
               the text.
Side Effect
Replacing the text selection in a text model by calling ITextModel_ReplaceSel() will cause BREW to send an EVT_MDL_TEXT_CHANGE ModelEvent to any object that has registered as a listener with the model.
The fields of the ModelEvent will contain the following information.
       dwParm:  The position of the character at the start of the text selection range, prior to
                the call to ITextModel_ReplaceSel().
Comment
None
  • Follow