Protocol

NSAccessibilityProtocol

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

Declaration

protocol NSAccessibilityProtocol

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 true if the accessibility client can call the selector; otherwise, false.

Topics

Configuring Text Elements

func accessibilityString(for: NSRange) -> String?

Returns the substring for the specified range.

Required.

func accessibilityAttributedString(for: NSRange) -> NSAttributedString?

Returns the attributed substring for the specified range of characters.

Required.

func accessibilityRTF(for: NSRange) -> Data?

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

Required.

func accessibilityFrame(for: NSRange) -> NSRect

Returns the rectangle enclosing the specified range of characters.

Required.

func accessibilityLine(for: Int) -> Int

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

Required.

func accessibilityRange(for: Int) -> NSRange

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

Required.

func accessibilityStyleRange(for: Int) -> NSRange

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

Required.

func accessibilityRange(forLine: Int) -> NSRange

Returns the range of characters in the specified line.

Required.

func accessibilityRange(for: NSPoint) -> NSRange

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

Required.

Configuring Table and Outline Views

enum NSAccessibilitySortDirection

Values that indicate the sort direction of a column.

Configuring Cell-Based Tables

func accessibilityCell(forColumn: Int, row: Int) -> Any?

The cell at the specified column and row.

Required.

Configuring Layout

func accessibilityLayoutPoint(forScreenPoint: NSPoint) -> NSPoint

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

Required.

func accessibilityLayoutSize(forScreenSize: NSSize) -> NSSize

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

Required.

func accessibilityScreenPoint(forLayoutPoint: NSPoint) -> NSPoint

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

Required.

func accessibilityScreenSize(forLayoutSize: NSSize) -> NSSize

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

Required.

Configuring Ruler Views

enum NSAccessibilityRulerMarkerType

Values that indicate the marker type of an element.

enum NSAccessibilityUnits

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

Confirming and Canceling Operations

func accessibilityPerformCancel() -> Bool

Cancels the current operation.

Required.

func accessibilityPerformConfirm() -> Bool

Simulates pressing Return in the element.

Required.

func accessibilityPerformDecrement() -> Bool

Decrements the element’s value.

Required.

func accessibilityPerformDelete() -> Bool

Deletes the element’s value.

Required.

func accessibilityPerformIncrement() -> Bool

Increments the element’s value.

Required.

func accessibilityPerformPick() -> Bool

Selects the element.

Required.

func accessibilityPerformPress() -> Bool

Simulates clicking the element.

Required.

func accessibilityPerformRaise() -> Bool

Brings this window to the front.

Required.

func accessibilityPerformShowAlternateUI() -> Bool

Displays the element’s alternate UI.

Required.

func accessibilityPerformShowDefaultUI() -> Bool

Returns to the element’s original UI.

Required.

func accessibilityPerformShowMenu() -> Bool

Displays this menu element.

Required.

func isAccessibilitySelectorAllowed(Selector) -> Bool

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.

init(rawValue: String)

Returns a new notification object with a specified name and object.

static let uiElements: NSAccessibility.NotificationUserInfoKey

An array of elements that are associated with the notification.

static let priority: NSAccessibility.NotificationUserInfoKey

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

struct NSAccessibility.Notification

The name of the notification.

struct NSAccessibility.NotificationUserInfoKey

The key used in the user info dictionary for notifications.

Other Accessor Methods

Additional accessibility methods organized by getter and setter.

Constants

enum NSAccessibilityPriorityLevel

A data type for notification priority levels.

enum 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

protocol NSAccessibilityContainsTransientUI

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