UI Automation Support for the MenuItem Control Type

Note

This documentation is intended for .NET Framework developers who want to use the managed UI Automation classes defined in the System.Windows.Automation namespace. For the latest information about UI Automation, see Windows Automation API: UI Automation.

This topic provides information about Microsoft UI Automation support for the MenuItem control type. It describes the control's Microsoft UI Automation tree structure and provides the properties and control patterns that are required for the MenuItem control type.

A menu control allows hierarchal organization of elements associated with commands and event handlers. In a typical Microsoft Windows application, a menu bar contains several menu items (such as File, Edit, and Window), and each menu item displays a menu. A menu contains a collection of menu items (such as New, Open, and Close), which can be expanded to display additional menu items or perform a specific action when clicked. A menu item can be hosted in a menu, menu bar, or tool bar.

The following sections define the required UI Automation tree structure, properties, control patterns, and events for the MenuItem control type. The UI Automation requirements apply to all list controls, whether Windows Presentation Foundation (WPF), Win32, or Windows Forms.

This topic contains the following sections.

  • Required UI Automation Tree Structure
  • Required UI Automation Properties
  • Required UI Automation Control Patterns
  • UI Automation Events for Menu Item
  • Required UI Automation Events
  • Legacy Issues
  • Related Topics

Required UI Automation Tree Structure

The following table depicts the control view and the content view of the UI Automation tree that pertains to menu item controls and describes what can be contained in each view. For more information on the UI Automation tree, see UI Automation Tree Overview.

Control View

Content View

MenuItem "Help"

  • Menu (sub menu of Help menu item)

    • MenuItem "Help Topics"

    • MenuItem "About Notepad"

MenuItem "Help"

  • MenuItem "Help Topics"

  • MenuItem "About Notepad"

The control view of the menu item control has the UI Automation tree structure shown above. Note that the Help menu item is inlcluded to better illustrate the structure in a typical menu to submenu hierarchy.

For the content view, Menu is absent from the UI Automation tree because it does not convey meaningful information to the end user.

Required UI Automation Properties

The following table lists the UI Automation properties whose value or definition is especially relevant to menu item controls. For more information on UI Automation properties, see UI Automation Properties for Clients.

Property

Value

Description

AutomationIdProperty

See notes.

The value of this property needs to be unique across all controls in an application.

BoundingRectangleProperty

See notes.

The outermost rectangle that contains the whole control.

ClickablePointProperty

See notes.

Supported if there is a bounding rectangle. If not every point within the bounding rectangle is clickable, and you perform specialized hit testing, then override and provide a clickable point.

IsKeyboardFocusableProperty

See notes.

If the control can receive keyboard focus, it must support this property.

NameProperty

See notes.

The menu item control is included in the content view of the UI Automation tree and is self labeled with a name.

LabeledByProperty

Null

No label.

ControlTypeProperty

MenuItem

This value is the same for all UI frameworks.

LocalizedControlTypeProperty

"menu item"

Localized string corresponding to the MenuItem control type.

IsContentElementProperty

True

The menu item control is never included in the content view of the UI Automation tree.

IsControlElementProperty

True

The menu item control must always be included in the control view of the UI Automation tree.

Required UI Automation Control Patterns

The following table lists the UI Automation control patterns required to be supported by menu item controls. For more information on control patterns, see UI Automation Control Patterns Overview.

Control Pattern Property

Support

Notes

IExpandCollapseProvider

Depends

If the control can be expanded or collapsed, implement IExpandCollapseProvider.

IInvokeProvider

Depends

If the control executes a single action or command, implement IInvokeProvider.

IToggleProvider

Depends

If the control represents an option that can be turned on or off, implement IToggleProvider.

ISelectionItemProvider

Depends

If the control is used to select from a list of options among menu items, implement ISelectionItemProvider.

UI Automation Events for Menu Item

The following table lists the Microsoft UI Automation events associated with the menu item control.

Event

Support

Explanation

InvokedEvent

Depends

Must be raised if control supports Invoke control pattern.

ToggleStateProperty property-changed event.

Depends

Must be raised if control supports Toggle control pattern.

ExpandCollapseStateProperty property-changed event.

Depends

Must be raised if control supports Expand Collapse control pattern.

ElementSelectedEvent

Depends

None.

Required UI Automation Events

The following table lists the UI Automation events required to be supported by all menu item controls. For more information on events, see UI Automation Events Overview.

UI Automation Event

Support/Value

Notes

InvokedEvent

Depends

None

ElementAddedToSelectionEvent

Depends

None

ElementRemovedFromSelectionEvent

Depends

None

ElementSelectedEvent

Depends

None

BoundingRectangleProperty property-changed event.

Required

None

IsOffscreenProperty property-changed event.

Required

None

IsEnabledProperty property-changed event.

Required

None

ExpandCollapseStateProperty property-changed event.

Depends

None

ToggleStateProperty property-changed event.

Depends

None

AutomationFocusChangedEvent

Required

None

StructureChangedEvent

Required

None

Legacy Issues

Toggle Pattern will only be supported when the Win32 menu item is checked and can be programmatically determined necessary to support Toggle Pattern. Because the Win32 menu item does not expose whether it has the ability to be checked, Invoke Pattern will be supported when the menu item is not checked. An exception will be made to always support Invoke Pattern even for menu items that should only support Toggle Pattern. This is so clients do not become confused that an element that was supporting Invoke Pattern (when menu item was unchecked) no longer supports the pattern once it becomes checked.

See Also

Reference

MenuItem

Concepts

UI Automation Control Patterns Overview

UI Automation Control Types Overview

UI Automation Overview