Creating an Accessibility Object for a Simple HIView

If your custom subview is an HIView and it contains no substructure, create an accessibility object for it with an identifier value of 0. Recall from The Carbon Implementation of the Accessibility Object that an identifier value of 0 indicates that the accessibility object represents the user interface element as a whole. Because this accessibility object represents a user interface element that has no substructure, it automatically represents the element as a whole.

To create an accessibility object for such a user interface element, use the AXUIElementCreateWithHIObjectAndIdentifier function, passing in the HIViewRef reference and 0, as shown below:

accessibilityObject = AXUIElementCreateWithHIObjectAndIdentifier( HIObjectRef myHIView, 0 )

Because your custom subview is an HIView, Carbon provides attribute values it can extract from the object, such as size and position. As with other accessibility objects in your application, however, you must provide the context-specific information that Carbon cannot determine. For information on providing descriptive and linking information, see Making a Standard Carbon Application Accessible. If there are additional attribute values you need to provide, do this with custom event handlers. For more information on how to do this, see Install Custom Event Handlers.

Creating an Accessibility Object for a Complex HIView

Although most custom HIViews an application might create are uncomplicated, it’s not uncommon for an application to need a custom HIView with complex substructure. From an accessibility perspective, however, such an HIView is accessible but its contents are not. This is because Carbon does not automatically create accessibility objects for the children of a custom HIView.

If you do this in your application, the first thing you need to do is create an accessibility object to represent each accessible child of the HIView. As mentioned in Creation of Accessibility Objects, you may choose to create these accessibility objects only when needed (in response to an assistive application’s requests) or in advance (when you open the application or display a window). Either way, when it’s time to provide an accessible subview, use the AXUIElementCreateWithHIObjectAndIdentifier function to create an accessibility object for it.

As described in The Carbon Implementation of the Accessibility Object, an accessibility object consists of an HIObject and an identifier. If you are creating an accessibility object for a child view of an HIView, for example, pass to the AXUIElementCreateWithHIObjectAndIdentifier function:

• The HIViewRef of the parent object

• An integer you define that uniquely identifies the subview

As with other accessibility objects in your application, you must provide the context-specific descriptive and linking information that Carbon cannot determine. For information on providing this information, see Making a Standard Carbon Application Accessible. To provide additional attribute values, use custom event handlers, as described in Install Custom Event Handlers.

Handle Events for Simple Subviews

If you use a custom class to implement a simple subview of an HIView, your main task is to make sure the parent view is aware of its child view. This ensures that your subview accessibility object is part of the accessibility hierarchy. Then, you may choose to provide handlers for other events.

To ensure that the parent HIView is aware of your simple subview, you must insert the accessibility object you’ve created for the subview into the parent’s children attribute array. To do this, you install on the parent HIView a handler for the kEventAccessibleGetNamedAttribute event that listens for a request for the value of the children attribute. When such a request arrives, your custom handler gets the parent HIView’s children attribute array and inserts your accessibility object.

After your custom accessibility object is a member of its parent’s children attribute array, you can rely on the parent’s default hit-testing and keyboard-focus handlers to return your subview when appropriate.

Handle Events for Complex Subviews

If you implement a complex subview, you must handle the kEventAccessibleGetNamedAttribute event both for your parent HIView (as described in Handle Events for Simple Subviews) and for your top-level subview. In addition, you must handle the hit-testing and keyboard-focus events that request information about your subview’s children.

To report information about your subview’s internal structure, install on your subview’s accessibility object a handler for the kEventAccessibleGetNamedAttribute event. Your custom handler responds to the request for the value of the children attribute by creating and returning an array of the subview’s accessible child accessibility objects. If your complex subview represents several levels of containment, you have to provide a similar handler for each level.

To handle the hit-testing and keyboard-focus events for your subview’s accessible children, install handlers for the kEventAccessibleGetChildAtPoint and kEventAccessibleGetFocusedChild events. It is important to return only the immediate child of the accessibility object receiving these events, not a grandchild or more distant descendant. This is because the Carbon accessibility implementation automatically handles the recursive traversal of the accessibility hierarchy.

Handle Action Events

If the custom subviews you create support actions, you must also handle the following events:

• kEventAccessibleGetAllActionNames

• kEventAccessibleGetNamedActionDescription

• kEventAccessiblePerformNamedAction

Your handler for the kEventAccessibleGetAllActionNames event must return the names of all actions your custom subview supports. Action names are defined in AXActionConstants.h (in the HIServices framework) and are of the form AXActionname, such as AXRaise and AXPush. To supply these names, you create a CFString for each action name and insert them into the mutable CFArray in the event’s kEventParamAccessibleActionNames parameter.

Unlike an action name, such as AXRaise, an action description is a human-intelligible, localizable string that names the action, such as “raise”. If your custom subview supports an action, you must also supply the action description. If you’re developing in Mac OS X version10.4 or later, you can use the AXUIElementCopyActionDescription convenience function (defined in AXUIElement.h) to get the current system-defined action description instead of hard-coding it. This way, your action description will always be consistent with the system’s action descriptions, even if they change.

Use the action description to modify the mutable CFString in the event’s kEventParamAccessibleActionDescription parameter.

An assistive application uses the kEventAccessiblePerformNamedAction event to tell an accessibility object to perform an action. If you provide a custom subview that performs actions, you must handle this event.

Beginning in Mac OS X version 10.3, the kEventAccessiblePerformNamedAction event includes a parameter that allows you to defer the action if performing it involves a call to a routine that might not return immediately. This can happen if your application performs a modal action, such as bringing up a menu. An assistive application waiting for confirmation of the performance of an action can time out if it takes too long. The assistive application can interpret this as a failure to perform the action (and give this feedback to the user), even if your application is running normally.

To avoid this situation, you can check the kEventParamAccessibilityEventQueued parameter. If it indicates the event has been queued, you can perform the action (including the calls to routines that might not return immediately) without causing an assistive application to time out. If it indicates the event has not been queued, you can request the event be queued and sent to you later. To request the event be queued, return eventDeferAccessibilityEventErr from your event handler.