Base class for accessible Components. More...

#include "juce_AccessibilityHandler.h"

Inheritance diagram for juce::AccessibilityHandler:

Classes
class	AccessibilityNativeImpl

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	clearCurrentlyFocusedHandler ()

static void *	getNativeChildForComponent (Component &component)

static void	setNativeChildForComponent (Component &component, void *nativeChild)

static Component *	getComponentForNativeChild (void *nativeChild)

Friends
class	AccessibilityNativeHandle

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.

@tags{Accessibility}

Definition at line 40 of file juce_AccessibilityHandler.h.

Member Enumeration Documentation

◆ 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.

Definition at line 275 of file juce_AccessibilityHandler.h.

Constructor & Destructor Documentation

◆ 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.

Definition at line 88 of file juce_AccessibilityHandler.cpp.

◆ ~AccessibilityHandler()

juce::AccessibilityHandler::~AccessibilityHandler ( )

virtual

Destructor.

Definition at line 101 of file juce_AccessibilityHandler.cpp.

Member Function Documentation

◆ clearCurrentlyFocusedHandler()

static void juce::AccessibilityHandler::clearCurrentlyFocusedHandler ( )

static

Definition at line 295 of file juce_AccessibilityHandler.h.

◆ getActions()

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

noexcept

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

Definition at line 152 of file juce_AccessibilityHandler.cpp.

◆ getCellInterface()

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

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

See also: AccessibilityCellInterface

Definition at line 167 of file juce_AccessibilityHandler.cpp.

◆ 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.

Definition at line 285 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 297 of file juce_AccessibilityHandler.cpp.

◆ getChildren()

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

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

Definition at line 237 of file juce_AccessibilityHandler.cpp.

◆ getComponent() [1/2]

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

noexcept

Returns the Component that this handler represents.

Definition at line 98 of file juce_AccessibilityHandler.h.

◆ getComponent() [2/2]

Component & juce::AccessibilityHandler::getComponent ( )

noexcept

Returns the Component that this handler represents.

Definition at line 101 of file juce_AccessibilityHandler.h.

◆ getComponentForNativeChild()

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

static

Definition at line 387 of file juce_AccessibilityHandler.cpp.

◆ getCurrentState()

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.

Reimplemented in juce::detail::ButtonAccessibilityHandler, juce::ComboBoxAccessibilityHandler, and juce::LabelAccessibilityHandler.

Definition at line 108 of file juce_AccessibilityHandler.cpp.

◆ getDescription()

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

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.

Definition at line 140 of file juce_AccessibilityHandler.h.

◆ getHelp()

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

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.

Reimplemented in juce::detail::ButtonAccessibilityHandler, juce::ComboBoxAccessibilityHandler, juce::LabelAccessibilityHandler, juce::SliderAccessibilityHandler, and juce::TextEditor::EditorAccessibilityHandler.

Definition at line 152 of file juce_AccessibilityHandler.h.

◆ getNativeChildForComponent()

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

static

Definition at line 382 of file juce_AccessibilityHandler.cpp.

◆ getNativeImplementation()

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

Definition at line 400 of file juce_AccessibilityHandler.cpp.

◆ 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.

Definition at line 229 of file juce_AccessibilityHandler.cpp.

◆ getRole()

AccessibilityRole juce::AccessibilityHandler::getRole ( ) const

noexcept

The type of UI element that this accessibility handler represents.

See also: AccessibilityRole

Definition at line 108 of file juce_AccessibilityHandler.h.

◆ getTableInterface()

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

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

See also: AccessibilityTableInterface

Definition at line 162 of file juce_AccessibilityHandler.cpp.

◆ getTextInterface()

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

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

See also: AccessibilityTextInterface

Definition at line 172 of file juce_AccessibilityHandler.cpp.

◆ getTitle()

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

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.

Reimplemented in juce::detail::ButtonAccessibilityHandler, juce::ComboBoxAccessibilityHandler, and juce::LabelAccessibilityHandler.

Definition at line 124 of file juce_AccessibilityHandler.h.

◆ getTypeIndex()

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

Definition at line 293 of file juce_AccessibilityHandler.h.

◆ getValueInterface()

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

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

See also: AccessibilityValueInterface

Definition at line 157 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 316 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 310 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 303 of file juce_AccessibilityHandler.cpp.

◆ isIgnored()

bool juce::AccessibilityHandler::isIgnored ( ) const

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

Definition at line 119 of file juce_AccessibilityHandler.cpp.

◆ 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.

Definition at line 272 of file juce_AccessibilityHandler.cpp.

◆ 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.

Definition at line 145 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 398 of file juce_AccessibilityHandler.cpp.

◆ 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

Definition at line 399 of file juce_AccessibilityHandler.cpp.

◆ setNativeChildForComponent()

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

static

Definition at line 392 of file juce_AccessibilityHandler.cpp.

Friends And Related Symbol Documentation

◆ AccessibilityNativeHandle

friend class AccessibilityNativeHandle

friend

Definition at line 317 of file juce_AccessibilityHandler.h.

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

juce_gui_basics/accessibility/juce_AccessibilityHandler.h
juce_gui_basics/accessibility/juce_AccessibilityHandler.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ AnnouncementPriority

Constructor & Destructor Documentation

◆ AccessibilityHandler()

◆ ~AccessibilityHandler()

Member Function Documentation

◆ clearCurrentlyFocusedHandler()

◆ getActions()

◆ getCellInterface()

◆ getChildAt()

◆ getChildFocus()

◆ getChildren()

◆ getComponent() [1/2]

◆ getComponent() [2/2]

◆ getComponentForNativeChild()

◆ getCurrentState()

◆ getDescription()

◆ getHelp()

◆ getNativeChildForComponent()

◆ getNativeImplementation()

◆ getParent()

◆ getRole()

◆ getTableInterface()

◆ getTextInterface()

◆ getTitle()

◆ getTypeIndex()

◆ getValueInterface()

◆ giveAwayFocus()

◆ grabFocus()

◆ hasFocus()

◆ isIgnored()

◆ isParentOf()

◆ isVisibleWithinParent()

◆ notifyAccessibilityEvent()

◆ postAnnouncement()

◆ setNativeChildForComponent()

Friends And Related Symbol Documentation

◆ AccessibilityNativeHandle