Loading...
Searching...
No Matches
juce::AccessibilityHandler Class Reference

## Detailed Description

Base class for accessible Components.

This class wraps a Component and provides methods that allow an accessibility client, such as VoiceOver on macOS, or Narrator on Windows, to control it.

It handles hierarchical navigation, properties, state, and various interfaces.

The documentation for this class was generated from the following file:

- juce_gui_basics/accessibility/juce_AccessibilityHandler.h

## Classes

struct | Interfaces
| Utility struct which holds one or more accessibility interfaces. More...

## Public Types

enum class | AnnouncementPriority { low , medium , high }
| A priority level that can help an accessibility client determine how to handle an announcement request. More...

## Public Member Functions

| AccessibilityHandler (Component &componentToWrap, AccessibilityRole accessibilityRole, AccessibilityActions actions={}, Interfaces interfaces={})
| Constructor.
virtual | ~AccessibilityHandler ()
| Destructor.
const Component & | getComponent () const noexcept
| Returns the Component that this handler represents.
Component & | getComponent () noexcept
| Returns the Component that this handler represents.
AccessibilityRole | getRole () const noexcept
| The type of UI element that this accessibility handler represents.
virtual String | getTitle () const
| The title of the UI element.
virtual String | getDescription () const
| A short description of the UI element.
virtual String | getHelp () const
| Some help text for the UI element (if required).
virtual AccessibleState | getCurrentState () const
| Returns the current state of the UI element.
bool | isIgnored () const
| Returns true if this UI element should be ignored by accessibility clients.
bool | isVisibleWithinParent () const
| Returns true if this UI element is visible within its parent.
const AccessibilityActions & | getActions () const noexcept
| Returns the set of actions that the UI element supports and the associated callbacks.
AccessibilityValueInterface * | getValueInterface () const
| Returns the value interface for this UI element, or nullptr if it is not supported.
AccessibilityTableInterface * | getTableInterface () const
| Returns the table interface for this UI element, or nullptr if it is not supported.
AccessibilityCellInterface * | getCellInterface () const
| Returns the cell interface for this UI element, or nullptr if it is not supported.
AccessibilityTextInterface * | getTextInterface () const
| Returns the text interface for this UI element, or nullptr if it is not supported.
AccessibilityHandler * | getParent () const
| Returns the first unignored parent of this UI element in the accessibility hierarchy, or nullptr if this is a root element without a parent.
std::vector< AccessibilityHandler * > | getChildren () const
| Returns the unignored children of this UI element in the accessibility hierarchy.
bool | isParentOf (const AccessibilityHandler *possibleChild) const noexcept
| Checks whether a given UI element is a child of this one in the accessibility hierarchy.
AccessibilityHandler * | getChildAt (Point< int > screenPoint)
| Returns the deepest child of this UI element in the accessibility hierarchy that contains the given screen point, or nullptr if there is no child at this point.
AccessibilityHandler * | getChildFocus ()
| Returns the deepest UI element which currently has focus.
bool | hasFocus (bool trueIfChildFocused) const
| Returns true if this UI element has the focus.
void | grabFocus ()
| Tries to give focus to this UI element.
void | giveAwayFocus () const
| If this UI element or any of its children in the accessibility hierarchy currently have focus, this will defocus it.
void | notifyAccessibilityEvent (AccessibilityEvent event) const
| Used to send a notification to any observing accessibility clients that something has changed in the UI element.
AccessibilityNativeHandle * | getNativeImplementation () const
std::type_index | getTypeIndex () const

## Static Public Member Functions

static void | postAnnouncement (const String &announcementString, AnnouncementPriority priority)
| Posts an announcement to be made to the user.
static void | postSystemNotification (const String &notificationTitle, const String &notificationBody)
| Posts a local system notification.
static void | clearCurrentlyFocusedHandler ()
static void * | getNativeChildForComponent (Component &component)
static void | setNativeChildForComponent (Component &component, void *nativeChild)
static Component * | getComponentForNativeChild (void *nativeChild)

## Member Enums

## AnnouncementPriority

enum class juce::AccessibilityHandler::AnnouncementPriority

strong

A priority level that can help an accessibility client determine how to handle an announcement request.

Exactly what this controls is platform-specific, but generally a low priority announcement will be read when the screen reader is free, whereas a high priority announcement will interrupt the current speech.

Enumerator
low |
medium |
high |

## Constructors and Destructors

## AccessibilityHandler()

juce::AccessibilityHandler::AccessibilityHandler | ( | Component & | componentToWrap,
|  | AccessibilityRole | accessibilityRole,
|  | AccessibilityActions | actions = {},
|  | Interfaces | interfaces = {} )

Constructor.

This will create a AccessibilityHandler which wraps the provided Component and makes it visible to accessibility clients. You must also specify a role for the UI element from the AccessibilityRole list which best describes it.

