Edit

SemanticZoom Control Type

  • Article

This topic provides information about UI Automation support for the SemanticZoom control type.

Semantic Zoom is a technique introduced in Windows 8 for presenting and navigating large sets of related data or content within a single view, such as a photo album, app list, or address book. Semantic Zoom uses two distinct modes of classification, or zoom levels, for organizing and presenting the content. The low-level (or zoomed in) mode displays items in a flat, "all-up" structure; and the high-level (or zoomed out) mode displays items in groups, enabling the user to quickly navigate and browse through the content. For example, zooming a list of cities might change to a list of states containing those cities. Zooming a list of programs might change to a list of logical program groups.

For more information about Semantic Zoom specifically as used for Windows Store apps, see Guidelines for Semantic Zoom.

The usage model for the SemanticZoom control type is unusual in that it exists mainly for programmatic access. Microsoft UI Automation clients can monitor and manipulate the Semantic Zoom control to control the zoomed-in state of the list. Users who are not using assistive technology would typically manipulate the Semantic Zoom control directly through touch gestures or keyboard shortcuts.

The following sections define the required UI Automation tree structure, properties, control patterns, and events for the SemanticZoom control type. The UI Automation requirements apply to all Semantic Zoom controls where the UI framework/platform integrates UI Automation support for control types and control patterns.

This topic contains the following sections.

Typical Tree Structure

The following table depicts a typical control and content view of the UI Automation tree that pertains to the SemanticZoom control type and describes what can be contained in each view. For more information about the UI Automation tree, see UI Automation Tree Overview.

Control View Content View
  • List
    • [SemanticZoom]
      • ListItem (0 or more)
  • List
    • ListItem (0 or more)

Or:

Control View Content View
  • [SemanticZoom]
    • List
      • ListItem (0 or more)
  • List
    • ListItem (0 or more)

Relevant Properties

The following table lists the UI Automation properties whose value or definition is especially relevant to the controls that implement the SemanticZoom control type. For more information about UI Automation properties, see Retrieving Properties from UI Automation Elements.

UI Automation Property Value Notes
UIA_AutomationIdPropertyId See notes. The value of this property must be unique among all peer elements in the raw view of the UI Automation tree.
UIA_BoundingRectanglePropertyId See notes. The outermost rectangle that contains the whole control.
UIA_ClickablePointPropertyId See notes. If the list control has a clickable point (a point that can be clicked to cause the list to take focus), that point must be exposed through this property. If the value of the UIA_IsOffscreenPropertyId property is TRUE, attempting to retrieve this property results in the UIA_E_NOCLICKABLEPOINT error.
UIA_ControlTypePropertyId SemanticZoom
UIA_IsContentElementPropertyId TRUE
UIA_IsControlElementPropertyId TRUE
UIA_IsKeyboardFocusablePropertyId FALSE
UIA_LabeledByPropertyId See notes. If there is a static text label, this property must expose a reference to that control.
UIA_LocalizedControlTypePropertyId See notes. A localized string corresponding to the SemanticZoom control type. The default value is "semantic zoom" for en-US or English (United States). Note: Some frameworks concatenated this as "semanticzoom".
UIA_NamePropertyId See notes. An empty string is acceptable, or a more useful name could be provided, as long as it does not contain the term semantic zoom , which would make the combination of control type and name confusing.

Required Control Patterns and Properties

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

Control Pattern/Pattern Property Support/Value Notes
IToggleProvider Depends Semantic Zoom controls support the Toggle control pattern to allow the zoom to be enabled or disabled. ToggleState_Off corresponds to the flat, all-up state, and ToggleState_On corresponds to the high level, zoomed-out view.

Required Events

The following table lists the UI Automation events that Semantic Zoom controls are required to support. For more information on events, see UI Automation Events Overview.

UI Automation Event Notes
UIA_BoundingRectanglePropertyId property-changed event.
UIA_IsEnabledPropertyId property-changed event. If the control supports the IsEnabled property, it must support this event.
UIA_IsOffscreenPropertyId property-changed event. If the control supports the IsOffscreen property, it must support this event.
UIA_ToggleToggleStatePropertyId property-changed event.

Remarks

If a UI has a visible button to toggle Semantic Zoom control behavior, this button should not have a SemanticZoom control type. This is counter-intuitive, but the SemanticZoom control type characterizes the container of the zooming content, not a button that controls the zoom. (Such a button could be represented simply as a Button control type with the Toggle control pattern.)

UI Automation Control Types Overview

UI Automation Overview