Protocol

NSAccessibility

The NSAccessibility protocol declares the complete list of properties and methods implemented by accessible elements. 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.

Overview

By default, many of the AppKit classes already adopt the NSAccessibility protocol. 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 helps ensure that 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 true if the accessibility client can call the selector; otherwise, false.

Symbols

Text-Specific Properties and Methods

func accessibilityString(for: NSRange)

Returns the substring for the specified range.

func accessibilityAttributedString(for: NSRange)

Returns the attributed substring for the specified range of characters.

func accessibilityRTF(for: NSRange)

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

func accessibilityFrame(for: NSRange)

Returns the rectangle enclosing the specified range of characters.

func accessibilityLine(for: Int)

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

func accessibilityRange(for: Int)

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

func accessibilityStyleRange(for: Int)

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

func accessibilityRange(forLine: Int)

Returns the range of characters in the specified line.

func accessibilityRange(for: NSPoint)

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

Cell-Based Table Properties and Methods

func accessibilityCell(forColumn: Int, row: Int)

The cell at the specified column and row.

Layout Properties and Methods

func accessibilityLayoutPoint(forScreenPoint: NSPoint)

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

func accessibilityLayoutSize(forScreenSize: NSSize)

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

func accessibilityScreenPoint(forLayoutPoint: NSPoint)

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

func accessibilityScreenSize(forLayoutSize: NSSize)

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

Action Methods

func accessibilityPerformCancel()

Cancels the current operation.

func accessibilityPerformConfirm()

Simulates pressing Return in the element.

func accessibilityPerformDecrement()

Decrements the element’s value.

func accessibilityPerformDelete()

Deletes the element’s value.

func accessibilityPerformIncrement()

Increments the element’s value.

func accessibilityPerformPress()

Simulates clicking the element.

func accessibilityPerformRaise()

Brings this window to the front.

func accessibilityPerformShowAlternateUI()

Displays the element’s alternate UI.

func accessibilityPerformShowDefaultUI()

Returns to the element’s original UI.

func accessibilityPerformShowMenu()

Displays this menu element.

func isAccessibilitySelectorAllowed(Selector)

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

Constants

NSAccessibilitySortDirection

Values that indicate the sort direction of a column (used with the accessibilitySortDirection property).

NSAccessibilityUnits

Values that indicate the unit values of a ruler or layout area (used with the accessibilityHorizontalUnits, accessibilityVerticalUnits, and accessibilityUnits properties).

NSAccessibilityPriorityLevel

A data type for notification priority levels.

Notification Priority Levels

Values for specifying the priority level of a notification.

NSAccessibilityOrientation

Values that indicate the orientation of elements, such as scroll bars and split views. Use these values with an accessibility element’s accessibilityOrientation property.

Roles

Standard roles that identify the type of object that an accessibility element represents. Use these constants with an accessibility element’s accessibilityRole property.

NSAccessibilityRulerMarkerType

Values that indicate the marker type of an element. Use these values with an accessibility element’s accessibilityRulerMarkerType property.

Subroles

Subroles identify a specialized object subtype that an accessibility element represents. Use these constants with an accessibility element’s accessibilitySubrole property.

UserInfo Key for Error Codes in Accessibility Exceptions

A key used by the userInfo dictionary of an NSAccessibilityException.

UserInfo Keys for Posting Accessibility Notifications

Keys used by the userInfo dictionary of an accessibility notification posted using the NSAccessibilityPostNotificationWithUserInfo(_:_:_:) function.

Notifications

These notifications alert accessibility clients to changes in the user interface’s state. This lets the accessibility client present these changes to the user. AppKit classes automatically post notifications for their basic behaviors; however, you may need to post your own notifications if you want to modify a class’s behavior, or if you are implementing a custom accessibility element. Always send these notifications using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityAnnouncementRequestedNotification: String

This notification is posted whenever an accessibility element needs to make an announcement to the user. This notification requires a userInfo dictionary with the key NSAccessibilityAnnouncementKey and a localized string containing the announcement. To help an assistive app determine the importance of the announcement, add the appropriate NSAccessibilityPriorityKey to the userInfo dictionary.

let NSAccessibilityApplicationActivatedNotification: String

This notification is posted after the app has been activated. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityApplicationDeactivatedNotification: String

This notification is posted after the app has been deactivated. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityApplicationHiddenNotification: String

This notification is posted after the app is hidden. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityApplicationShownNotification: String

This notification is posted after the app is shown. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityCreatedNotification: String

This notification is posted after an accessibility element is created. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityDrawerCreatedNotification: String

This notification is posted after a drawer appears. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityFocusedUIElementChangedNotification: String

This notification is posted after an accessibility element gains focus. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityFocusedWindowChangedNotification: String

This notification is posted after the key window changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityHelpTagCreatedNotification: String

This notification is posted after a help tag appears. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityLayoutChangedNotification: String

This notification is posted after the UI changes in a way that requires the attention of an accessibility client. This notification should be accompanied by a userInfo dictionary with the key NSAccessibilityUIElementsKey and an array containing the UI elements that have been added or changed. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityMainWindowChangedNotification: String

This notification is posted after the main window changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityMovedNotification: String

This notification is posted after an accessibility element moves. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityResizedNotification: String

This notification is posted after an accessibility element’s size changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityRowCollapsedNotification: String

This notification is posted after a row collapses. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityRowCountChangedNotification: String

This notification is posted after a row is added or deleted. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityRowExpandedNotification: String

This notification is posted after a row expands. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedCellsChangedNotification: String

This notification is posted after one or more cells in a cell-based table are selected or deselected. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedChildrenChangedNotification: String

This notification is posted after one or more child elements are selected or deselected. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedChildrenMovedNotification: String

This notification is posted after the selected items in a layout area move. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedColumnsChangedNotification: String

This notification is posted after one or more columns are selected or deselected. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedRowsChangedNotification: String

This notification is posted after one or more rows are selected or deselected. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySelectedTextChangedNotification: String

This notification is posted after text is selected or deselected. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilitySheetCreatedNotification: String

This notification is posted after a sheet appears. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityTitleChangedNotification: String

This notification is posted after an accessibility element’s title changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityUIElementDestroyedNotification: String

This notification is posted after an accessibility element is destroyed. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityUnitsChangedNotification: String

This notification is posted after the units in a layout area change. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityValueChangedNotification: String

This notification is posted after an accessibility element’s value changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityWindowCreatedNotification: String

This notification is posted after a new window appears. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityWindowDeminiaturizedNotification: String

This notification is posted after a window is restored to full size from the Dock. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityWindowMiniaturizedNotification: String

This notification is posted after a window is put in the Dock. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityWindowMovedNotification: String

This notification is posted after a window moves. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

let NSAccessibilityWindowResizedNotification: String

This notification is posted after a window’s size changes. Post this notification using the NSAccessibilityPostNotification(_:_:) function instead of an NSNotificationCenter instance.

Instance Methods

