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:

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:

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


[view class]
~ITextChangeEvent
public:
virtual ~ITextChangeEvent()

Supported Platforms

Windows OS/2 AIX
Yes No Yes


[view class]
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:


[view 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


[view class]
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


[view class]
isChangeAllowed
public:
bool isChangeAllowed() const

Returns whether the proposed change is allowed to:

Supported Platforms

Windows OS/2 AIX
Yes No Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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
IEvent

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data