Protocol

NSAccessibility

The complete list of properties and methods implemented by accessible elements.

Declaration

@protocol NSAccessibility

Overview

In general, your custom user interface elements should not adopt this protocol. Instead, select the role-specific protocol—such as NSAccessibilityButton, NSAccessibilityImage, or NSAccessibilityGroup—that best matches your element’s behavior.

Many AppKit classes already adopt the NSAccessibility protocol by default. In particular, NSView, NSWindow, NSCell and NSDrawer provide a default implementation for all the properties and methods listed in this protocol. However, if you create a custom subclass that adopts one of the role-specific protocols, the compiler may ask you to reimplement some of the protocol’s accessor or action methods. By forcing you to reimplement these methods, the compiler ensures your custom subclass provides accurate information to the accessibility clients.

If your custom user interface element does not inherit from NSView (or one of the other accessibility-enabled AppKit classes), subclass the NSAccessibilityElement class instead. This class manages many of the details required to work with accessibility clients successfully. You also need to implement all the properties and methods from your user interface element’s role-specific protocol—as well as any additional properties and methods you may need to use to further customize your element’s behavior.

Customizing User Interface Elements

You can further customize any user interface elements by freely implementing any of the other properties or methods listed in the NSAccessibility protocol. You do not need to adopt any particular protocol to make these properties and methods available to the accessibility client. As soon as your element is accessibility enabled, the system automatically uses any of the NSAccessibility properties and methods that you have implemented.

If a user interface element inherits from NSView (or one of the other accessibility-enabled AppKit classes), you can also customize it by simply setting the appropriate properties. Often, you can fine tune how an accessibility client interacts with your element without creating a custom subclass.

Sometimes, however, it makes more sense to override the property’s accessor methods. If you override the getter for a property declared in the NSAccessibility protocol, the system lets accessibility clients call your getter. This can be particularly useful when managing dynamic properties, because you can calculate their current value on demand instead of trying to update the property in response to a change.

If you override the setter for a property, by default the system lets accessibility clients both read and modify that property. For example, you can override the setter for a control’s accessibilityValue property, letting users modify the control’s value through an accessibility client.

You can further control which accessor methods the accessibility client can use by overriding isAccessibilitySelectorAllowed:. Return YES if the accessibility client can call the selector; otherwise, NO.

Topics

Configuring Accessibility

accessibilityElement

A Boolean value that determines whether the accessibility element participates in the accessibility hierarchy.

Required.

accessibilityEnabled

A Boolean value that determines whether the element responds to user events.

Required.

accessibilityFrame

The element’s frame in screen coordinates.

Required.

accessibilityHelp

The help text for the accessibility element.

Required.

accessibilityLabel

A short description of the accessibility element.

Required.

accessibilityTitle

The title of the accessibility element—for example, a button’s visible text.

Required.

accessibilityValue

The element’s value.

Required.

Setting Content and Values

accessibilityContents

The contents of the current element.

Required.

accessibilityCriticalValue

The critical value for this level indicator.

Required.

accessibilityIdentifier

The accessibility element’s identity.

Required.

accessibilityMaxValue

The maximum value for the accessibility element.

Required.

accessibilityMinValue

The minimum value for the accessibility element.

Required.

accessibilityOrientation

The orientation of the element.

Required.

accessibilityProtectedContent

A Boolean value that determines whether the element contains protected content.

Required.

accessibilitySelected

A Boolean value that determines whether the element is currently selected.

Required.

accessibilityURL

The URL associated with the element.

Required.

accessibilityValueDescription

A human-readable description of the accessibility element’s value.

Required.

accessibilityWarningValue

The warning value for this level indicator.

Required.

Determining Relationships

accessibilityChildren

The child elements in the accessibility hierarchy.

Required.

accessibilityChildrenInNavigationOrder

An array of child elements, ordered for linear navigation.

Required.

accessibilityParent

The accessibility element’s parent in the accessibility hierarchy.

Required.

accessibilitySelectedChildren

The element’s currently selected children.

