java/14 : java.desktop/javax/accessibility/package-info.java

javax.accessibility
https://openjdk.java.net/
GPLv2 + Classpath Exception
/*
 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

Defines a contract between user-interface components and an assistive
technology that provides access to those components. If a Java application
fully supports the Java Accessibility API, then it should be compatible with,
and friendly toward, assistive technologies such as screen readers, screen
magnifiers, etc. With a Java application that fully supports the Java
Accessibility API, no screen reader off screen model would be necessary
because the API provides all of the information normally contained in an off
screen model.

The Java Accessibility API package consists of 8 Java programming language
interfaces, and 6 Java programming language classes. These are described
below.
Interface
Accessible
Interface Accessible is the main interface of the Java Accessibility API. All components that support the Java Accessibility API must implement this interface. It contains a single method, getAccessibleContext, that returns an instance of the class AccessibleContext. Sun thinks that
implementing this interface is the absolute minimum requirement of every
object that is part of the user interface of a Java application, if that
program is to be compatible with assistive technologies.
Class
AccessibleContext
AccessibleContext represents the minimum information all accessible objects return and is obtained by calling the getAccessibleContext method on an object that implements the Accessible interface. This information includes the
accessible name, description, role, and
state of the object, as well as information
about the parent and children of the object.  In addition,
JavaBeans™ property change support is also included to allow assistive
technologies learn when the values of the accessible properties change.
AccessibleContext also contains methods for obtaining more specific
accessibility information about a component. If the component supports it,
these methods will return an object that implements one or more of the
following interfaces:

    AccessibleAction - the object can perform one or more actions. This interface provides the standard mechanism for an assistive technology to determine what those actions are and tell the object to perform those actions. Any object that can be manipulated should return an object that implements this interface when the getAccessibleAction method is called on an AccessibleContext. 
    AccessibleComponent - the object has a graphical representation. This interface provides the standard mechanism for an assistive technology to determine and set the graphical representation of the object. Any object that is rendered on the screen should return an object that implements this interface when the getAccessibleComponent method is called on an AccessibleContext.
    AccessibleSelection - the object allows its children to be selected. This interface provides the standard mechanism for an assistive technology to determine the currently selected children as well as modify the selection set. Any object that has children that can be selected should return an object that implements this interface when the getAccessibleSelection method is called on an AccessibleContext.
    AccessibleText - the object presents editable textual information on the display. This interface provides the standard mechanism for an assistive technology to access that text via its content, attributes, and spatial location. Any object that contains editable text should return an object that implements this interface when the getAccessibleText method is called on an AccessibleContext.
    AccessibleHypertext - the object presents hypertext information on the display. This interface provides the standard mechanism for an assistive technology to access that hypertext via its content, attributes, and spatial location. Any object that contains hypertext should return an object that implements this interface when the getAccessibleText method is called on an AccessibleContext.
    AccessibleValue - the object supports a numerical value. This interface provides the standard mechanism for an assistive technology to determine and set the current value of the object, as well as the minimum and maximum values. Any object that supports a numerical value should return an object that implements this interface when the getAccessibleValue method is called on an AccessibleContext.

Class
AccessibleRole
 This class encapsulates the Accessible object's role in the user interface and is obtained by calling the getAccessibleRole method on an AccessibleContext. Accessible roles include "Check box", "Menu Item", "Panel", etc. These roles are identified by the constants in this class such as AccessibleRole.CHECK_BOX,
AccessibleRole.MENU_ITEM, and AccessibleRole.PANEL. The constants in this class present a strongly typed enumeration of common object roles. A public constructor for this class has been purposely omitted and applications should use one of the constants from this class. Although this class pre-defines a large list of standard roles, it is extensible so additional programmer-defined roles can be added in the future without needing to modify the base class. Class
AccessibleState
 This class encapsulates a particular state of the Accessible object. Accessible states include things like "Armed", "Busy", "Checked", "Focused", etc. These roles are identified by the constants in this class such as AccessibleState.ARMED, AccessibleState.BUSY, AccessibleState.CHECKED, and AccessibleState.FOCUSED. The sum of all the states of an Accessible object is called the AccessibleStateSet, and can be obtained by calling the getAccessibleStateSet method on an AccessibleContext.

The constants in this class present a strongly typed enumeration of common
object roles. A public constructor for this class has been purposely omitted
and applications should use one of the constants from this class. Although
this class pre-defines a large list of standard roles, it is extensible so
additional, programmer-defined roles can be added in the future without
needing to modify the base class.
Class
AccessibleStateSet
 This class encapsulates a collection of states of the Accessible object and is obtained by calling the getAccessibleStateSet method on an AccessibleContext. Since an object might
have multiple states (e.g. it might be both "Checked" and "Focused"), this
class is needed to encapsulate a collection of these states. Methods in the
class provide for retrieving the individual
AccessibleStates on the state set.
Class
AccessibleBundle
This class is used to maintain a strongly typed enumeration. It is the super
class of both the AccessibleRole and
AccessibleState classes. Programmers normally
do not interact with this class directly, but will instead use the
AccessibleRole and
AccessibleState classes.
Interface
AccessibleAction
The AccessibleAction interface should be
supported by any object that can perform one or more actions. This interface
provides the standard mechanism for an assistive technology to determine what
those actions are as well as tell the object to perform those actions. Any
object that can be manipulated should support this interface.

Applications can determine if an object supports the AccessibleAction
interface by first obtaining its
AccessibleContext (see
Accessible) and then calling the getAccessibleAction method of AccessibleContext. If the return value is not null, the object supports this interface. 
 
Interface AccessibleComponent
The AccessibleComponent interface
should be supported by any object that is rendered on the screen. This
interface provides the standard mechanism for an assistive technology to
determine and set the graphical representation of an object. Applications
can determine if an object supports the AccessibleComponent interface by
first obtaining its AccessibleContext (see
Accessible) and then calling the getAccessibleComponent method of AccessibleContext. If the return value is not null, the object supports this interface. 

Interface AccessibleSelection
The AccessibleSelection interface
provides the standard mechanism for an assistive technology to determine what
the current selected children are, as well as modify the selection set. Any
object that has children that can be selected should support this the
AccessibleSelection interface.

Applications can determine if an object supports the AccessibleSelection
interface by first obtaining its
AccessibleContext (see
Accessible) and then calling the getAccessibleSelection method of AccessibleContext. If the return value is not null, the object supports this interface. 
Interface
AccessibleText
Interface AccessibleText is the contract
for making rich, editable text Accessible. Not all text displayed on the
screen is rich and editable (e.g. text contained in buttons, labels, menus,
etc., which users aren't expected to manipulate). However, objects containing
editable text must implement interface AccessibleText if they are to
interoperate with assistive technologies.

This interface provides support for going between pixel coordinates and the
text at a given pixel coordinate, for retrieving the letter, word, and
sentence at, before, or after a given position in the text. This interface
provides support for retrieving the attributes of the character at a given
position in the text (font, font size, style, etc.), as well as getting the
selected text (if any), the length of the text, and the location of the text
caret.

Applications can determine if an object supports the AccessibleText interface
by first obtaining its AccessibleContext
(see Accessible) and then calling the getAccessibleText method of AccessibleContext. If the return value is not null, the object supports this interface. 
 
Interface AccessibleHypertext
The AccessibleHypertext interface
should be supported by any object that presents hypertext information on the
display. This interface provides the standard mechanism for an assistive
technology to access that text via its content, attributes, and spatial
location. It also provides standard mechanisms for manipulating
hyperlinks. Applications can determine if
an object supports the AccessibleHypertext interface by first obtaining its
AccessibleContext (see
Accessible) and then calling the
AccessibleContext.getAccessibleText() method of
AccessibleContext. If the return value is a
class which extends AccessibleHypertext, then that object supports
AccessibleHypertext.

Interface AccessibleHyperlink
An object that is a hyperlink should support the
AccessibleHyperlink interface. 
An object that implements this interface will be returned by calling the
getLink method on an AccessibleHypertext
object.
Interface
AccessibleValue
The AccessibleValue interface should be
supported by any object that supports a numerical value (e.g., a scroll bar).
This interface provides the standard mechanism for an assistive technology to
determine and set the numerical value as well as get the minimum and maximum
values.

Applications can determine if an object supports the AccessibleValue
interface by first obtaining its
AccessibleContext (see
Accessible) and then calling the getAccessibleValue method of AccessibleContext. If the return value is not null, the object supports this interface. 
Since: 1.2/**
 * Defines a contract between user-interface components and an assistive
 * technology that provides access to those components. If a Java application
 * fully supports the Java Accessibility API, then it should be compatible with,
 * and friendly toward, assistive technologies such as screen readers, screen
 * magnifiers, etc. With a Java application that fully supports the Java
 * Accessibility API, no screen reader off screen model would be necessary
 * because the API provides all of the information normally contained in an off
 * screen model.
 * <p>
 * The Java Accessibility API package consists of 8 Java programming language
 * interfaces, and 6 Java programming language classes. These are described
 * below.
 *
 * <h2><a id="Accessible"></a><a href="Accessible.html">Interface
 * Accessible</a></h2>
 * <a href="Accessible.html">Interface Accessible</a> is the main interface of
 * the Java Accessibility API. All components that support the Java
 * Accessibility API must implement this interface. It contains a single method,
 * {@code getAccessibleContext}, that returns an instance of the class
 * <a href="#AccessibleContext">AccessibleContext</a>. Sun thinks that
 * implementing this interface is the absolute minimum requirement of every
 * object that is part of the user interface of a Java application, if that
 * program is to be compatible with assistive technologies.
 *
 * <h2><a id="AccessibleContext"></a><a href="AccessibleContext.html">Class
 * AccessibleContext</a></h2>
 * <a href="AccessibleContext.html">AccessibleContext</a> represents the minimum
 * information all accessible objects return and is obtained by calling the
 * {@code getAccessibleContext} method on an object that implements the
 * <a href="#Accessible">Accessible</a> interface. This information includes the
 * accessible name, description, <a href="#AccessibleRole">role</a>, and
 * <a href="#AccessibleState">state</a> of the object, as well as information
 * about the parent and children of the object.&nbsp; In addition,
 * JavaBeans&trade; property change support is also included to allow assistive
 * technologies learn when the values of the accessible properties change.
 * AccessibleContext also contains methods for obtaining more specific
 * accessibility information about a component. If the component supports it,
 * these methods will return an object that implements one or more of the
 * following interfaces:
 * <ul>
 *     <li><b><a href="#AccessibleAction">AccessibleAction</a></b> - the object
 *     can perform one or more actions. This interface provides the standard
 *     mechanism for an assistive technology to determine what those actions are
 *     and tell the object to perform those actions. Any object that can be
 *     manipulated should return an object that implements this interface when
 *     the {@code getAccessibleAction} method is called on an AccessibleContext.
 *     </li>
 *     <li><b><a href="#AccessibleComponent">AccessibleComponent</a></b> - the
 *     object has a graphical representation. This interface provides the
 *     standard mechanism for an assistive technology to determine and set the
 *     graphical representation of the object. Any object that is rendered on
 *     the screen should return an object that implements this interface when
 *     the {@code getAccessibleComponent} method is called on an
 *     AccessibleContext.</li>
 *     <li><b><a href="#AccessibleSelection">AccessibleSelection</a></b> - the
 *     object allows its children to be selected. This interface provides the
 *     standard mechanism for an assistive technology to determine the currently
 *     selected children as well as modify the selection set. Any object that
 *     has children that can be selected should return an object that implements
 *     this interface when the {@code getAccessibleSelection} method is called
 *     on an AccessibleContext.</li>
 *     <li><b><a href="#AccessibleText">AccessibleText</a></b> - the object
 *     presents editable textual information on the display. This interface
 *     provides the standard mechanism for an assistive technology to access
 *     that text via its content, attributes, and spatial location. Any object
 *     that contains editable text should return an object that implements this
 *     interface when the {@code getAccessibleText} method is called on an
 *     AccessibleContext.</li>
 *     <li><b><a href="#AccessibleHypertext">AccessibleHypertext</a></b> - the
 *     object presents hypertext information on the display. This interface
 *     provides the standard mechanism for an assistive technology to access that
 *     hypertext via its content, attributes, and spatial location. Any object
 *     that contains hypertext should return an object that implements this
 *     interface when the {@code getAccessibleText} method is called on an
 *     AccessibleContext.</li>
 *     <li><b><a href="#AccessibleValue">AccessibleValue</a></b> - the object
 *     supports a numerical value. This interface provides the standard
 *     mechanism for an assistive technology to determine and set the current
 *     value of the object, as well as the minimum and maximum values. Any
 *     object that supports a numerical value should return an object that
 *     implements this interface when the {@code getAccessibleValue} method is
 *     called on an AccessibleContext.</li>
 * </ul>
 *
 * <h2><a id="AccessibleRole"></a><a href="AccessibleRole.html">Class
 * AccessibleRole</a></h2>
 * This class encapsulates the Accessible object's role in the user interface
 * and is obtained by calling the {@code getAccessibleRole} method on an
 * <a href="#AccessibleContext">AccessibleContext</a>. Accessible roles include
 * "Check box", "Menu Item", "Panel", etc. These roles are identified by the
 * constants in this class such as {@code AccessibleRole.CHECK_BOX,
 * AccessibleRole.MENU_ITEM,} and {@code AccessibleRole.PANEL}. The constants in
 * this class present a strongly typed enumeration of common object roles. A
 * public constructor for this class has been purposely omitted and applications
 * should use one of the constants from this class. Although this class
 * pre-defines a large list of standard roles, it is extensible so additional
 * programmer-defined roles can be added in the future without needing to modify
 * the base class.
 *
 * <h2><a id="AccessibleState"></a><a href="AccessibleState.html">Class
 * AccessibleState</a></h2>
 * This class encapsulates a particular state of the Accessible object.
 * Accessible states include things like "Armed", "Busy", "Checked", "Focused",
 * etc. These roles are identified by the constants in this class such as
 * {@code AccessibleState.ARMED, AccessibleState.BUSY, AccessibleState.CHECKED,}
 * and {@code AccessibleState.FOCUSED}. The sum of all the states of an
 * Accessible object is called the
 * <a href="#AccessibleStateSet">AccessibleStateSet</a>, and can be obtained by
 * calling the {@code getAccessibleStateSet} method on an
 * <a href="#AccessibleContext">AccessibleContext</a>.
 * <p>
 * The constants in this class present a strongly typed enumeration of common
 * object roles. A public constructor for this class has been purposely omitted
 * and applications should use one of the constants from this class. Although
 * this class pre-defines a large list of standard roles, it is extensible so
 * additional, programmer-defined roles can be added in the future without
 * needing to modify the base class.
 *
 * <h2><a id="AccessibleStateSet"></a><a href="AccessibleStateSet.html">Class
 * AccessibleStateSet</a></h2>
 * This class encapsulates a collection of states of the Accessible object and
 * is obtained by calling the {@code getAccessibleStateSet} method on an
 * <a href="#AccessibleContext">AccessibleContext</a>. Since an object might
 * have multiple states (e.g. it might be both "Checked" and "Focused"), this
 * class is needed to encapsulate a collection of these states. Methods in the
 * class provide for retrieving the individual
 * <a href="#AccessibleState">AccessibleStates</a> on the state set.
 *
 * <h2><a id="AccessibleBundle"></a><a href="AccessibleBundle.html">Class
 * AccessibleBundle</a></h2>
 * This class is used to maintain a strongly typed enumeration. It is the super
 * class of both the <a href="#AccessibleRole">AccessibleRole</a> and
 * <a href="#AccessibleState">AccessibleState</a> classes. Programmers normally
 * do not interact with this class directly, but will instead use the
 * <a href="#AccessibleRole">AccessibleRole</a> and
 * <a href="#AccessibleState">AccessibleState</a> classes.
 *
 * <h2><a id="AccessibleAction"></a><a href="AccessibleAction.html">Interface
 * AccessibleAction</a></h2>
 * The <a href="AccessibleAction.html">AccessibleAction</a> interface should be
 * supported by any object that can perform one or more actions. This interface
 * provides the standard mechanism for an assistive technology to determine what
 * those actions are as well as tell the object to perform those actions. Any
 * object that can be manipulated should support this interface.
 * <p>
 * Applications can determine if an object supports the AccessibleAction
 * interface by first obtaining its
 * <a href="#AccessibleContext">AccessibleContext</a> (see
 * <a href="#Accessible">Accessible</a>) and then calling the
 * {@code getAccessibleAction} method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 * not {@code null}, the object supports this interface.
 *
 * <h2> <a id="AccessibleComponent"></a><a href="AccessibleComponent.html">
 * Interface AccessibleComponent</a></h2>
 * The <a href="AccessibleComponent.html">AccessibleComponent</a> interface
 * should be supported by any object that is rendered on the screen. This
 * interface provides the standard mechanism for an assistive technology to
 * determine and set the graphical representation of an object. <p>Applications
 * can determine if an object supports the AccessibleComponent interface by
 * first obtaining its <a href="#AccessibleContext">AccessibleContext</a> (see
 * <a href="#Accessible">Accessible</a>) and then calling the
 * {@code getAccessibleComponent} method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 * not {@code null}, the object supports this interface.
 *
 * <h2><a id="AccessibleSelection"></a><a href="AccessibleSelection.html">
 * Interface AccessibleSelection</a></h2>
 * The <a href="AccessibleSelection.html">AccessibleSelection</a> interface
 * provides the standard mechanism for an assistive technology to determine what
 * the current selected children are, as well as modify the selection set. Any
 * object that has children that can be selected should support this the
 * AccessibleSelection interface.
 * <p>
 * Applications can determine if an object supports the AccessibleSelection
 * interface by first obtaining its
 * <a href="#AccessibleContext">AccessibleContext</a> (see
 * <a href="#Accessible">Accessible</a>) and then calling the
 * {@code getAccessibleSelection} method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 * not {@code null}, the object supports this interface.
 *
 * <h2><a id="AccessibleText"></a><a href="AccessibleText.html">Interface
 * AccessibleText</a></h2>
 * Interface <a href="AccessibleText.html">AccessibleText</a> is the contract
 * for making rich, editable text Accessible. Not all text displayed on the
 * screen is rich and editable (e.g. text contained in buttons, labels, menus,
 * etc., which users aren't expected to manipulate). However, objects containing
 * editable text must implement interface AccessibleText if they are to
 * interoperate with assistive technologies.
 * <p>
 * This interface provides support for going between pixel coordinates and the
 * text at a given pixel coordinate, for retrieving the letter, word, and
 * sentence at, before, or after a given position in the text. This interface
 * provides support for retrieving the attributes of the character at a given
 * position in the text (font, font size, style, etc.), as well as getting the
 * selected text (if any), the length of the text, and the location of the text
 * caret.
 * <p>
 * Applications can determine if an object supports the AccessibleText interface
 * by first obtaining its <a href="#AccessibleContext">AccessibleContext</a>
 * (see <a href="#Accessible">Accessible</a>) and then calling the
 * {@code getAccessibleText} method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 * not {@code null}, the object supports this interface.
 *
 * <h2><a id="AccessibleHypertext"></a> <a href="AccessibleHypertext.html">
 * Interface AccessibleHypertext</a></h2>
 * The <a href="AccessibleHypertext.html">AccessibleHypertext</a> interface
 * should be supported by any object that presents hypertext information on the
 * display. This interface provides the standard mechanism for an assistive
 * technology to access that text via its content, attributes, and spatial
 * location. It also provides standard mechanisms for manipulating
 * <a href="#AccessibleHyperlink">hyperlinks</a>. Applications can determine if
 * an object supports the AccessibleHypertext interface by first obtaining its
 * <a href="#AccessibleContext">AccessibleContext</a> (see
 * <a href="#Accessible">Accessible</a>) and then calling the
 * AccessibleContext.getAccessibleText() method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is a
 * class which extends AccessibleHypertext, then that object supports
 * AccessibleHypertext.
 *
 * <h2><a id="AccessibleHyperlink"></a><a href="AccessibleHyperlink.html">
 * Interface AccessibleHyperlink</a></h2>
 * An object that is a hyperlink should support the
 * <a href="AccessibleHyperlink.html">AccessibleHyperlink</a> interface.&nbsp;
 * An object that implements this interface will be returned by calling the
 * getLink method on an <a href="#AccessibleHypertext">AccessibleHypertext</a>
 * object.
 *
 * <h2><a id="AccessibleValue"></a><a href="AccessibleValue.html">Interface
 * AccessibleValue</a></h2>
 * The <a href="AccessibleValue.html">AccessibleValue</a> interface should be
 * supported by any object that supports a numerical value (e.g., a scroll bar).
 * This interface provides the standard mechanism for an assistive technology to
 * determine and set the numerical value as well as get the minimum and maximum
 * values.
 * <p>
 * Applications can determine if an object supports the AccessibleValue
 * interface by first obtaining its
 * <a href="#AccessibleContext">AccessibleContext</a> (see
 * <a href="#Accessible">Accessible</a>) and then calling the
 * {@code getAccessibleValue} method of
 * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 * not {@code null}, the object supports this interface.
 *
 * @since 1.2
 */
package javax.accessibility;