To enable users to interact with the UI element you should provide the set of supported actions and their associated callbacks via the accessibilityActions parameter.

For UI elements that support more complex interaction the value, text, table, and cell interfaces should be implemented as required and passed as the final argument of this constructor. See the documentation of these classes for more information about the types of control they represent and which methods need to be implemented.

Referenced by AccessibilityNativeHandle, getChildAt(), getChildFocus(), getChildren(), getParent(), and isParentOf().

## ~AccessibilityHandler()

virtual juce::AccessibilityHandler::~AccessibilityHandler | ( |  | ) |

virtual

Destructor.

## Member Functions

## getComponent() [1/2]

const Component & juce::AccessibilityHandler::getComponent | ( |  | ) | const

inline noexcept

Returns the Component that this handler represents.

## getComponent() [2/2]

Component & juce::AccessibilityHandler::getComponent | ( |  | ) |

inline noexcept

Returns the Component that this handler represents.

## getRole()

AccessibilityRole juce::AccessibilityHandler::getRole | ( |  | ) | const

inline noexcept

The type of UI element that this accessibility handler represents.

See also
  AccessibilityRole

## getTitle()

virtual String juce::AccessibilityHandler::getTitle | ( |  | ) | const

inline virtual

The title of the UI element.

This will be read out by the system and should be concise, preferably matching the visible title of the UI element (if any). For example, this might be the text of a button or a simple label.

The default implementation will call Component::getTitle(), but you can override this to return a different string if required.

If neither a name nor a description is provided then the UI element may be ignored by accessibility clients.

This must be a localised string.

## getDescription()

virtual String juce::AccessibilityHandler::getDescription | ( |  | ) | const

inline virtual

A short description of the UI element.

This may be read out by the system. It should not include the type of the UI element and should ideally be a single word, for example "Open" for a button that opens a window.

The default implementation will call Component::getDescription(), but you can override this to return a different string if required.

If neither a name nor a description is provided then the UI element may be ignored by accessibility clients.

This must be a localised string.

## getHelp()

virtual String juce::AccessibilityHandler::getHelp | ( |  | ) | const

inline virtual

Some help text for the UI element (if required).

This may be read out by the system. This string functions in a similar way to a tooltip, for example "Click to open window." for a button which opens a window.

The default implementation will call Component::getHelpText(), but you can override this to return a different string if required.

This must be a localised string.

## getCurrentState()

virtual AccessibleState juce::AccessibilityHandler::getCurrentState | ( |  | ) | const

virtual

Returns the current state of the UI element.

The default implementation of this method will set the focusable flag and, if this UI element is currently focused, will also set the focused flag.

## isIgnored()

bool juce::AccessibilityHandler::isIgnored | ( |  | ) | const

Returns true if this UI element should be ignored by accessibility clients.

## isVisibleWithinParent()

bool juce::AccessibilityHandler::isVisibleWithinParent | ( |  | ) | const

Returns true if this UI element is visible within its parent.

This will always return true for UI elements with the AccessibleState::accessibleOffscreen flag set.

## getActions()

const AccessibilityActions & juce::AccessibilityHandler::getActions | ( |  | ) | const

noexcept

Returns the set of actions that the UI element supports and the associated callbacks.

## getValueInterface()

AccessibilityValueInterface * juce::AccessibilityHandler::getValueInterface | ( |  | ) | const

Returns the value interface for this UI element, or nullptr if it is not supported.

See also
  AccessibilityValueInterface

References getValueInterface().

Referenced by getValueInterface().

## getTableInterface()

AccessibilityTableInterface * juce::AccessibilityHandler::getTableInterface | ( |  | ) | const

Returns the table interface for this UI element, or nullptr if it is not supported.

See also
  AccessibilityTableInterface

References getTableInterface().

Referenced by getTableInterface().

## getCellInterface()

AccessibilityCellInterface * juce::AccessibilityHandler::getCellInterface | ( |  | ) | const

Returns the cell interface for this UI element, or nullptr if it is not supported.

See also
  AccessibilityCellInterface

References getCellInterface().

Referenced by getCellInterface().

## getTextInterface()

AccessibilityTextInterface * juce::AccessibilityHandler::getTextInterface | ( |  | ) | const

Returns the text interface for this UI element, or nullptr if it is not supported.

See also
  AccessibilityTextInterface

References getTextInterface().

Referenced by getTextInterface().

## getParent()

AccessibilityHandler * juce::AccessibilityHandler::getParent | ( |  | ) | const

Returns the first unignored parent of this UI element in the accessibility hierarchy, or nullptr if this is a root element without a parent.

References AccessibilityHandler(), and getParent().

Referenced by getParent().

## getChildren()

std::vector< AccessibilityHandler * > juce::AccessibilityHandler::getChildren | ( |  | ) | const

