Announce
Pushes short application-status text to attached screen readers through a UI Automation notification event.
C
void SftTree_Announce(HWND hwndCtl, LPCTSTR lpszText, DWORD flags);
void WINAPI SftTree_Announce_A(HWND hwndCtl, LPCSTR lpszText, DWORD flags);
void WINAPI SftTree_Announce_W(HWND hwndCtl, LPCWSTR lpszText, DWORD flags);
void SftTreeSplit_Announce(HWND hwndCtl, LPCTSTR lpszText, DWORD flags);
void WINAPI SftTreeSplit_Announce_A(HWND hwndCtl, LPCSTR lpszText, DWORD flags);
void WINAPI SftTreeSplit_Announce_W(HWND hwndCtl, LPCWSTR lpszText, DWORD flags);
C++
void CSftTree::Announce(LPCTSTR lpszText, DWORD flags = SFTTREE_ANNOUNCE_INFO);
void CSftTreeSplit::Announce(LPCTSTR lpszText, DWORD flags = SFTTREE_ANNOUNCE_INFO);
Parameters
hwndCtl
The window handle of the tree control.
lpszText
The text to announce. A short, complete phrase describing an application status change - for example "3 rows added", "Filter cleared", "Saved", "Cannot delete - item is referenced". The text should be something the user would want spoken, not a verbose log message. An empty or NULL string is silently ignored.
flags
Defines the kind of announcement and its delivery priority. flags combines one kind value and, optionally, the SFTTREE_ANNOUNCE_ASSERTIVE priority override.
| SFTTREE_ANNOUNCE_INFO | Informational announcement, polite delivery. The assistive technology may dedup or drop the announcement if the user is currently interacting with other UI. This is the default. |
| SFTTREE_ANNOUNCE_SUCCESS | An action has completed successfully. Polite delivery. |
| SFTTREE_ANNOUNCE_WARNING | A notable but non-fatal situation the user should know about. Polite delivery. |
| SFTTREE_ANNOUNCE_ERROR | An action has been aborted or has failed. Polite delivery. |
| SFTTREE_ANNOUNCE_POLITE | Alias for SFTTREE_ANNOUNCE_INFO describing the default (polite / deduped) delivery mode. |
| SFTTREE_ANNOUNCE_ASSERTIVE | Bit flag that can be combined with any of the kind values above (for example SFTTREE_ANNOUNCE_ERROR | SFTTREE_ANNOUNCE_ASSERTIVE) to override the assistive technology's normal drop / dedup policy. The announcement will preempt any pending utterance. Use sparingly and only for information the user must hear. |
Comments
The Announce function pushes short application-status text to attached screen readers (Narrator, NVDA, JAWS, etc.) through a UI Automation notification event. The tree control itself does not render the text visually - Announce is a speech-only side channel intended for momentary status updates that would otherwise be invisible to users relying on assistive technologies.
Typical uses:
- confirming a destructive action ("3 items deleted", "Tree reset"),
- reporting an operation result ("Saved", "Export complete", "No items matched"),
- reporting filter or sort changes ("Filter cleared", "Sorted by Name, ascending"),
- reporting progress milestones for long-running operations.
Announce has zero cost when no assistive technology is listening - the tree control queries UiaClientsAreListening before building the event and skips the call entirely otherwise. It is also a silent no-op on Windows versions earlier than Windows 10 version 1709 (build 16299), where UIA notification events are not supported. Empty or NULL text is likewise a no-op.
Announce is independent of the tree control's UI Automation provider. Announcements are raised on the tree control's existing provider and do not require the application to register its own UIA provider.
See Also C/C++ API | Categories | Notifications
On
Off