1 /*
   2  * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /**
  27  * Defines a contract between user-interface components and an assistive
  28  * technology that provides access to those components. If a Java application
  29  * fully supports the Java Accessibility API, then it should be compatible with,
  30  * and friendly toward, assistive technologies such as screen readers, screen
  31  * magnifiers, etc. With a Java application that fully supports the Java
  32  * Accessibility API, no screen reader off screen model would be necessary
  33  * because the API provides all of the information normally contained in an off
  34  * screen model.
  35  * <p>
  36  * The Java Accessibility API package consists of 8 Java programming language
  37  * interfaces, and 6 Java programming language classes. These are described
  38  * below.
  39  *
  40  * <h2><a id="Accessible"></a><a href="Accessible.html">Interface
  41  * Accessible</a></h2>
  42  * <a href="Accessible.html">Interface Accessible</a> is the main interface of
  43  * the Java Accessibility API. All components that support the Java
  44  * Accessibility API must implement this interface. It contains a single method,
  45  * {@code getAccessibleContext}, that returns an instance of the class
  46  * <a href="#AccessibleContext">AccessibleContext</a>. Sun thinks that
  47  * implementing this interface is the absolute minimum requirement of every
  48  * object that is part of the user interface of a Java application, if that
  49  * program is to be compatible with assistive technologies.
  50  *
  51  * <h2><a id="AccessibleContext"></a><a href="AccessibleContext.html">Class
  52  * AccessibleContext</a></h2>
  53  * <a href="AccessibleContext.html">AccessibleContext</a> represents the minimum
  54  * information all accessible objects return and is obtained by calling the
  55  * {@code getAccessibleContext} method on an object that implements the
  56  * <a href="#Accessible">Accessible</a> interface. This information includes the
  57  * accessible name, description, <a href="#AccessibleRole">role</a>, and
  58  * <a href="#AccessibleState">state</a> of the object, as well as information
  59  * about the parent and children of the object.&nbsp; In addition,
  60  * JavaBeans property change support is also included to allow assistive
  61  * technologies learn when the values of the accessible properties change.
  62  * AccessibleContext also contains methods for obtaining more specific
  63  * accessibility information about a component. If the component supports it,
  64  * these methods will return an object that implements one or more of the
  65  * following interfaces:
  66  * <ul>
  67  *     <li><b><a href="#AccessibleAction">AccessibleAction</a></b> - the object
  68  *     can perform one or more actions. This interface provides the standard
  69  *     mechanism for an assistive technology to determine what those actions are
  70  *     and tell the object to perform those actions. Any object that can be
  71  *     manipulated should return an object that implements this interface when
  72  *     the {@code getAccessibleAction} method is called on an AccessibleContext.
  73  *     </li>
  74  *     <li><b><a href="#AccessibleComponent">AccessibleComponent</a></b> - the
  75  *     object has a graphical representation. This interface provides the
  76  *     standard mechanism for an assistive technology to determine and set the
  77  *     graphical representation of the object. Any object that is rendered on
  78  *     the screen should return an object that implements this interface when
  79  *     the {@code getAccessibleComponent} method is called on an
  80  *     AccessibleContext.</li>
  81  *     <li><b><a href="#AccessibleSelection">AccessibleSelection</a></b> - the
  82  *     object allows its children to be selected. This interface provides the
  83  *     standard mechanism for an assistive technology to determine the currently
  84  *     selected children as well as modify the selection set. Any object that
  85  *     has children that can be selected should return an object that implements
  86  *     this interface when the {@code getAccessibleSelection} method is called
  87  *     on an AccessibleContext.</li>
  88  *     <li><b><a href="#AccessibleText">AccessibleText</a></b> - the object
  89  *     presents editable textual information on the display. This interface
  90  *     provides the standard mechanism for an assistive technology to access
  91  *     that text via its content, attributes, and spatial location. Any object
  92  *     that contains editable text should return an object that implements this
  93  *     interface when the {@code getAccessibleText} method is called on an
  94  *     AccessibleContext.</li>
  95  *     <li><b><a href="#AccessibleHypertext">AccessibleHypertext</a></b> - the
  96  *     object presents hypertext information on the display. This interface
  97  *     provides the standard mechanism for an assistive technology to access that
  98  *     hypertext via its content, attributes, and spatial location. Any object
  99  *     that contains hypertext should return an object that implements this
 100  *     interface when the {@code getAccessibleText} method is called on an
 101  *     AccessibleContext.</li>
 102  *     <li><b><a href="#AccessibleValue">AccessibleValue</a></b> - the object
 103  *     supports a numerical value. This interface provides the standard
 104  *     mechanism for an assistive technology to determine and set the current
 105  *     value of the object, as well as the minimum and maximum values. Any
 106  *     object that supports a numerical value should return an object that
 107  *     implements this interface when the {@code getAccessibleValue} method is
 108  *     called on an AccessibleContext.</li>
 109  * </ul>
 110  *
 111  * <h2><a id="AccessibleRole"></a><a href="AccessibleRole.html">Class
 112  * AccessibleRole</a></h2>
 113  * This class encapsulates the Accessible object's role in the user interface
 114  * and is obtained by calling the {@code getAccessibleRole} method on an
 115  * <a href="#AccessibleContext">AccessibleContext</a>. Accessible roles include
 116  * "Check box", "Menu Item", "Panel", etc. These roles are identified by the
 117  * constants in this class such as {@code AccessibleRole.CHECK_BOX,
 118  * AccessibleRole.MENU_ITEM,} and {@code AccessibleRole.PANEL}. The constants in
 119  * this class present a strongly typed enumeration of common object roles. A
 120  * public constructor for this class has been purposely omitted and applications
 121  * should use one of the constants from this class. Although this class
 122  * pre-defines a large list of standard roles, it is extensible so additional
 123  * programmer-defined roles can be added in the future without needing to modify
 124  * the base class.
 125  *
 126  * <h2><a id="AccessibleState"></a><a href="AccessibleState.html">Class
 127  * AccessibleState</a></h2>
 128  * This class encapsulates a particular state of the Accessible object.
 129  * Accessible states include things like "Armed", "Busy", "Checked", "Focused",
 130  * etc. These roles are identified by the constants in this class such as
 131  * {@code AccessibleState.ARMED, AccessibleState.BUSY, AccessibleState.CHECKED,}
 132  * and {@code AccessibleState.FOCUSED}. The sum of all the states of an
 133  * Accessible object is called the
 134  * <a href="#AccessibleStateSet">AccessibleStateSet</a>, and can be obtained by
 135  * calling the {@code getAccessibleStateSet} method on an
 136  * <a href="#AccessibleContext">AccessibleContext</a>.
 137  * <p>
 138  * The constants in this class present a strongly typed enumeration of common
 139  * object roles. A public constructor for this class has been purposely omitted
 140  * and applications should use one of the constants from this class. Although
 141  * this class pre-defines a large list of standard roles, it is extensible so
 142  * additional, programmer-defined roles can be added in the future without
 143  * needing to modify the base class.
 144  *
 145  * <h2><a id="AccessibleStateSet"></a><a href="AccessibleStateSet.html">Class
 146  * AccessibleStateSet</a></h2>
 147  * This class encapsulates a collection of states of the Accessible object and
 148  * is obtained by calling the {@code getAccessibleStateSet} method on an
 149  * <a href="#AccessibleContext">AccessibleContext</a>. Since an object might
 150  * have multiple states (e.g. it might be both "Checked" and "Focused"), this
 151  * class is needed to encapsulate a collection of these states. Methods in the
 152  * class provide for retrieving the individual
 153  * <a href="#AccessibleState">AccessibleStates</a> on the state set.
 154  *
 155  * <h2><a id="AccessibleBundle"></a><a href="AccessibleBundle.html">Class
 156  * AccessibleBundle</a></h2>
 157  * This class is used to maintain a strongly typed enumeration. It is the super
 158  * class of both the <a href="#AccessibleRole">AccessibleRole</a> and
 159  * <a href="#AccessibleState">AccessibleState</a> classes. Programmers normally
 160  * do not interact with this class directly, but will instead use the
 161  * <a href="#AccessibleRole">AccessibleRole</a> and
 162  * <a href="#AccessibleState">AccessibleState</a> classes.
 163  *
 164  * <h2><a id="AccessibleAction"></a><a href="AccessibleAction.html">Interface
 165  * AccessibleAction</a></h2>
 166  * The <a href="AccessibleAction.html">AccessibleAction</a> interface should be
 167  * supported by any object that can perform one or more actions. This interface
 168  * provides the standard mechanism for an assistive technology to determine what
 169  * those actions are as well as tell the object to perform those actions. Any
 170  * object that can be manipulated should support this interface.
 171  * <p>
 172  * Applications can determine if an object supports the AccessibleAction
 173  * interface by first obtaining its
 174  * <a href="#AccessibleContext">AccessibleContext</a> (see
 175  * <a href="#Accessible">Accessible</a>) and then calling the
 176  * {@code getAccessibleAction} method of
 177  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 178  * not {@code null}, the object supports this interface.
 179  *
 180  * <h2> <a id="AccessibleComponent"></a><a href="AccessibleComponent.html">
 181  * Interface AccessibleComponent</a></h2>
 182  * The <a href="AccessibleComponent.html">AccessibleComponent</a> interface
 183  * should be supported by any object that is rendered on the screen. This
 184  * interface provides the standard mechanism for an assistive technology to
 185  * determine and set the graphical representation of an object. <p>Applications
 186  * can determine if an object supports the AccessibleComponent interface by
 187  * first obtaining its <a href="#AccessibleContext">AccessibleContext</a> (see
 188  * <a href="#Accessible">Accessible</a>) and then calling the
 189  * {@code getAccessibleComponent} method of
 190  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 191  * not {@code null}, the object supports this interface.
 192  *
 193  * <h2><a id="AccessibleSelection"></a><a href="AccessibleSelection.html">
 194  * Interface AccessibleSelection</a></h2>
 195  * The <a href="AccessibleSelection.html">AccessibleSelection</a> interface
 196  * provides the standard mechanism for an assistive technology to determine what
 197  * the current selected children are, as well as modify the selection set. Any
 198  * object that has children that can be selected should support this the
 199  * AccessibleSelection interface.
 200  * <p>
 201  * Applications can determine if an object supports the AccessibleSelection
 202  * interface by first obtaining its
 203  * <a href="#AccessibleContext">AccessibleContext</a> (see
 204  * <a href="#Accessible">Accessible</a>) and then calling the
 205  * {@code getAccessibleSelection} method of
 206  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 207  * not {@code null}, the object supports this interface.
 208  *
 209  * <h2><a id="AccessibleText"></a><a href="AccessibleText.html">Interface
 210  * AccessibleText</a></h2>
 211  * Interface <a href="AccessibleText.html">AccessibleText</a> is the contract
 212  * for making rich, editable text Accessible. Not all text displayed on the
 213  * screen is rich and editable (e.g. text contained in buttons, labels, menus,
 214  * etc., which users aren't expected to manipulate). However, objects containing
 215  * editable text must implement interface AccessibleText if they are to
 216  * interoperate with assistive technologies.
 217  * <p>
 218  * This interface provides support for going between pixel coordinates and the
 219  * text at a given pixel coordinate, for retrieving the letter, word, and
 220  * sentence at, before, or after a given position in the text. This interface
 221  * provides support for retrieving the attributes of the character at a given
 222  * position in the text (font, font size, style, etc.), as well as getting the
 223  * selected text (if any), the length of the text, and the location of the text
 224  * caret.
 225  * <p>
 226  * Applications can determine if an object supports the AccessibleText interface
 227  * by first obtaining its <a href="#AccessibleContext">AccessibleContext</a>
 228  * (see <a href="#Accessible">Accessible</a>) and then calling the
 229  * {@code getAccessibleText} method of
 230  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 231  * not {@code null}, the object supports this interface.
 232  *
 233  * <h2><a id="AccessibleHypertext"></a> <a href="AccessibleHypertext.html">
 234  * Interface AccessibleHypertext</a></h2>
 235  * The <a href="AccessibleHypertext.html">AccessibleHypertext</a> interface
 236  * should be supported by any object that presents hypertext information on the
 237  * display. This interface provides the standard mechanism for an assistive
 238  * technology to access that text via its content, attributes, and spatial
 239  * location. It also provides standard mechanisms for manipulating
 240  * <a href="#AccessibleHyperlink">hyperlinks</a>. Applications can determine if
 241  * an object supports the AccessibleHypertext interface by first obtaining its
 242  * <a href="#AccessibleContext">AccessibleContext</a> (see
 243  * <a href="#Accessible">Accessible</a>) and then calling the
 244  * AccessibleContext.getAccessibleText() method of
 245  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is a
 246  * class which extends AccessibleHypertext, then that object supports
 247  * AccessibleHypertext.
 248  *
 249  * <h2><a id="AccessibleHyperlink"></a><a href="AccessibleHyperlink.html">
 250  * Interface AccessibleHyperlink</a></h2>
 251  * An object that is a hyperlink should support the
 252  * <a href="AccessibleHyperlink.html">AccessibleHyperlink</a> interface.&nbsp;
 253  * An object that implements this interface will be returned by calling the
 254  * getLink method on an <a href="#AccessibleHypertext">AccessibleHypertext</a>
 255  * object.
 256  *
 257  * <h2><a id="AccessibleValue"></a><a href="AccessibleValue.html">Interface
 258  * AccessibleValue</a></h2>
 259  * The <a href="AccessibleValue.html">AccessibleValue</a> interface should be
 260  * supported by any object that supports a numerical value (e.g., a scroll bar).
 261  * This interface provides the standard mechanism for an assistive technology to
 262  * determine and set the numerical value as well as get the minimum and maximum
 263  * values.
 264  * <p>
 265  * Applications can determine if an object supports the AccessibleValue
 266  * interface by first obtaining its
 267  * <a href="#AccessibleContext">AccessibleContext</a> (see
 268  * <a href="#Accessible">Accessible</a>) and then calling the
 269  * {@code getAccessibleValue} method of
 270  * <a href="#AccessibleContext">AccessibleContext</a>. If the return value is
 271  * not {@code null}, the object supports this interface.
 272  *
 273  * @since 1.2
 274  */
 275 package javax.accessibility;