Returns the unignored children of this UI element in the accessibility hierarchy.

References AccessibilityHandler(), and getChildren().

Referenced by getChildren().

## isParentOf()

bool juce::AccessibilityHandler::isParentOf | ( | const AccessibilityHandler * | possibleChild | ) | const

noexcept

Checks whether a given UI element is a child of this one in the accessibility hierarchy.

References AccessibilityHandler(), and isParentOf().

Referenced by isParentOf().

## getChildAt()

AccessibilityHandler * juce::AccessibilityHandler::getChildAt | ( | Point< int > | screenPoint | ) |

Returns the deepest child of this UI element in the accessibility hierarchy that contains the given screen point, or nullptr if there is no child at this point.

References AccessibilityHandler(), and getChildAt().

Referenced by getChildAt().

## getChildFocus()

AccessibilityHandler * juce::AccessibilityHandler::getChildFocus | ( |  | ) |

Returns the deepest UI element which currently has focus.

This can be a child of this UI element or, if no child is focused, this element itself.

Note that this can be different to the value of the Component with keyboard focus returned by Component::getCurrentlyFocusedComponent().

See also
  hasFocus

References AccessibilityHandler(), and getChildFocus().

Referenced by getChildFocus().

## hasFocus()

bool juce::AccessibilityHandler::hasFocus | ( | bool | trueIfChildFocused | ) | const

Returns true if this UI element has the focus.

Parameters

  trueIfChildFocused | if this is true, this method will also return true if any child of this UI element in the accessibility hierarchy has focus

References hasFocus().

Referenced by hasFocus().

## grabFocus()

void juce::AccessibilityHandler::grabFocus | ( |  | ) |

Tries to give focus to this UI element.

If the UI element is focusable and not ignored this will update the currently focused element, try to give keyboard focus to the Component it represents, and notify any listening accessibility clients that the current focus has changed.

See also
  hasFocus, giveAwayFocus

References grabFocus().

Referenced by grabFocus().

## giveAwayFocus()

void juce::AccessibilityHandler::giveAwayFocus | ( |  | ) | const

If this UI element or any of its children in the accessibility hierarchy currently have focus, this will defocus it.

This will also give away the keyboard focus from the Component it represents, and notify any listening accessibility clients that the current focus has changed.

See also
  hasFocus, grabFocus

References giveAwayFocus().

Referenced by giveAwayFocus().

## notifyAccessibilityEvent()

void juce::AccessibilityHandler::notifyAccessibilityEvent | ( | AccessibilityEvent | event | ) | const

Used to send a notification to any observing accessibility clients that something has changed in the UI element.

See also
  AccessibilityEvent

References notifyAccessibilityEvent().

Referenced by notifyAccessibilityEvent().

## postAnnouncement()

void juce::AccessibilityHandler::postAnnouncement | ( | const String & | announcementString,
|  | AnnouncementPriority | priority )

static

Posts an announcement to be made to the user.

Parameters

  announcementString | a localised string containing the announcement to be read out
  priority | the appropriate priority level for the announcement

## postSystemNotification()

void juce::AccessibilityHandler::postSystemNotification | ( | const String & | notificationTitle,
|  | const String & | notificationBody )

static

Posts a local system notification.

In order for this to do anything, the following conditions must be met.

- At build time:
  - The juce_gui_extra module must be included in the project.
  - Push notifications must be enabled by setting the preprocessor definition JUCE_PUSH_NOTIFICATIONS=1
- At run time:
  - An accessibility client (narrator, voiceover etc.) must be active.

Additionally, on Android, an icon is required for notifications. This must be specified by adding the path to the icon file called "accessibilitynotificationicon" in the "Extra Android Raw Resources" setting in the Projucer.

This will use the push notification client on macOS, iOS and Android. On Windows this will create a system tray icon to post the notification.

Parameters

  notificationTitle | the title of the notification
  notificationBody | the main body text of the notification

## getNativeImplementation()

AccessibilityNativeHandle * juce::AccessibilityHandler::getNativeImplementation | ( |  | ) | const

References AccessibilityNativeHandle.

## getTypeIndex()

std::type_index juce::AccessibilityHandler::getTypeIndex | ( |  | ) | const

inline

## clearCurrentlyFocusedHandler()

void juce::AccessibilityHandler::clearCurrentlyFocusedHandler | ( |  | ) |

inline static

## getNativeChildForComponent()

void * juce::AccessibilityHandler::getNativeChildForComponent | ( | Component & | component | ) |

static

## setNativeChildForComponent()

void juce::AccessibilityHandler::setNativeChildForComponent | ( | Component & | component,
|  | void * | nativeChild )

static

## getComponentForNativeChild()

Component * juce::AccessibilityHandler::getComponentForNativeChild | ( | void * | nativeChild | ) |

static

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited