ITextChangeHandler

Objects of the ITextChangeHandler class process text change events for the following controls:

Text-change events describe a proposed change to the data in an editable text control. Such events result from a user attempting to change an input text value, by one of the following actions:

In short, you can verify any change to the text data of these controls in this handler.

This handler is called after IKeyboardHandlers, but before IEditHandlers and before any of the changes in the text values show up on the screen.

You can create a handler derived from ITextChangeHandler and attach it to either the control whose input users can change or to the control's owner window. You do this by calling IHandler::handleEventsFor to pass the appropriate control window or owner window to the text-change handler.

When the text-change handler receives a text-change event, it creates an ITextChangeEvent object and routes that object to the textChange virtual function. You must override this virtual function to supply your own specialized processing of a text-change event. In your processing, you decide whether the proposed change is:

The ITextChangeEvent, which is routed to the virtual function, contains both the proposed data and the allowChange flag. This is the event you modify in your processing.

When processing, you can do the following:

Handlers which are called after yours can set the allowChange flag to false. After all the handlers have been called, the final state of allowChange determines whether a control event is created. The default behavior is successful (true). The control event is sent to IEditHandler signaling the change to the control.

The return value from the virtual function (which is not the same thing as allowChange) specifies whether the control event is passed on for additional processing, as follows:

true
The text-change event requires no additional processing. Do not pass it to another handler.
false
Pass the text-change event to the next handler for additional processing, as follows:
  • If there is another handler for the control or window, pass the text-change event to the next handler.
  • If this is the last handler for the control, call IWindow::dispatch to dispatch the text-change event to the control's owner window.
  • If this is the last handler for the owner window, call IWindow::defaultProcedure to process the text-change event.

Note: Additional processing by another handler can alter the proposed data again, and as possibly modify the allowChange flag.


ITextChangeHandler - Member Functions and Data by Group

Constructors & Destructor


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

Supported Platforms

Windows OS/2 AIX
Yes No Yes


[view class]
ITextChangeHandler
protected:
ITextChangeHandler()

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Event Dispatching


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

IWindow calls this function when a window event occurs. If this function returns true, the event is not processed by additional handlers. In such cases, a result must be placed in the specified IEvent object.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Event Processing


[view class]
textChange
protected:
virtual bool textChange(ITextChangeEvent& event) = 0

Implemented by derived classes to process a text-change event. If you do not override this function, you can not create a derived class.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


ITextChangeHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data