Word Custom Patterns
This topic describes the custom UI Automation patterns provided in Microsoft Word for Windows. These patterns can be queried and used from the provider node which has a text pattern.
For experimentation purposes, we have created special PowerShell scripts in the PowerShell Gallery that exercise each Word custom pattern. These are called out explicitly with each pattern, or you can search for CustomPatternClient_Word to see all of the Word scripts. These scripts can be run in a PowerShell window against a running instance of Word on Windows 11 to see what output the custom patterns produce. The scripts are self documented with comment based help.
The main goal of these patterns is to provide additional information related to Word content and perform actions which can't be achieved through existing UI Automation interfaces. Custom patterns can be applied to any element present in the accessibility hierarchy. There can be single or multiple custom patterns associated with an element which can be identified by their own GUID.
Operands common to all methods
There are 3 fixed input operands for every custom pattern method call.
| Operand | Type | Description |
|---|---|---|
| 0 | ConnectBoundObject | Pattern Object |
| 1 | GUID | The method GUID |
| 2 | Int32 | Total number of input and output arguments |
Return values
Every method described here returns an HRESULT for the CallExtension to indicate success or failure. A successful operation returns S_OK, and a failed operation will yield UIA_E_INVALIDOPERATON.
ITextRangeCustomProvider
Description
Guid: {93514122-FF04-4B2C-A4AD-4AB04587C129}
This is a pattern for text ranges and applied on those Word nodes in the accessibility hierarchy which has a text pattern set. ITextRangeCustomProvider provides an additional set of methods which are applicable to text ranges. Clients can query for GetEnlcosingElement for a text range and use the custom pattern GUID to check if the element supports the custom pattern.
PowerShell Script
CustomPatternClient_Word_TextRangeProvider.ps1
Methods
GetCustomAttributeValue
Guid: {081ACA91-32F2-46F0-9FB9-017038BC45F8}
Returns values of custom attributes for a text range like line number, column number, section number, page number, and bookmark. It is similar to GetAttributeValue API for ITextRange and returns a VARIANT holding either integer or string values for currently supported custom attributes. Both input parameters and return values are packed in IInspectable.
| Operand | Role | Type | Description |
|---|---|---|---|
| 3 | Input | ITextRangeProvider | Input text range |
| 4 | Input | Int32 | Input attribute identifier |
| 5 | Output | Int32 or String | Return value of custom attribute |
Currently Word supports the following set of custom attribute identifiers:
| Attribute Identifier | Input Value | Return Type |
|---|---|---|
| Line Number | 0 | Int32 |
| Page Number | 1 | Int32 |
| Column Number | 2 | Int32 |
| Section Number | 3 | Int32 |
| Bookmark Name | 4 | String |
MoveBySentence
Guid: {F39655AC-133A-435B-A318-C197F0D3D203}
Like Move API of ITextRangeProvider, it moves the text range forward or backward by the specified number of sentence units.
| Operand | Role | Type | Description |
|---|---|---|---|
| 3 | Input/Output | ITextRangeProvider | Input and Output text range |
| 4 | Input | Int32 | Input unit counts to move |
| 5 | Output | Int32 | Return value of actual units moved |
MoveEndpointBySentence
Guid: {368E89A2-1BC2-4402-8C58-33C63ECFFA3B}
Like MoveEndpoint API of ITextRangeProvider, it moves one endpoint of the text range the specified number of sentence units within the document range.
| Operand | Role | Type | Description |
|---|---|---|---|
| 3 | Input/Output | ITextRangeProvider | Input and Output text range |
| 4 | Input | Int32 | Endpoint to move |
| 5 | Input | Int32 | Input unit counts to move |
| 6 | Output | Int32 | Return value of actual units moved |
Endpoint values are same as TextPatternRangeEndpoint enum.
ExpandToEnclosingSentence
Guid: {98FE8B34-F317-459A-9627-21123EA95BEA}
Like ExpandToEnclosingUnit API of ITextRangeProvider, the range is expanded if it is smaller than the sentence unit or shortened if it is longer than the sentence unit.
| Operand | Role | Type | Description |
|---|---|---|---|
| 3 | Input/Output | ITextRangeProvider | Input and Output text range |
GetMathText
Guid: {380198E5-A51F-4618-A78D-57E9568A3862}
For the text ranges which are of Math type and have annotation as “Mathematics”, this API will support different Math text formats such as MathML. Word currently only supports MathML format. This API is similar to GetText of ITextRangeProvider without any length argument and returns full text of math zone.
| Operand | Role | Type | Description |
|---|---|---|---|
| 3 | Input | ITextRangeProvider | Input text range |
| 4 | Input | Int32 | Math Format Type |
| 5 | Output | String | Math text for given format |
| Math Format Type | Input Value (Int32) | Return Type |
|---|---|---|
| MathML | 0 | String |
Requirements
Microsoft 365 Version 2112 (Build 14725.xxxxx)
See also
Custom Properties, Events, and Control Patterns