func accessibilityActivationPoint()func accessibilityAllowedValues()func accessibilityApplicationFocusedUIElement()func accessibilityCancelButton()func accessibilityChildren()func accessibilityClearButton()func accessibilityCloseButton()func accessibilityColumnCount()func accessibilityColumnHeaderUIElements()func accessibilityColumnIndexRange()func accessibilityColumnTitles()func accessibilityColumns()func accessibilityContents()func accessibilityCriticalValue()func accessibilityDecrementButton()func accessibilityDefaultButton()func accessibilityDisclosedByRow()func accessibilityDisclosedRows()func accessibilityDisclosureLevel()func accessibilityDocument()func accessibilityExtrasMenuBar()func accessibilityFilename()func accessibilityFocusedWindow()func accessibilityFrame()func accessibilityFullScreenButton()func accessibilityGrowArea()func accessibilityHandles()func accessibilityHeader()func accessibilityHelp()func accessibilityHorizontalScrollBar()func accessibilityHorizontalUnitDescription()func accessibilityHorizontalUnits()func accessibilityIdentifier()func accessibilityIncrementButton()func accessibilityIndex()func accessibilityInsertionPointLineNumber()func accessibilityLabel()func accessibilityLabelUIElements()func accessibilityLabelValue()func accessibilityLinkedUIElements()func accessibilityMainWindow()func accessibilityMarkerGroupUIElement()func accessibilityMarkerTypeDescription()func accessibilityMarkerUIElements()func accessibilityMarkerValues()func accessibilityMaxValue()func accessibilityMenuBar()func accessibilityMinValue()func accessibilityMinimizeButton()func accessibilityNextContents()func accessibilityNumberOfCharacters()func accessibilityOrientation()func accessibilityOverflowButton()func accessibilityParent()func accessibilityPlaceholderValue()func accessibilityPreviousContents()func accessibilityProxy()func accessibilityRole()func accessibilityRoleDescription()func accessibilityRowCount()func accessibilityRowHeaderUIElements()func accessibilityRowIndexRange()func accessibilityRows()func accessibilityRulerMarkerType()func accessibilitySearchButton()func accessibilitySearchMenu()func accessibilitySelectedCells()func accessibilitySelectedChildren()func accessibilitySelectedColumns()func accessibilitySelectedRows()func accessibilitySelectedText()func accessibilitySelectedTextRange()func accessibilitySelectedTextRanges()func accessibilityServesAsTitleForUIElements()func accessibilitySharedCharacterRange()func accessibilitySharedFocusElements()func accessibilitySharedTextUIElements()func accessibilityShownMenu()func accessibilitySortDirection()func accessibilitySplitters()func accessibilitySubrole()func accessibilityTabs()func accessibilityTitle()func accessibilityTitleUIElement()func accessibilityToolbarButton()func accessibilityTopLevelUIElement()func accessibilityURL()func accessibilityUnitDescription()func accessibilityUnits()func accessibilityValue()func accessibilityValueDescription()func accessibilityVerticalScrollBar()func accessibilityVerticalUnitDescription()func accessibilityVerticalUnits()func accessibilityVisibleCells()func accessibilityVisibleCharacterRange()func accessibilityVisibleChildren()func accessibilityVisibleColumns()func accessibilityVisibleRows()func accessibilityWarningValue()func accessibilityWindow()func accessibilityWindows()func accessibilityZoomButton()func isAccessibilityAlternateUIVisible()func isAccessibilityDisclosed()func isAccessibilityEdited()func isAccessibilityElement()func isAccessibilityEnabled()func isAccessibilityExpanded()func isAccessibilityFocused()func isAccessibilityFrontmost()func isAccessibilityHidden()func isAccessibilityMain()func isAccessibilityMinimized()func isAccessibilityModal()func isAccessibilityOrderedByRow()func isAccessibilityProtectedContent()func isAccessibilityRequired()func isAccessibilitySelected()func setAccessibilityActivationPoint(NSPoint)func setAccessibilityAllowedValues([NSNumber]?)func setAccessibilityAlternateUIVisible(Bool)func setAccessibilityApplicationFocusedUIElement(Any?)func setAccessibilityCancelButton(Any?)func setAccessibilityChildren([Any]?)func setAccessibilityClearButton(Any?)func setAccessibilityCloseButton(Any?)func setAccessibilityColumnCount(Int)func setAccessibilityColumnHeaderUIElements([Any]?)func setAccessibilityColumnIndexRange(NSRange)func setAccessibilityColumnTitles([Any]?)func setAccessibilityColumns([Any]?)func setAccessibilityContents([Any]?)func setAccessibilityCriticalValue(Any?)func setAccessibilityDecrementButton(Any?)func setAccessibilityDefaultButton(Any?)func setAccessibilityDisclosed(Bool)func setAccessibilityDisclosedByRow(Any?)func setAccessibilityDisclosedRows(Any?)func setAccessibilityDisclosureLevel(Int)func setAccessibilityDocument(String?)func setAccessibilityEdited(Bool)func setAccessibilityElement(Bool)func setAccessibilityEnabled(Bool)func setAccessibilityExpanded(Bool)func setAccessibilityExtrasMenuBar(Any?)func setAccessibilityFilename(String?)func setAccessibilityFocused(Bool)func setAccessibilityFocusedWindow(Any?)func setAccessibilityFrame(NSRect)func setAccessibilityFrontmost(Bool)func setAccessibilityFullScreenButton(Any?)func setAccessibilityGrowArea(Any?)func setAccessibilityHandles([Any]?)func setAccessibilityHeader(Any?)func setAccessibilityHelp(String?)func setAccessibilityHidden(Bool)func setAccessibilityHorizontalScrollBar(Any?)func setAccessibilityHorizontalUnitDescription(String?)func setAccessibilityHorizontalUnits(NSAccessibilityUnits)func setAccessibilityIdentifier(String?)func setAccessibilityIncrementButton(Any?)func setAccessibilityIndex(Int)func setAccessibilityInsertionPointLineNumber(Int)func setAccessibilityLabel(String?)func setAccessibilityLabelUIElements([Any]?)func setAccessibilityLabelValue(Float)func setAccessibilityLinkedUIElements([Any]?)func setAccessibilityMain(Bool)func setAccessibilityMainWindow(Any?)func setAccessibilityMarkerGroupUIElement(Any?)func setAccessibilityMarkerTypeDescription(String?)func setAccessibilityMarkerUIElements([Any]?)func setAccessibilityMarkerValues(Any?)func setAccessibilityMaxValue(Any?)func setAccessibilityMenuBar(Any?)func setAccessibilityMinValue(Any?)func setAccessibilityMinimizeButton(Any?)func setAccessibilityMinimized(Bool)func setAccessibilityModal(Bool)func setAccessibilityNextContents([Any]?)func setAccessibilityNumberOfCharacters(Int)func setAccessibilityOrderedByRow(Bool)func setAccessibilityOrientation(NSAccessibilityOrientation)func setAccessibilityOverflowButton(Any?)func setAccessibilityParent(Any?)func setAccessibilityPlaceholderValue(String?)func setAccessibilityPreviousContents([Any]?)func setAccessibilityProtectedContent(Bool)func setAccessibilityProxy(Any?)func setAccessibilityRequired(Bool)func setAccessibilityRole(String?)func setAccessibilityRoleDescription(String?)func setAccessibilityRowCount(Int)func setAccessibilityRowHeaderUIElements([Any]?)func setAccessibilityRowIndexRange(NSRange)func setAccessibilityRows([Any]?)func setAccessibilityRulerMarkerType(NSAccessibilityRulerMarkerType)func setAccessibilitySearchButton(Any?)func setAccessibilitySearchMenu(Any?)func setAccessibilitySelected(Bool)func setAccessibilitySelectedCells([Any]?)func setAccessibilitySelectedChildren([Any]?)func setAccessibilitySelectedColumns([Any]?)func setAccessibilitySelectedRows([Any]?)func setAccessibilitySelectedText(String?)func setAccessibilitySelectedTextRange(NSRange)func setAccessibilitySelectedTextRanges([NSValue]?)func setAccessibilityServesAsTitleForUIElements([Any]?)func setAccessibilitySharedCharacterRange(NSRange)func setAccessibilitySharedFocusElements([Any]?)func setAccessibilitySharedTextUIElements([Any]?)func setAccessibilityShownMenu(Any?)func setAccessibilitySortDirection(NSAccessibilitySortDirection)func setAccessibilitySplitters([Any]?)func setAccessibilitySubrole(String?)func setAccessibilityTabs([Any]?)func setAccessibilityTitle(String?)func setAccessibilityTitleUIElement(Any?)func setAccessibilityToolbarButton(Any?)func setAccessibilityTopLevelUIElement(Any?)func setAccessibilityURL(URL?)func setAccessibilityUnitDescription(String?)func setAccessibilityUnits(NSAccessibilityUnits)func setAccessibilityValue(Any?)func setAccessibilityValueDescription(String?)func setAccessibilityVerticalScrollBar(Any?)func setAccessibilityVerticalUnitDescription(String?)func setAccessibilityVerticalUnits(NSAccessibilityUnits)func setAccessibilityVisibleCells([Any]?)func setAccessibilityVisibleCharacterRange(NSRange)func setAccessibilityVisibleChildren([Any]?)func setAccessibilityVisibleColumns([Any]?)func setAccessibilityVisibleRows([Any]?)func setAccessibilityWarningValue(Any?)func setAccessibilityWindow(Any?)func setAccessibilityWindows([Any]?)func setAccessibilityZoomButton(Any?)