1/*
2 * Copyright (c) 1997, 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
26package javax.accessibility;
27
28/**
29 * Class {@code AccessibleState} describes a component's particular state. The
30 * actual state of the component is defined as an {@code AccessibleStateSet},
31 * which is a composed set of {@code AccessibleStates}.
32 * <p>
33 * The {@link #toDisplayString()} method allows you to obtain the localized
34 * string for a locale independent key from a predefined {@code ResourceBundle}
35 * for the keys defined in this class.
36 * <p>
37 * The constants in this class present a strongly typed enumeration of common
38 * object roles. A public constructor for this class has been purposely omitted
39 * and applications should use one of the constants from this class. If the
40 * constants in this class are not sufficient to describe the role of an object,
41 * a subclass should be generated from this class and it should provide
42 * constants in a similar manner.
43 *
44 * @author Willie Walker
45 * @author Peter Korn
46 */
47public class AccessibleState extends AccessibleBundle {
48
49    // If you add or remove anything from here, make sure you
50    // update AccessibleResourceBundle.java.
51
52    /**
53     * Indicates a window is currently the active window. This includes windows,
54     * dialogs, frames, etc. In addition, this state is used to indicate the
55     * currently active child of a component such as a list, table, or tree. For
56     * example, the active child of a list is the child that is drawn with a
57     * rectangle around it.
58     *
59     * @see AccessibleRole#WINDOW
60     * @see AccessibleRole#FRAME
61     * @see AccessibleRole#DIALOG
62     */
63    public static final AccessibleState ACTIVE
64            = new AccessibleState("active");
65
66    /**
67     * Indicates this object is currently pressed. This is usually associated
68     * with buttons and indicates the user has pressed a mouse button while the
69     * pointer was over the button and has not yet released the mouse button.
70     *
71     * @see AccessibleRole#PUSH_BUTTON
72     */
73    public static final AccessibleState PRESSED
74            = new AccessibleState("pressed");
75
76    /**
77     * Indicates that the object is armed. This is usually used on buttons that
78     * have been pressed but not yet released, and the mouse pointer is still
79     * over the button.
80     *
81     * @see AccessibleRole#PUSH_BUTTON
82     */
83    public static final AccessibleState ARMED
84            = new AccessibleState("armed");
85
86    /**
87     * Indicates the current object is busy. This is usually used on objects
88     * such as progress bars, sliders, or scroll bars to indicate they are in a
89     * state of transition.
90     *
91     * @see AccessibleRole#PROGRESS_BAR
92     * @see AccessibleRole#SCROLL_BAR
93     * @see AccessibleRole#SLIDER
94     */
95    public static final AccessibleState BUSY
96            = new AccessibleState("busy");
97
98    /**
99     * Indicates this object is currently checked. This is usually used on
100     * objects such as toggle buttons, radio buttons, and check boxes.
101     *
102     * @see AccessibleRole#TOGGLE_BUTTON
103     * @see AccessibleRole#RADIO_BUTTON
104     * @see AccessibleRole#CHECK_BOX
105     */
106    public static final AccessibleState CHECKED
107            = new AccessibleState("checked");
108
109    /**
110     * Indicates the user can change the contents of this object. This is
111     * usually used primarily for objects that allow the user to enter text.
112     * Other objects, such as scroll bars and sliders, are automatically
113     * editable if they are enabled.
114     *
115     * @see #ENABLED
116     */
117    public static final AccessibleState EDITABLE
118            = new AccessibleState("editable");
119
120    /**
121     * Indicates this object allows progressive disclosure of its children. This
122     * is usually used with hierarchical objects such as trees and is often
123     * paired with the {@code EXPANDED} or {@code COLLAPSED} states.
124     *
125     * @see #EXPANDED
126     * @see #COLLAPSED
127     * @see AccessibleRole#TREE
128     */
129    public static final AccessibleState EXPANDABLE
130            = new AccessibleState("expandable");
131
132    /**
133     * Indicates this object is collapsed. This is usually paired with the
134     * {@code EXPANDABLE} state and is used on objects that provide progressive
135     * disclosure such as trees.
136     *
137     * @see #EXPANDABLE
138     * @see #EXPANDED
139     * @see AccessibleRole#TREE
140     */
141    public static final AccessibleState COLLAPSED
142            = new AccessibleState("collapsed");
143
144    /**
145     * Indicates this object is expanded. This is usually paired with the
146     * {@code EXPANDABLE} state and is used on objects that provide progressive
147     * disclosure such as trees.
148     *
149     * @see #EXPANDABLE
150     * @see #COLLAPSED
151     * @see AccessibleRole#TREE
152     */
153    public static final AccessibleState EXPANDED
154            = new AccessibleState("expanded");
155
156    /**
157     * Indicates this object is enabled. The absence of this state from an
158     * object's state set indicates this object is not enabled. An object that
159     * is not enabled cannot be manipulated by the user. In a graphical display,
160     * it is usually grayed out.
161     */
162    public static final AccessibleState ENABLED
163            = new AccessibleState("enabled");
164
165    /**
166     * Indicates this object can accept keyboard focus, which means all events
167     * resulting from typing on the keyboard will normally be passed to it when
168     * it has focus.
169     *
170     * @see #FOCUSED
171     */
172    public static final AccessibleState FOCUSABLE
173            = new AccessibleState("focusable");
174
175    /**
176     * Indicates this object currently has the keyboard focus.
177     *
178     * @see #FOCUSABLE
179     */
180    public static final AccessibleState FOCUSED
181            = new AccessibleState("focused");
182
183    /**
184     * Indicates this object is minimized and is represented only by an icon.
185     * This is usually only associated with frames and internal frames.
186     *
187     * @see AccessibleRole#FRAME
188     * @see AccessibleRole#INTERNAL_FRAME
189     */
190    public static final AccessibleState ICONIFIED
191            = new AccessibleState("iconified");
192
193    /**
194     * Indicates something must be done with this object before the user can
195     * interact with an object in a different window. This is usually associated
196     * only with dialogs.
197     *
198     * @see AccessibleRole#DIALOG
199     */
200    public static final AccessibleState MODAL
201            = new AccessibleState("modal");
202
203    /**
204     * Indicates this object paints every pixel within its rectangular region. A
205     * non-opaque component paints only some of its pixels, allowing the pixels
206     * underneath it to "show through". A component that does not fully paint
207     * its pixels therefore provides a degree of transparency.
208     *
209     * @see Accessible#getAccessibleContext
210     * @see AccessibleContext#getAccessibleComponent
211     * @see AccessibleComponent#getBounds
212     */
213    public static final AccessibleState OPAQUE
214            = new AccessibleState("opaque");
215
216    /**
217     * Indicates the size of this object is not fixed.
218     *
219     * @see Accessible#getAccessibleContext
220     * @see AccessibleContext#getAccessibleComponent
221     * @see AccessibleComponent#getSize
222     * @see AccessibleComponent#setSize
223     */
224    public static final AccessibleState RESIZABLE
225            = new AccessibleState("resizable");
226
227
228    /**
229     * Indicates this object allows more than one of its children to be selected
230     * at the same time.
231     *
232     * @see Accessible#getAccessibleContext
233     * @see AccessibleContext#getAccessibleSelection
234     * @see AccessibleSelection
235     */
236    public static final AccessibleState MULTISELECTABLE
237            = new AccessibleState("multiselectable");
238
239    /**
240     * Indicates this object is the child of an object that allows its children
241     * to be selected, and that this child is one of those children that can be
242     * selected.
243     *
244     * @see #SELECTED
245     * @see Accessible#getAccessibleContext
246     * @see AccessibleContext#getAccessibleSelection
247     * @see AccessibleSelection
248     */
249    public static final AccessibleState SELECTABLE
250            = new AccessibleState("selectable");
251
252    /**
253     * Indicates this object is the child of an object that allows its children
254     * to be selected, and that this child is one of those children that has
255     * been selected.
256     *
257     * @see #SELECTABLE
258     * @see Accessible#getAccessibleContext
259     * @see AccessibleContext#getAccessibleSelection
260     * @see AccessibleSelection
261     */
262    public static final AccessibleState SELECTED
263            = new AccessibleState("selected");
264
265    /**
266     * Indicates this object, the object's parent, the object's parent's parent,
267     * and so on, are all visible. Note that this does not necessarily mean the
268     * object is painted on the screen. It might be occluded by some other
269     * showing object.
270     *
271     * @see #VISIBLE
272     */
273    public static final AccessibleState SHOWING
274            = new AccessibleState("showing");
275
276    /**
277     * Indicates this object is visible. Note: this means that the object
278     * intends to be visible; however, it may not in fact be showing on the
279     * screen because one of the objects that this object is contained by is not
280     * visible.
281     *
282     * @see #SHOWING
283     */
284    public static final AccessibleState VISIBLE
285            = new AccessibleState("visible");
286
287    /**
288     * Indicates the orientation of this object is vertical. This is usually
289     * associated with objects such as scrollbars, sliders, and progress bars.
290     *
291     * @see #VERTICAL
292     * @see AccessibleRole#SCROLL_BAR
293     * @see AccessibleRole#SLIDER
294     * @see AccessibleRole#PROGRESS_BAR
295     */
296    public static final AccessibleState VERTICAL
297            = new AccessibleState("vertical");
298
299    /**
300     * Indicates the orientation of this object is horizontal. This is usually
301     * associated with objects such as scrollbars, sliders, and progress bars.
302     *
303     * @see #HORIZONTAL
304     * @see AccessibleRole#SCROLL_BAR
305     * @see AccessibleRole#SLIDER
306     * @see AccessibleRole#PROGRESS_BAR
307     */
308    public static final AccessibleState HORIZONTAL
309            = new AccessibleState("horizontal");
310
311    /**
312     * Indicates this (text) object can contain only a single line of text.
313     */
314    public static final AccessibleState SINGLE_LINE
315            = new AccessibleState("singleline");
316
317    /**
318     * Indicates this (text) object can contain multiple lines of text.
319     */
320    public static final AccessibleState MULTI_LINE
321            = new AccessibleState("multiline");
322
323    /**
324     * Indicates this object is transient. An assistive technology should not
325     * add a {@code PropertyChange} listener to an object with transient state,
326     * as that object will never generate any events. Transient objects are
327     * typically created to answer Java Accessibility method queries, but
328     * otherwise do not remain linked to the underlying object (for example,
329     * those objects underneath lists, tables, and trees in Swing, where only
330     * one actual {@code UI Component} does shared rendering duty for all of the
331     * data objects underneath the actual list/table/tree elements).
332     *
333     * @since 1.5
334     */
335    public static final AccessibleState TRANSIENT
336            = new AccessibleState("transient");
337
338    /**
339     * Indicates this object is responsible for managing its subcomponents. This
340     * is typically used for trees and tables that have a large number of
341     * subcomponents and where the objects are created only when needed and
342     * otherwise remain virtual. The application should not manage the
343     * subcomponents directly.
344     *
345     * @since 1.5
346     */
347    public static final AccessibleState MANAGES_DESCENDANTS
348            = new AccessibleState ("managesDescendants");
349
350    /**
351     * Indicates that the object state is indeterminate. An example is selected
352     * text that is partially bold and partially not bold. In this case the
353     * attributes associated with the selected text are indeterminate.
354     *
355     * @since 1.5
356     */
357    public static final AccessibleState INDETERMINATE
358           = new AccessibleState ("indeterminate");
359
360    /**
361     * A state indicating that text is truncated by a bounding rectangle and
362     * that some of the text is not displayed on the screen. An example is text
363     * in a spreadsheet cell that is truncated by the bounds of the cell.
364     *
365     * @since 1.5
366     */
367    public static final AccessibleState TRUNCATED
368           =  new AccessibleState("truncated");
369
370    /**
371     * Creates a new {@code AccessibleState} using the given locale independent
372     * key. This should not be a public method. Instead, it is used to create
373     * the constants in this file to make it a strongly typed enumeration.
374     * Subclasses of this class should enforce similar policy.
375     * <p>
376     * The key {@code String} should be a locale independent key for the state.
377     * It is not intended to be used as the actual {@code String} to display to
378     * the user. To get the localized string, use {@link #toDisplayString()}.
379     *
380     * @param  key the locale independent name of the state
381     * @see AccessibleBundle#toDisplayString
382     */
383    protected AccessibleState(String key) {
384        this.key = key;
385    }
386}
387