JUCE  v6.1.6 (6.0.8-1114)
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::AccessibilityHandler Class Reference

Base class for accessible Components. More...

#include <juce_AccessibilityHandler.h>

Collaboration diagram for juce::AccessibilityHandler:

Classes

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

Public Types

enum  AnnouncementPriority {
  AnnouncementPriority::low,
  AnnouncementPriority::medium,
  AnnouncementPriority::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. More...
 
virtual ~AccessibilityHandler ()
 Destructor. More...
 
const AccessibilityActionsgetActions () const noexcept
 Returns the set of actions that the UI element supports and the associated callbacks. More...
 
AccessibilityCellInterfacegetCellInterface () const
 Returns the cell interface for this UI element, or nullptr if it is not supported. More...
 
AccessibilityHandlergetChildAt (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. More...
 
AccessibilityHandlergetChildFocus ()
 Returns the deepest UI element which currently has focus. More...
 
std::vector< AccessibilityHandler * > getChildren () const
 Returns the unignored children of this UI element in the accessibility hierarchy. More...
 
const ComponentgetComponent () const noexcept
 Returns the Component that this handler represents. More...
 
ComponentgetComponent () noexcept
 Returns the Component that this handler represents. More...
 
virtual AccessibleState getCurrentState () const
 Returns the current state of the UI element. More...
 
virtual String getDescription () const
 A short description of the UI element. More...
 
virtual String getHelp () const
 Some help text for the UI element (if required). More...
 
AccessibilityNativeHandlegetNativeImplementation () const
 
AccessibilityHandlergetParent () 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. More...
 
AccessibilityRole getRole () const noexcept
 The type of UI element that this accessibility handler represents. More...
 
AccessibilityTableInterfacegetTableInterface () const
 Returns the table interface for this UI element, or nullptr if it is not supported. More...
 
AccessibilityTextInterfacegetTextInterface () const
 Returns the text interface for this UI element, or nullptr if it is not supported. More...
 
virtual String getTitle () const
 The title of the UI element. More...
 
std::type_index getTypeIndex () const
 
AccessibilityValueInterfacegetValueInterface () const
 Returns the value interface for this UI element, or nullptr if it is not supported. More...
 
void giveAwayFocus () const
 If this UI element or any of its children in the accessibility hierarchy currently have focus, this will defocus it. More...
 
void grabFocus ()
 Tries to give focus to this UI element. More...
 
bool hasFocus (bool trueIfChildFocused) const
 Returns true if this UI element has the focus. More...
 
bool isIgnored () const
 Returns true if this UI element should be ignored by accessibility clients. More...
 
bool isParentOf (const AccessibilityHandler *possibleChild) const noexcept
 Checks whether a given UI element is a child of this one in the accessibility hierarchy. More...
 
bool isVisibleWithinParent () const
 Returns true if this UI element is visible within its parent. More...
 
void notifyAccessibilityEvent (AccessibilityEvent event) const
 Used to send a notification to any observing accessibility clients that something has changed in the UI element. More...
 

Static Public Member Functions

static void postAnnouncement (const String &announcementString, AnnouncementPriority priority)
 Posts an announcement to be made to the user. More...
 

Private Member Functions

void giveAwayFocusInternal () const
 
void grabFocusInternal (bool)
 
void takeFocus ()
 

Static Private Member Functions

static std::unique_ptr< AccessibilityNativeImpl > createNativeImpl (AccessibilityHandler &)
 

Private Attributes

AccessibilityActions actions
 
Componentcomponent
 
Interfaces interfaces
 
std::unique_ptr< AccessibilityNativeImpl > nativeImpl
 
const AccessibilityRole role
 
std::type_index typeIndex
 

Static Private Attributes

static AccessibilityHandlercurrentlyFocusedHandler
 

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}

Member Enumeration Documentation

◆ AnnouncementPriority

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 

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.

◆ ~AccessibilityHandler()

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

Destructor.

Member Function Documentation

◆ createNativeImpl()

static std::unique_ptr<AccessibilityNativeImpl> juce::AccessibilityHandler::createNativeImpl ( AccessibilityHandler )
staticprivate

◆ getActions()

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

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

◆ getCellInterface()

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

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

See also
AccessibilityCellInterface

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

◆ 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

◆ getChildren()

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

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

◆ getComponent() [1/2]

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

◆ getComponent() [2/2]

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

Returns the Component that this handler represents.

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

Referenced by juce::UIAExpandCollapseProvider::get_ExpandCollapseState(), juce::UIAToggleProvider::getCurrentToggleState(), and juce::UIASelectionProvider::isMultiSelectable().

◆ getDescription()

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

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
inlinevirtual

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.

◆ getNativeImplementation()

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

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

◆ getRole()

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

The type of UI element that this accessibility handler represents.

See also
AccessibilityRole

◆ getTableInterface()

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

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

See also
AccessibilityTableInterface

◆ getTextInterface()

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

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

See also
AccessibilityTextInterface

◆ getTitle()

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

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.

◆ getTypeIndex()

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

◆ getValueInterface()

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

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

See also
AccessibilityValueInterface

Referenced by juce::UIAValueProvider::get_IsReadOnly(), and juce::UIAValueProvider::get_Value().

◆ 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

◆ giveAwayFocusInternal()

void juce::AccessibilityHandler::giveAwayFocusInternal ( ) const
private

◆ 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

◆ grabFocusInternal()

void juce::AccessibilityHandler::grabFocusInternal ( bool  )
private

◆ hasFocus()

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

Returns true if this UI element has the focus.

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

Referenced by juce::UIATextProvider::GetCaretRange().

◆ isIgnored()

bool juce::AccessibilityHandler::isIgnored ( ) const

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

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

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

◆ 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

◆ postAnnouncement()

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

Posts an announcement to be made to the user.

Parameters
announcementStringa localised string containing the announcement to be read out
prioritythe appropriate priority level for the announcement

◆ takeFocus()

void juce::AccessibilityHandler::takeFocus ( )
private

Friends And Related Function Documentation

◆ AccessibilityNativeHandle

friend class AccessibilityNativeHandle
friend

Member Data Documentation

◆ actions

AccessibilityActions juce::AccessibilityHandler::actions
private

◆ component

Component& juce::AccessibilityHandler::component
private

◆ currentlyFocusedHandler

AccessibilityHandler* juce::AccessibilityHandler::currentlyFocusedHandler
staticprivate

◆ interfaces

Interfaces juce::AccessibilityHandler::interfaces
private

◆ nativeImpl

std::unique_ptr<AccessibilityNativeImpl> juce::AccessibilityHandler::nativeImpl
private

◆ role

const AccessibilityRole juce::AccessibilityHandler::role
private

◆ typeIndex

std::type_index juce::AccessibilityHandler::typeIndex
private

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