Required.

accessibilityTopLevelUIElement

The top-level element that contains the accessibility element.

Required.

accessibilityVisibleChildren

The element’s visible child elements.

Required.

Setting the Focus

accessibilityApplicationFocusedUIElement

The child element with the current focus.

Required.

accessibilityFocused

A Boolean value that determines whether the accessibility element has the keyboard focus.

Required.

accessibilityFocusedWindow

The child window with the current focus.

Required.

accessibilitySharedFocusElements

An array of elements that share the keyboard focus with the element.

Required.

Assigning Actions and Roles

accessibilityCustomActions

The custom actions of the current element.

Required.

accessibilityCustomRotors

The custom rotors of the current element.

Required.

accessibilityRequired

A Boolean value that determines whether the element is required to have content for successful submission of a form.

Required.

accessibilityRole

The type of interface element represented by the accessibility element.

Required.

accessibilityRoleDescription

A localized, human-intelligible description of the element’s role, such as "radio button.”

Required.

accessibilitySubrole

The specialized interface element type represented by the accessibility element.

Required.

Configuring Text Elements

accessibilityInsertionPointLineNumber

The line number containing the insertion point.

Required.

accessibilityNumberOfCharacters

The number of characters in the text.

Required.

accessibilityPlaceholderValue

The placeholder value for this accessibility element.

Required.

accessibilitySelectedText

The currently selected text.

Required.

accessibilitySelectedTextRange

The range of the currently selected text.

Required.

accessibilitySelectedTextRanges

An array of NSValue ranges for the currently selected text.

Required.

accessibilitySharedCharacterRange

The range of characters displayed by the accessibility element.

Required.

accessibilitySharedTextUIElements

Other elements that share text with the accessibility element.

Required.

accessibilityVisibleCharacterRange

The range of visible characters in the document.

Required.

- accessibilityStringForRange:

Returns the substring for the specified range.

Required.

- accessibilityAttributedStringForRange:

Returns the attributed substring for the specified range of characters.

Required.

- accessibilityRTFForRange:

Returns the Rich Text Format (RTF) data that describes the specified range of characters.

Required.

- accessibilityFrameForRange:

Returns the rectangle enclosing the specified range of characters.

Required.

- accessibilityLineForIndex:

Returns the line number for the line holding the specified character index.

Required.

- accessibilityRangeForIndex:

Returns the range of characters for the glyph that includes the specified character.

Required.

- accessibilityStyleRangeForIndex:

Returns a range of characters that all have the same style as the specified character.

Required.

- accessibilityRangeForLine:

Returns the range of characters in the specified line.

Required.

- accessibilityRangeForPosition:

Returns the range of characters for the glyph at the specified point.

Required.

Configuring Windows

accessibilityActivationPoint

The activation point for this user interface element.

Required.

accessibilityAlternateUIVisible

A Boolean value that determines whether the element’s alternative UI is currently visible.

Required.

accessibilityCancelButton

The child element representing the window’s cancel button.

Required.

accessibilityCloseButton

The child element representing the window’s close button.

Required.

accessibilityDefaultButton

The child element representing the window’s default button.

Required.

accessibilityFullScreenButton

The child element representing the window’s full screen button.

Required.

accessibilityGrowArea

The child element representing the window’s grow area.

Required.

accessibilityMain

A Boolean value that determines whether this window is the app’s main window.

Required.

accessibilityMinimizeButton

The child element representing the window’s minimize button.

Required.

accessibilityMinimized

A Boolean value that determines whether this window is minimized.

Required.

accessibilityModal

A Boolean value that determines whether the window is modal.

Required.

accessibilityProxy

The child element representing the window’s proxy icon.

Required.

accessibilityShownMenu

The menu currently being displayed for the element.

Required.

accessibilityToolbarButton

The child element representing the window’s toolbar button.

Required.

accessibilityWindow

The window that contains the element.

Required.

accessibilityZoomButton

The child element representing the window’s zoom button.

Required.

Managing Apps

