AccNotifyTouchInteraction function (oleacc.h)

Article
10/13/2021

Allows an assistive technology (AT) application to notify the system that it is interacting with UI through a Windows Automation API (such as Microsoft UI Automation) as a result of a touch gesture from the user. This allows the assistive technology to notify the target application and the system that the user is interacting with touch.

Syntax

HRESULT AccNotifyTouchInteraction(
  [in] HWND  hwndApp,
  [in] HWND  hwndTarget,
  [in] POINT ptTarget
);

Parameters

[in] hwndApp

A window that belongs to the AT process that is calling AccNotifyTouchInteraction.

[in] hwndTarget

The nearest window of the automation element that the AT is targeting.

[in] ptTarget

The center point of the automation element (or a point in the bounding rectangle of the element).

Return value

If successful, returns S_OK.

If not successful, returns a standard COM error code.

Remarks

This function requires the calling process to have UIAccess or higher privileges. If the caller does not have the required privileges, the call to AccNotifyTouchInteraction fails and returns E_ACCESSDENIED. For more information, see Security Considerations for Assistive Technologies and /MANIFESTUAC (Embeds UAC information in manifest).

When an AT is consuming touch data (such as when using the RegisterPointerInputTarget function), the shell and applications that the AT interacts with through the Windows Automation API are not aware that the user is interacting through touch. For the system to expose touch-related functionality to the user, the AT must use AccNotifyTouchInteraction to notify the system that it is performing the interaction in response to user touch input.

Examples

This code example shows how to call the AccNotifyTouchInteraction function.

// pTargetElement is the element being interacted with by the user, hwndApp 
// represents an HWND owned by the AT.
HRESULT PerformTouchBasedInteraction(IUIAutomationElement *pTargetElement, 
        HWND hwndApp)
{
    HRESULT hr = S_OK;

    // Set the focus to the element and then notify the system that the 
    // interaction is occurring due to a touch gesture. This would also apply 
    // to pattern-based interactions (such as calls to 
    // IUIAutomationInvokePattern::Invoke)
    hr = pTargetElement->SetFocus();
    if (SUCCEEDED(hr))
    {
        HWND hwndTarget;
        POINT ptTarget;
        BOOL fGotClickablePoint;

        // If the current element does not have a native window handle, an 
        // alternate method (such as walking up the parent chain) is required 
        // to get the nearest valid HWND.
        hr = pTargetElement->get_CurrentNativeWindowHandle((UIA_HWND *)(&hwndTarget));
        if (SUCCEEDED(hr))
        {
            // If the provider doesn't return a clickable point, an alternate 
            // method (such as using the bounding rectangle) will be required 
            // to get the center point of the current element.
            hr = pTargetElement->GetClickablePoint(&ptTarget, &fGotClickablePoint);
        }

        if (SUCCEEDED(hr) && fGotClickablePoint)
        {
            hr = AccNotifyTouchInteraction(hwndApp, hwndTarget, ptTarget);
        }
    }

    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	oleacc.h
Library	Oleacc.lib
DLL	Oleacc.dll