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 * <h3><a id="Accessible"></a><a href="Accessible.html">Interface 41 * Accessible</a></h3> 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 * <h3><a id="AccessibleContext"></a><a href="AccessibleContext.html">Class 52 * AccessibleContext</a></h3> 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. 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 * <h3><a id="AccessibleRole"></a><a href="AccessibleRole.html">Class 112 * AccessibleRole</a></h3> 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 * <h3><a id="AccessibleState"></a><a href="AccessibleState.html">Class 127 * AccessibleState</a></h3> 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 * <h3><a id="AccessibleStateSet"></a><a href="AccessibleStateSet.html">Class 146 * AccessibleStateSet</a></h3> 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 * <h3><a id="AccessibleBundle"></a><a href="AccessibleBundle.html">Class 156 * AccessibleBundle</a></h3> 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 * <h3><a id="AccessibleAction"></a><a href="AccessibleAction.html">Interface 165 * AccessibleAction</a></h3> 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 * <h3> <a id="AccessibleComponent"></a><a href="AccessibleComponent.html"> 181 * Interface AccessibleComponent</a></h3> 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 * <h3><a id="AccessibleSelection"></a><a href="AccessibleSelection.html"> 194 * Interface AccessibleSelection</a></h3> 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 * <h3><a id="AccessibleText"></a><a href="AccessibleText.html">Interface 210 * AccessibleText</a></h3> 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 * <h3><a id="AccessibleHypertext"></a> <a href="AccessibleHypertext.html"> 234 * Interface AccessibleHypertext</a></h3> 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 * <h3><a id="AccessibleHyperlink"></a><a href="AccessibleHyperlink.html"> 250 * Interface AccessibleHyperlink</a></h3> 251 * An object that is a hyperlink should support the 252 * <a href="AccessibleHyperlink.html">AccessibleHyperlink</a> interface. 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 * <h3><a id="AccessibleValue"></a><a href="AccessibleValue.html">Interface 258 * AccessibleValue</a></h3> 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 */ 275package javax.accessibility; 276