accessibilityExtrasMenuBar

The icon for the app’s menu bar extra.

Required.

accessibilityFrontmost

A Boolean value that determines whether this app is the frontmost app.

Required.

accessibilityHidden

A Boolean value that determines whether this app is hidden.

Required.

accessibilityMainWindow

The app’s main window.

Required.

accessibilityMenuBar

The app’s menu bar.

Required.

accessibilityWindows

An array containing all the app’s windows.

Required.

Configuring Grid Views

accessibilityColumnCount

The number of columns in the element’s grid.

Required.

accessibilityOrderedByRow

A Boolean value that determines whether the element’s grid is ordered row major or column major.

Required.

accessibilityRowCount

The number of rows in the element’s grid.

Required.

Configuring Scroll Views

accessibilityHorizontalScrollBar

The horizontal scroll bar for this scroll view.

Required.

accessibilityVerticalScrollBar

The vertical scroll bar for this scroll view.

Required.

Configuring Table and Outline Views

NSAccessibilitySortDirection

Values that indicate the sort direction of a column.

accessibilityColumnHeaderUIElements

The column header elements for this table or outline.

Required.

accessibilityColumns

The column elements for this table or outline.

Required.

accessibilityColumnTitles

The column titles for the element.

Required.

accessibilityExpanded

A Boolean value that determines whether the element is expanded.

Required.

accessibilityHeader

The header for this table view.

Required.

accessibilityIndex

The index of the row or column represented by the element.

Required.

accessibilityRowHeaderUIElements

The row header elements for this table or outline.

Required.

accessibilityRows

The row elements for this table or outline.

Required.

accessibilitySelectedColumns

The currently selected columns for this table or outline.

Required.

accessibilitySelectedRows

The currently selected rows for this table or outline.

Required.

accessibilitySortDirection

The element’s sort direction.

Required.

accessibilityVisibleColumns

The visible columns for this table or outline.

Required.

accessibilityVisibleRows

The visible rows for this table or outline.

Required.

Outline Views

accessibilityDisclosed

A Boolean value that determines whether this row is disclosing other rows.

Required.

accessibilityDisclosedByRow

The row disclosing this row.

Required.

accessibilityDisclosedRows

The rows disclosed by this row.

Required.

accessibilityDisclosureLevel

The indention level for this row.

Required.

Configuring Cell-Based Tables

accessibilityColumnIndexRange

The column index range of the cell.

Required.

accessibilityRowIndexRange

The row index range of the cell.

Required.

accessibilitySelectedCells

The currently selected cells for this table.

Required.

accessibilityVisibleCells

The visible cells for this table.

Required.

- accessibilityCellForColumn:row:

The cell at the specified column and row.

Required.

Configuring Layout

accessibilityHandles

The drag handle elements for this layout item element.

Required.

accessibilityHorizontalUnits

The units that this layout area element uses for horizontal values.

Required.

accessibilityHorizontalUnitDescription

A description of the layout area’s horizontal units.

Required.

accessibilityVerticalUnits

The units that this layout area element uses for vertical values.

Required.

accessibilityVerticalUnitDescription

A description of the layout area’s vertical units.

Required.

- accessibilityLayoutPointForScreenPoint:

Converts the provided point in screen coordinates to a point in the layout area’s coordinate system.

Required.

- accessibilityLayoutSizeForScreenSize:

Converts the provided size in screen coordinates to a size in the layout area’s coordinate system.

Required.

- accessibilityScreenPointForLayoutPoint:

Converts the provided point in the layout area’s coordinates to a point in the screen’s coordinate system.

Required.

- accessibilityScreenSizeForLayoutSize:

Converts the provided size in the layout area’s coordinates to a size in the screen’s coordinate system.

Required.

Configuring Sliders

accessibilityAllowedValues

The allowed values for this slider element.

Required.

accessibilityLabelUIElements

The child label elements for this slider element.

Required.

accessibilityLabelValue

The value of this label element.

Required.

Configuring Split Views

accessibilityNextContents

