This documentation is archived and is not being maintained.

CacheRequest.AutomationElementMode Property

Gets or sets a value that specifies whether returned elements should contain full references to the underlying user interface (UI), or only cached information.

Namespace:  System.Windows.Automation
Assembly:  UIAutomationClient (in UIAutomationClient.dll)

'Declaration
Public Property AutomationElementMode As AutomationElementMode
'Usage
Dim instance As CacheRequest 
Dim value As AutomationElementMode 

value = instance.AutomationElementMode

instance.AutomationElementMode = value

Property Value

Type: System.Windows.Automation.AutomationElementMode
Full if the returned elements have a full reference to the underlying user interface (UI); otherwise None.

Full is the default value, and specifies that returned elements contain a full reference to the underlying UI. None specifies that the returned elements have no reference to the underlying UI, and contain only cached information.

Certain operations on elements, including GetCurrentPropertyValue, GetCurrentPattern, and SetFocus, require a full reference; attempting to perform these on an element that has none results in an InvalidOperationException.

Using None can be more efficient when only properties are needed, as it avoids the overhead involved in setting up full references.

In the following example, AutomationElementMode is set to None, with the result that only cached properties and patterns are available for the retrieved object.

''' <summary> 
''' Caches and retrieves properties for a list item by using CacheRequest.Push. 
''' </summary> 
''' <param name="elementList">Element from which to retrieve a child element.</param> 
''' <remarks> 
''' This code demonstrates various aspects of caching. It is not intended to be  
''' an example of a useful method. 
''' </remarks> 
Private Sub CachePropertiesByPush(ByVal elementList As AutomationElement)
    ' Set up the request. 
    Dim cacheRequest As New CacheRequest()

    ' Do not get a full reference to the cached objects, only to their cached properties and patterns.
    cacheRequest.AutomationElementMode = AutomationElementMode.None

    ' Cache all elements, regardless of whether they are control or content elements.
    cacheRequest.TreeFilter = Automation.RawViewCondition

    ' Property and pattern to cache.
    cacheRequest.Add(AutomationElement.NameProperty)
    cacheRequest.Add(SelectionItemPattern.Pattern)

    ' Activate the request.
    cacheRequest.Push()

    ' Obtain an element and cache the requested items. 
    Dim myCondition As New PropertyCondition(AutomationElement.IsSelectionItemPatternAvailableProperty, _
        True)
    Dim elementListItem As AutomationElement = elementList.FindFirst(TreeScope.Children, myCondition)

    ' At this point, you could call another method that creates a CacheRequest and calls Push/Pop. 
    ' While that method was retrieving automation elements, the CacheRequest set in this method  
    ' would not be active.  
    ' Deactivate the request.
    cacheRequest.Pop()

    ' Retrieve the cached property and pattern. 
    Dim itemName As String = elementListItem.Cached.Name
    Dim pattern As SelectionItemPattern = _
        DirectCast(elementListItem.GetCachedPattern(SelectionItemPattern.Pattern), SelectionItemPattern)

    ' The following is an alternative way of retrieving the Name property.
    itemName = CStr(elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty))

    ' This is yet another way, which returns AutomationElement.NotSupported if the element does 
    ' not supply a value. If the second parameter is false, a default name is returned. 
    Dim objName As Object = elementListItem.GetCachedPropertyValue(AutomationElement.NameProperty, True)
    If objName Is AutomationElement.NotSupported Then
        itemName = "Unknown" 
    Else
        itemName = CStr(objName)
    End If 
    ' The following call raises an exception, because only the cached properties are available,  
    '  as specified by cacheRequest.AutomationElementMode. If AutomationElementMode had its 
    '  default value (Full), this call would be valid. 
    '** bool enabled = elementListItem.Current.IsEnabled; ** 

End Sub 'CachePropertiesByPush

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0
Show: