Share via


IRawElementProviderSimple::GetPropertyValue Method

Retrieves the value of a property supported by the UI Automation provider.

Syntax

HRESULT GetPropertyValue(      
    PROPERTYID propertyId,
    VARIANT *pRetVal
);

Parameters

  • propertyId
    [in] The property identifier. For a list of property IDs, see Property Identifiers.
  • pRetVal
    [out, retval] The address of a variable that receives the property value, or NULL if the property is not supported by this provider. This parameter is passed uninitialized. See Remarks.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

If a provider is explicitly hiding the property value (that is, the provider does not supply the property, and the request is not to be passed through to other providers), it should return a pointer obtained by using the UiaGetReservedNotSupportedValue function. For example:

pRetVal->vt = VT_UNKNOWN;
UiaGetReservedNotSupportedValue(&pRetVal->punkVal);

Microsoft UI Automation properties of the double type support Not a Number (NaN) values. When returning a NaN value, the provider should return a quiet (non-signalling) NaN to avoid raising an exception if floating point exceptions are turned on. The following example shows how to create a quiet NaN:

ULONGLONG ulNaN = 0xFFFFFFFFFFFFFFFF;
    *pRetVal = *reinterpret_cast<double*>(&ulNaN);

Alternatively, you can use the following function from the standard C++ libraries:

numeric_limits<double>::quiet_NaN( )

Example

The following example returns various property values. The UiaIds structure contains property identifiers; to see how it is initialized, see UiaLookupId.


HRESULT STDMETHODCALLTYPE Provider::GetPropertyValue(PROPERTYID propertyId, VARIANT* pRetVal)
{
    if (propertyId == UiaIds.ControlTypeProperty)
    {
        pRetVal->vt = VT_I4;
        pRetVal->lVal = UiaIds.ButtonControlType;
    }

    // The Name property normally comes from the Caption property of the control window, if it has one.
    // The Name is overridden here for the sake of illustration. 
    else if (propertyId == UiaIds.NameProperty)
    {
        pRetVal->vt = VT_BSTR;
        pRetVal->bstrVal = SysAllocString(L"ColorButton");
    }
    else
    {
        pRetVal->vt = VT_EMPTY;
       // UI Automation will attempt to get the property from the host window provider.
    }
    return S_OK;
}
            

See Also

IRawElementProviderSimple