The contents following this divider element.

Required.

accessibilityPreviousContents

The contents preceding this divider element.

Required.

accessibilitySplitters

An array that contains the views and splitter bar from this split view.

Required.

Tabs and Toolbars

accessibilityOverflowButton

The overflow button for this toolbar.

Required.

accessibilityTabs

The tab elements for this tab view.

Required.

Configuring Ruler Views

NSAccessibilityRulerMarkerType

Values that indicate the marker type of an element.

NSAccessibilityUnits

Values that indicate the unit values of a ruler or layout area.

accessibilityMarkerGroupUIElement

The user interface element that functions as a marker group for this ruler element.

Required.

accessibilityMarkerTypeDescription

A human-readable description of the marker type.

Required.

accessibilityMarkerUIElements

An array of marker elements for this ruler.

Required.

accessibilityMarkerValues

The marker values for this ruler.

Required.

accessibilityRulerMarkerType

The type of markers used on this ruler.

Required.

accessibilityUnits

The units used on this ruler.

Required.

accessibilityUnitDescription

A human-readable description of this ruler’s units.

Required.

Managing Documents and Editing

accessibilityDocument

The URL for the file represented by the element.

Required.

accessibilityEdited

A Boolean value that determines whether the element has been edited.

Required.

accessibilityFilename

The filename for the file represented by the element.

Required.

Configuring Linkage Elements

accessibilityLinkedUIElements

The elements associated with the element.

Required.

accessibilityServesAsTitleForUIElements

The list of elements for which the element acts as a title.

Required.

accessibilityTitleUIElement

A static text element that represents the element’s title.

Required.

Configuring Search

accessibilityClearButton

The clear button for this search field.

Required.

accessibilityDecrementButton

The decrement button for this stepper element.

Required.

accessibilityIncrementButton

The increment button for this stepper element.

Required.

accessibilitySearchButton

The search button for this search field.

Required.

accessibilitySearchMenu

The search menu for this search field.

Required.

Confirming and Canceling Operations

- accessibilityPerformCancel

Cancels the current operation.

Required.

- accessibilityPerformConfirm

Simulates pressing Return in the element.

Required.

- accessibilityPerformDecrement

Decrements the element’s value.

Required.

- accessibilityPerformDelete

Deletes the element’s value.

Required.

- accessibilityPerformIncrement

Increments the element’s value.

Required.

- accessibilityPerformPick

Selects the element.

Required.

- accessibilityPerformPress

Simulates clicking the element.

Required.

- accessibilityPerformRaise

Brings this window to the front.

Required.

- accessibilityPerformShowAlternateUI

Displays the element’s alternate UI.

Required.

- accessibilityPerformShowDefaultUI

Returns to the element’s original UI.

Required.

- accessibilityPerformShowMenu

Displays this menu element.

Required.

- isAccessibilitySelectorAllowed:

Indicates whether the provided selector can be invoked on the element.

Required.

Managing Notifications

Notifications alert accessibility clients to changes in the user interface’s state.

NSAccessibilityUIElementsKey

An array of elements that are associated with the notification.

NSAccessibilityAnnouncementKey

The announcement, as a localized string.

NSAccessibilityPriorityKey

A priority level that can help an assistive app determine how to handle the corresponding notification.

NSAccessibilityNotificationName

The name of the notification.

NSAccessibilityNotificationUserInfoKey

The key used in the user info dictionary for notifications.

Constants

NSAccessibilityPriorityLevel

A data type for notification priority levels.

NSAccessibilityOrientation

Values that indicate the orientation of elements, such as scroll bars and split views.

Notification Priority Levels

Values for specifying the priority level of a notification.

Roles

The type of objects that accessibility elements represent.

Subroles

Specialized object subtypes that accessibility elements represent.

Accessibility Notifcations and Error Codes

The keys in a posted accessibility notification's dictionary.

See Also

First Steps

NSAccessibilityContainsTransientUI

A set of methods that support accessibility in a UI that changes dynamically—usually in response to mouse-hover events.