AutomationInteropProvider.RaiseStructureChangedEvent Method (IRawElementProviderSimple, StructureChangedEventArgs)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Raises an event when the UI Automation tree has changed.

Namespace:   System.Windows.Automation.Provider
Assembly:  UIAutomationProvider (in UIAutomationProvider.dll)

public static void RaiseStructureChangedEvent(
	IRawElementProviderSimple provider,
	StructureChangedEventArgs e
)

Parameters

provider
Type: System.Windows.Automation.Provider.IRawElementProviderSimple

The element associated with the event.

e
Type: System.Windows.Automation.StructureChangedEventArgs

Information about the event.

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.

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);
    }
}

.NET Framework
Available since 3.0
Return to top
Show: