### ITextChangeEvent

  Objects of the ITextChangeEvent class represent a pending change to the text data in an editable text control.

  Changes to the text might include the following:

  - Insertion
  - Replacement
  - Deletion

  The change can be via keyboard entry, cut and paste, or using the text control's functions. Depending on how this event is processed, the change will be:

  - Successful (either exactly as proposed, or you can modify the proposed text data)
  - Unsuccessful
  If successful, a control event is sent to the IEditHandler signaling that the change has occurred.

  An ITextChangeHandler constructs and processes ITextChangeEvents. They can be constructed elsewhere as well. You must write your own handler class derived from ITextChangeHandler. You can then use this handler to gain access to ITextChangeEvents, allowing you to edit and/or verify proposed changes to an editable text control.

  ITextChangeEvents are first dispatched to the handlers attached to the control itself, then to the handlers attached to the owner window of the control.

### ITextChangeEvent - Member Functions and Data by Group

### Constructors & Destructor

~ITextChangeEvent

      public:
      virtual ~ITextChangeEvent()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

ITextChangeEvent

  Overload 1

      public:
      ITextChangeEvent(IEvent& event)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

  Overload 2

      public:
      ITextChangeEvent(const ITextChangeEvent& event)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

### Accessors

These functions provide the means of getting and setting accessible attributes of instances of this class:

allowChange

      public:
      ITextChangeEvent& allowChange(bool allow = true)

  Sets the disposition of the proposed change.

  allow
    The proposed change can:
    - Succeed, subject to any changes made in the data of this event (true)
    - Not succeed (false)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

endPosition

      public:
      unsigned long endPosition() const

  Returns the position of the last character in the control's current data to be affected by the proposed change. If the proposed change is an insert, both startPosition and endPosition will have the same value; this value is the point of insertion.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

isChangeAllowed

      public:
      bool isChangeAllowed() const

  Returns whether the proposed change is allowed to:

  - Succeed, subject to any changes made in the data of this event (true)
  - Not succeed (false)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

proposedText

      public:
      IString proposedText() const

  Returns a IString object containing the proposed text to be inserted or overwrittten into the control's data. This is a copy of the data in this event; if you want to modify the proposed text, you must call setProposedText with a IString object containing your modified text. The IString object can be the one returned by proposedText, or another one.

  If proposedText is a null IString, the proposed change is a deletion from startPosition to endPosition.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

resultingText

      public:
      IString resultingText() const

  Returns a IString object containing the result of combining the control's text with the proposed text; this would be the control's data if the change were allowed to occur. Typically, this text is examined to see if the proposed change would result in valid overall contents for the control if the change were allowed.

  After examining it, if you want to change text to make it valid, work with the proposed text only, not the resulting text. Passing the resulting text on a call to setProposedText would not only add the proposed text but would add a second copy of the control's text. This is usually not what you want to do.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

setEndPosition

      public:
      ITextChangeEvent& setEndPosition(unsigned long endPos)

  Sets the position of the last character in the control's current data affected by the proposed change. If the proposed change is an insert, set both startPosition and endPosition to the same value; this value is the point of insertion.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

setProposedText

      public:
      ITextChangeEvent& setProposedText(IString text)

  Sets a new value for the pending text to be inserted or overwritten into the control's data. The text parameter can be the object returned by proposedText with your modifications, or it can be a completely different IString object. The IString object can be longer or shorter than the original text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

setStartPosition

      public:
      ITextChangeEvent& setStartPosition(unsigned long startPos)

  Sets the position of the first character in the control's current data affected by the pending change. If the change is an insert, you should set both startPosition and endPosition to the same value; this value is the point of insertion.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

startPosition

      public:
      unsigned long startPosition() const

  Returns the position of the first character in the control's current data which will be affected by the pending change. If the change is an insert, both startPosition and endPosition will have the same value; this value is the point of insertion.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | No | Yes

### ITextChangeEvent - Inherited Member Functions and Data

#### Inherited Public Functions

  IControlEvent

  -     virtual ~IControlEvent()

  -     virtual unsigned long controlId() const

  -     IControlEvent(const IEvent& event)

  -     IControlEvent(const IControlEvent& event)

  IEvent

  -     virtual ~IEvent()

  -     IWindowHandle controlHandle() const

  -     virtual IWindow* controlWindow() const

  -     IEvent& decrementOwnerLevels()

  -     virtual IWindow* dispatchingWindow() const

  -     unsigned long eventId() const

  -     IWindowHandle handle() const

  -     IEvent(const IEvent& event)

  -     IEvent( IWindow* window,
                unsigned long eventId,
                const IEventParameter1& parameter1,
                const IEventParameter2& parameter2 )

  -     IEvent( const IWindowHandle& handle,
                unsigned long eventId,
                const IEventParameter1& parameter1,
                const IEventParameter2& parameter2 )

  -     IEvent& operator =(const IEvent& event)

  -     IEventParameter1 parameter1() const

  -     IEventParameter2 parameter2() const

  -     bool passToOwner() const

  -     IEventResult result() const

  -     IEvent& setControlHandle(const IWindowHandle& handle)

  -     IEvent& setDispatchingHandle(const IWindowHandle& handle)

  -     IEvent& setDispatchingWindow(IWindow* window)

  -     IEvent& setHandle(const IWindowHandle& handle)

  -     IEvent& setNumberOfLevels(int levels = - 1)

  -     IEvent& setPassToOwner(bool passOn = true)

  -     IEvent& setResult(bool eventResult)

  -     IEvent& setResult(const IEventResult& eventResult)

  -     virtual IWindow* window() const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None