Edit

TextEdit Control Pattern

  • Article

Introduces guidelines and conventions for implementing ITextEditProvider, including information about properties and methods. The TextEdit control pattern is used for programmatic access to a control that modifies text, for example a control that performs auto-correction or enables input composition.

Note

Implementation notes in this topic refer to APIs that come from Text Services Framework (TSF). For more info about TSF and the API reference, see Text Services Framework.

Required Members for ITextEditProvider

These properties and methods are required for implementing the ITextEditProvider interface.

Required members Member type Notes
GetActiveComposition Method Returns the range of the current conversion (none if there is no conversion). Return the active composition (in TSF, this is the range marked by GUID_PROP_COMPOSING). For example with the Microsoft Japanese Input Method Editor (IME), this would be the full underlined text.
GetConversionTarget Method Returns the current conversion target range (none if no conversion). In TSF, this is the range of characters marked as TF_ATTR_TARGET_NOTCONVERTED or TF_ATTR_TARGET_CONVERTED from the TF_DISPLAYATTRIBUTE structure.

The TextEditTextChanged and ConversionTargetChanged events are required to be raised by Microsoft UI Automation elements supporting the TextEdit pattern.

TextEditTextChanged

TextEditChangeType Event Payload Notes
AutoCorrect New corrected string Raised when an auto-correction is made by the control. Or whenever a replacement is made through TSF and the range has a GUID_PROP_TKB_ALTERNATES value of TKB_ALTERNATES_AUTOCORRECTION_APPLIED.
Composition The updated string The payload must only include the characters that changed (do not send the entire composition string). Raised whenever a composition replacement is made. In TSF, a composition replacement is defined as a replacement that has the GUID_PROP_COMPOSING flag set. Edit controls implementing TSF can monitor for these changes via the OnEndEdit notification.
CompositionFinalized The finalized composition string (see Notes) In TSF, the conversion string being finalized is defined by the GUID_PROP_COMPOSING flag being removed from a composition. Edit controls implementing TSF should determine the finalized string from EndComposition and raise the event when OnEndEdit is called.
The finalized composition string may be empty if composition was cancelled or deleted.

ConversionTargetChanged

  • ConversionTargetChanged occurs when conversion target changes from one target to another.
  • Use the UiaRaiseAutomationEvent function to raise the ConversionTargetChanged event (pass the UIA_TextEdit_ConversionTargetChangedEventId event identifier).
  • ConversionTargetChanged should not be raised when the content of the target changes. If the target change occurs simultaneous with a composition change, the target change event must be raised after any composition events have already been raised.
  • In TSF, the conversion target is defined by the value TF_ATTR_TARGET_CONVERTED being set from the TF_DISPLAYATTRIBUTE structure. Changes can be monitored using OnEndEdit.

Conceptual

Control Types and Their Supported Control Patterns

UI Automation Control Patterns Overview

UI Automation Tree Overview