AutomationInteropProvider.RaiseStructureChangedEvent Method

Reference

Definition

Namespace:: System.Windows.Automation.Provider

Assembly:: UIAutomationProvider.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Raises an event when the UI Automation tree has changed.

public:
 static void RaiseStructureChangedEvent(System::Windows::Automation::Provider::IRawElementProviderSimple ^ provider, System::Windows::Automation::StructureChangedEventArgs ^ e);

public static void RaiseStructureChangedEvent (System.Windows.Automation.Provider.IRawElementProviderSimple provider, System.Windows.Automation.StructureChangedEventArgs e);

static member RaiseStructureChangedEvent : System.Windows.Automation.Provider.IRawElementProviderSimple * System.Windows.Automation.StructureChangedEventArgs -> unit

Public Shared Sub RaiseStructureChangedEvent (provider As IRawElementProviderSimple, e As StructureChangedEventArgs)

Parameters

provider: IRawElementProviderSimple

The element associated with the event.

e: StructureChangedEventArgs

Information about the event.

Examples

The following example shows how to raise an event when children are added to, or removed from, a custom list box.

/// <summary>
/// Responds to an addition to the UI Automation tree structure by raising an event.
/// </summary>
/// <param name="list">
/// The list to which the item was added.
/// </param>
/// <remarks>
/// For the runtime Id of the item, pass 0 because the provider cannot know
/// what its actual runtime Id is.
/// </remarks>
public static void OnStructureChangeAdd(CustomListControl list)
{
    if (AutomationInteropProvider.ClientsAreListening)
    {
        int[] fakeRuntimeId = { 0 };
        StructureChangedEventArgs args =
            new StructureChangedEventArgs(StructureChangeType.ChildrenBulkAdded, 
            fakeRuntimeId);
        AutomationInteropProvider.RaiseStructureChangedEvent(
            (IRawElementProviderSimple)list.Provider, args);
    }
}

/// <summary>
/// Responds to a removal from the UI Automation tree structure 
/// by raising an event.
/// </summary>
/// <param name="list">
/// The list from which the item was removed.
/// </param>
/// <remarks>
/// For the runtime Id of the list, pass 0 because the provider cannot know
/// what its actual runtime ID is.
/// </remarks>
public static void OnStructureChangeRemove(CustomListControl list)
{
    if (AutomationInteropProvider.ClientsAreListening)
    {
        int[] fakeRuntimeId = { 0 };
        StructureChangedEventArgs args =
            new StructureChangedEventArgs(StructureChangeType.ChildrenBulkRemoved, 
            fakeRuntimeId);
        AutomationInteropProvider.RaiseStructureChangedEvent(
            (IRawElementProviderSimple)list.Provider, args);
    }
}

''' <summary>
''' Responds to an addition to the UI Automation tree structure by raising an event.
''' </summary>
''' <param name="list">
''' The list to which the item was added.
''' </param>
''' <remarks>
''' For the runtime Id of the item, pass 0 because the provider cannot know
''' what its actual runtime Id is.
''' </remarks>
Public Shared Sub OnStructureChangeAdd(ByVal list As CustomListControl)
    If AutomationInteropProvider.ClientsAreListening Then
        Dim fakeRuntimeId(1) As Integer
        fakeRuntimeId(0) = 0
        Dim args As New StructureChangedEventArgs( _
            StructureChangeType.ChildrenBulkAdded, fakeRuntimeId)
        AutomationInteropProvider.RaiseStructureChangedEvent( _
            CType(list.Provider, IRawElementProviderSimple), args)
    End If

End Sub


''' <summary>
''' Responds to a removal from the UI Automation tree structure by raising an event.
''' </summary>
''' <param name="list">
''' The list from which the item was removed.
''' </param>
''' <remarks>
''' For the runtime Id of the list, pass 0 because the provider cannot know
''' what its actual runtime ID is.
''' </remarks>
Public Shared Sub OnStructureChangeRemove(ByVal list As CustomListControl)
    If AutomationInteropProvider.ClientsAreListening Then
        Dim fakeRuntimeId(1) As Integer
        fakeRuntimeId(0) = 0
        Dim args As New StructureChangedEventArgs( _
            StructureChangeType.ChildrenBulkRemoved, fakeRuntimeId)
        AutomationInteropProvider.RaiseStructureChangedEvent( _
            CType(list.Provider, IRawElementProviderSimple), args)
    End If

End Sub

Remarks

An example of a change in the tree structure is child elements being added to or removed from a list box, or being expanded or collapsed in a tree view.

When a child element is removed, the runtime identifier of either the element, or of its container, is passed to the StructureChangedEventArgs constructor. In the current version of UI Automation, however, there is no easy way for an instance of a provider to discover its runtime identifier. The GetRuntimeId method normally returns an array that contains AppendRuntimeId, a magic number that instructs the UI Automation system to create a unique identifer for every instance of the control. The raw value provided by GetRuntimeId should not be used in events, because it is meaningless to clients and cannot be used to identify a specific instance.

Because of this limitation, events of type ChildAdded and ChildRemoved are not very useful. As an alternative, always use ChildrenBulkAdded and ChildrenBulkRemoved, passing 0 as the runtime identifer. You cannot use null, as this will raise an exception. Clients will be notified that a change has been made in the container (identified by the sender parameter passed to the StructureChangedEventHandler), without specific notice of what children have been added or removed.

Applies to

Share via