1 /* AccessibleContext.java -- the context of an accessible object
2    Copyright (C) 2002 Free Software Foundation
3 
4 This file is part of GNU Classpath.
5 
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10 
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15 
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20 
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25 
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module.  An independent module is a module which is not derived from
33 or based on this library.  If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so.  If you do not wish to do so, delete this
36 exception statement from your version. */
37 
38 package javax.accessibility;
39 
40 import java.beans.PropertyChangeListener;
41 import java.beans.PropertyChangeSupport;
42 import java.util.Locale;
43 
44 /**
45  * The minimum information that all accessible objects return. This includes
46  * name, description, role, and state of the object, parents and children,
47  * and any other useful information. If a component supports further details,
48  * it should implement one of the following:<ul>
49  * <li>{@link AccessibleAction} - the object can perform actions</li>
50  * <li>{@link AccessibleComponent} - the object has a graphical
51  *     representation</li>
52  * <li>{@link AccessibleSelection} - the object allows its children to be
53  *     selected</li>
54  * <li>{@link AccessibleText} - the object represents editable text</li>
55  * <li>{@link AccessibleValue} - the object represents a numerical value</li>
56  * </ul>
57  *
58  * @author Eric Blake (ebb9@email.byu.edu)
59  * @since 1.2
60  * @status updated to 1.4
61  */
62 public abstract class AccessibleContext
63 {
64   /**
65    * Constant used when the accessible name has changed. Both the old and new
66    * values are listed in the event.
67    *
68    * @see #getAccessibleName()
69    * @see #addPropertyChangeListener(PropertyChangeListener)
70    */
71   public static final String ACCESSIBLE_NAME_PROPERTY
72     = "AccessibleName";
73 
74   /**
75    * Constant used when the accessible description has changed. Both the old
76    * and new values are listed in the event.
77    *
78    * @see #getAccessibleDescription()
79    * @see #addPropertyChangeListener(PropertyChangeListener)
80    */
81   public static final String ACCESSIBLE_DESCRIPTION_PROPERTY
82     = "AccessibleDescription";
83 
84   /**
85    * Constant used when the accessibleStateSet has changed. Both the old and
86    * new values are listed in the event, although either may be null if a
87    * state was disabled at that time.
88    *
89    * @see #getAccessibleStateSet()
90    * @see AccessibleState
91    * @see AccessibleStateSet
92    * @see #addPropertyChangeListener(PropertyChangeListener)
93    */
94   public static final String ACCESSIBLE_STATE_PROPERTY
95     = "AccessibleState";
96 
97   /**
98    * Constant used when the accessibleValue has changed. Both the old and new
99    * values are listed in the event.
100    *
101    * @see #getAccessibleValue()
102    * @see #addPropertyChangeListener(PropertyChangeListener)
103    */
104   public static final String ACCESSIBLE_VALUE_PROPERTY
105     = "AccessibleValue";
106 
107   /**
108    * Constant used when the accessibleSelection has changed. Both the old and
109    * new values of the event are reserved for future use.
110    *
111    * @see #getAccessibleSelection()
112    * @see #addPropertyChangeListener(PropertyChangeListener)
113    */
114   public static final String ACCESSIBLE_SELECTION_PROPERTY
115     = "AccessibleSelection";
116 
117   /**
118    * Constant used when the accessibleText has changed. Both the old and new
119    * values of the event are reserved for future use.
120    *
121    * @see #getAccessibleText()
122    * @see #addPropertyChangeListener(PropertyChangeListener)
123    */
124   public static final String ACCESSIBLE_TEXT_PROPERTY
125     = "AccessibleText";
126 
127   /**
128    * Constant used when the accessibleText caret has changed. Both the old and
129    * new values are listed in the event.
130    *
131    * @see #addPropertyChangeListener(PropertyChangeListener)
132    */
133   public static final String ACCESSIBLE_CARET_PROPERTY
134     = "AccessibleCaret";
135 
136   /**
137    * Constant used when the visible data has changed. Both the old and new
138    * values of the event are reserved for future use.
139    *
140    * @see #addPropertyChangeListener(PropertyChangeListener)
141    */
142   public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY
143     = "AccessibleVisibleData";
144 
145   /**
146    * Constant used when children are added or removed. On addition, the new
147    * value of the event holds the new child; on removal, the old value holds
148    * the removed child.
149    *
150    * @see #addPropertyChangeListener(PropertyChangeListener)
151    */
152   public static final String ACCESSIBLE_CHILD_PROPERTY
153     = "AccessibleChild";
154 
155   /**
156    * Constant used when active descendent of a component has changed. Both
157    * the old and new values are listed in the event.
158    *
159    * @see #addPropertyChangeListener(PropertyChangeListener)
160    */
161   public static final String ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY
162     = "AccessibleActiveDescendant";
163 
164   /**
165    * Constant used when the accessible table caption has changed. Both the
166    * old and new values are listed in the event.
167    *
168    * @see Accessible
169    * @see AccessibleTable
170    */
171   public static final String ACCESSIBLE_TABLE_CAPTION_CHANGED
172     = "accessibleTableCaptionChanged";
173 
174   /**
175    * Constant used when the accessible table summary has changed. Both the
176    * old and new values are listed in the event.
177    *
178    * @see Accessible
179    * @see AccessibleTable
180    */
181   public static final String ACCESSIBLE_TABLE_SUMMARY_CHANGED
182     = "accessibleTableSummaryChanged";
183 
184   /**
185    * Constant used when the accessible table model has changed. Only the new
186    * value of the event has meaning.
187    *
188    * @see AccessibleTable
189    * @see AccessibleTableModelChange
190    */
191   public static final String ACCESSIBLE_TABLE_MODEL_CHANGED
192     = "accessibleTableModelChanged";
193 
194   /**
195    * Constant used when the accessible table row header has changed. Only the
196    * new value of the event has meaning.
197    *
198    * @see AccessibleTable
199    * @see AccessibleTableModelChange
200    */
201   public static final String ACCESSIBLE_TABLE_ROW_HEADER_CHANGED
202     = "accessibleTableRowHeaderChanged";
203 
204   /**
205    * Constant used when the accessible table row description has changed. Only
206    * the new value of the event has meaning.
207    *
208    * @see AccessibleTable
209    */
210   public static final String ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED
211     = "accessibleTableRowDescriptionChanged";
212 
213   /**
214    * Constant used when the accessible table column header has changed. Only
215    * the new value of the event has meaning.
216    *
217    * @see AccessibleTable
218    * @see AccessibleTableModelChange
219    */
220   public static final String ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED
221     = "accessibleTableColumnHeaderChanged";
222 
223   /**
224    * Constant used when the accessible table column description has changed.
225    * Only the new value of the event has meaning.
226    *
227    * @see AccessibleTable
228    */
229   public static final String ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED
230     = "accessibleTableColumnDescriptionChanged";
231 
232   /**
233    * Constant used when supported set of actions has changed. Both the old
234    * and new values are listed in the event.
235    *
236    * @see AccessibleAction
237    */
238   public static final String ACCESSIBLE_ACTION_PROPERTY
239     = "accessibleActionProperty";
240 
241   /**
242    * Constant used when a hypertext element received focus. Both the old
243    * and new values are listed in the event, with -1 indicating that no link
244    * had focus.
245    *
246    * @see AccessibleHyperlink
247    */
248   public static final String ACCESSIBLE_HYPERTEXT_OFFSET
249     = "AccessibleHypertextOffset";
250 
251   /**
252    * Constant used when a component's bounds have changed.  The old and
253    * new bounds are given in the event.
254    * @since 1.5
255    */
256   public static final String ACCESSIBLE_COMPONENT_BOUNDS_CHANGED
257     = "accessibleComponentBoundsChanged";
258 
259   /**
260    * Constant used when the state of child objects changes.  The old
261    * value in the event is always null, and the new value is the component
262    * whose children have changed.
263    * @since 1.5
264    */
265   public static final String ACCESSIBLE_INVALIDATE_CHILDREN
266     = "accessibleInvalidateChildren";
267 
268   /**
269    * Constant used when the attributes of some text have changed.
270    * On insertion, the old value is null and the new value is an
271    * {@link AccessibleAttributeSequence} describing the insertion.
272    * On deletion, the old value is an {@link AccessibleAttributeSequence}
273    * and the new value is null.  For replacement, both the old
274    * and new values are {@link AccessibleAttributeSequence} objects.
275    * @since 1.5
276    */
277   public static final String ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED
278     = "accessibleTextAttributesChanged";
279 
280   /**
281    * The accessible parent of this object.
282    *
283    * @see #getAccessibleParent()
284    * @see #setAccessibleParent(Accessible)
285    */
286   protected Accessible accessibleParent;
287 
288   /**
289    * A localized string naming this object.
290    *
291    * @see #getAccessibleName()
292    * @see #setAccessibleName(String)
293    */
294   protected String accessibleName;
295 
296   /**
297    * A localized string describing this object.
298    *
299    * @see #getAccessibleDescription()
300    * @see #setAccessibleDescription(String)
301    */
302   protected String accessibleDescription;
303 
304   /**
305    * The listener tool.
306    *
307    * @see #addPropertyChangeListener(PropertyChangeListener)
308    * @see #removePropertyChangeListener(PropertyChangeListener)
309    * @see #firePropertyChange(String, Object, Object)
310    */
311   private final PropertyChangeSupport listeners
312     = new PropertyChangeSupport(this);
313 
314   /**
315    * Default constructor.
316    */
AccessibleContext()317   public AccessibleContext()
318   {
319   }
320 
321   /**
322    * Get the localized name of the object. For example, a label may just
323    * return the text of the label, while an entry field for city may return
324    * "city" in en_US.
325    *
326    * @return the accessible object's name, or null if it is unnamed
327    * @see #setAccessibleName(String)
328    */
getAccessibleName()329   public String getAccessibleName()
330   {
331     return accessibleName;
332   }
333 
334   /**
335    * Set the localized name of the object. This will fire a
336    * PropertyChangeEvent with ACCESSIBLE_NAME_PROPERTY.
337    *
338    * @param s the new name
339    * @see #getAccessibleName()
340    * @see #addPropertyChangeListener(PropertyChangeListener)
341    */
setAccessibleName(String s)342   public void setAccessibleName(String s)
343   {
344     listeners.firePropertyChange(ACCESSIBLE_NAME_PROPERTY, accessibleName, s);
345     accessibleName = s;
346   }
347 
348   /**
349    * Get the localized description of the object. For example, a 'Cancel'
350    * button may be described as "Ignore changes and close dialog box" in
351    * en_US.
352    *
353    * @return the accessible object's description, or null if there is none
354    * @see #setAccessibleDescription(String)
355    */
getAccessibleDescription()356   public String getAccessibleDescription()
357   {
358     return accessibleDescription;
359   }
360 
361   /**
362    * Set the localized name of the object. This will fire a
363    * PropertyChangeEvent with ACCESSIBLE_DESCRIPTION_PROPERTY.
364    *
365    * @param s the new description
366    * @see #getAccessibleDescription()
367    * @see #addPropertyChangeListener(PropertyChangeListener)
368    */
setAccessibleDescription(String s)369   public void setAccessibleDescription(String s)
370   {
371     listeners.firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
372                                  accessibleDescription, s);
373     accessibleDescription = s;
374   }
375 
376   /**
377    * Gets the role of this object. For example, a button serves the role of
378    * AccessibleRole.PUSH_BUTTON. This allows assistive technologies to funnel
379    * similar objects into the same assistance classes. Note that the class
380    * is extensible, to define new roles if necessary.
381    *
382    * @return the role of the object
383    * @see AccessibleRole
384    */
getAccessibleRole()385   public abstract AccessibleRole getAccessibleRole();
386 
387   /**
388    * Gets the state set of this object. A change in the state of the object
389    * will fire a PropertyChangeEvent for ACCESSIBLE_STATE_PROPERTY.
390    *
391    * @return the current state of the object
392    * @see AccessibleState
393    * @see AccessibleStateSet
394    * @see #addPropertyChangeListener(PropertyChangeListener)
395    */
getAccessibleStateSet()396   public abstract AccessibleStateSet getAccessibleStateSet();
397 
398   /**
399    * Return the accessible parent of this object.
400    *
401    * @return the accessible parent, or null if there is none
402    */
getAccessibleParent()403   public Accessible getAccessibleParent()
404   {
405     return accessibleParent;
406   }
407 
408   /**
409    * Sets the accessible parent of this object. This should only be used when
410    * the current parent object should not be the accessible parent; only the
411    * parent of the accessible child should call this method.
412    *
413    * @param a the new parent
414    */
setAccessibleParent(Accessible a)415   public void setAccessibleParent(Accessible a)
416   {
417     accessibleParent = a;
418   }
419 
420   /**
421    * Gets the index of this object within its accessible parent.
422    *
423    * @return the 0-based index, or -1 if there is no accessible parent
424    * @see #getAccessibleParent()
425    * @see #getAccessibleChildrenCount()
426    * @see #getAccessibleChild(int)
427    */
getAccessibleIndexInParent()428   public abstract int getAccessibleIndexInParent();
429 
430   /**
431    * Returns the number of accessible children of this object.
432    *
433    * @return the number of accessible children
434    * @see #getAccessibleChild(int)
435    */
getAccessibleChildrenCount()436   public abstract int getAccessibleChildrenCount();
437 
438   /**
439    * Returns the specified accessible chile.
440    *
441    * @param i the 0-based index to get
442    * @return the child, or null if out of bounds
443    * @see #getAccessibleChildrenCount()
444    */
getAccessibleChild(int i)445   public abstract Accessible getAccessibleChild(int i);
446 
447   /**
448    * Gets the component locale, deferring to the parent if one is not declared.
449    *
450    * @return the locale
451    * @throws java.awt.IllegalComponentStateException if there is no locale
452    *         or parent
453    */
getLocale()454   public abstract Locale getLocale();
455 
456   /**
457    * Add a PropertyChangeListener to the listener list. This listener will
458    * be notified of all property changes to the accessible object.
459    *
460    * @param l the listener to add
461    * @see #ACCESSIBLE_NAME_PROPERTY
462    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
463    * @see #ACCESSIBLE_STATE_PROPERTY
464    * @see #ACCESSIBLE_VALUE_PROPERTY
465    * @see #ACCESSIBLE_SELECTION_PROPERTY
466    * @see #ACCESSIBLE_TEXT_PROPERTY
467    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
468    * @see #removePropertyChangeListener(PropertyChangeListener)
469    */
addPropertyChangeListener(PropertyChangeListener l)470   public void addPropertyChangeListener(PropertyChangeListener l)
471   {
472     listeners.addPropertyChangeListener(l);
473   }
474 
475   /**
476    * Remove a PropertyChangeListener from the listener list.
477    *
478    * @param l the listener to remove
479    * @see #addPropertyChangeListener(PropertyChangeListener)
480    */
removePropertyChangeListener(PropertyChangeListener l)481   public void removePropertyChangeListener(PropertyChangeListener l)
482   {
483     listeners.removePropertyChangeListener(l);
484   }
485 
486   /**
487    * Get any supported accessible actions. The default implementation returns
488    * null.
489    *
490    * @return the supported action, or null
491    * @see AccessibleAction
492    */
getAccessibleAction()493   public AccessibleAction getAccessibleAction()
494   {
495     return null;
496   }
497 
498   /**
499    * Get any supported accessible component. The default implementation returns
500    * null.
501    *
502    * @return the supported component, or null
503    * @see AccessibleComponent
504    */
getAccessibleComponent()505   public AccessibleComponent getAccessibleComponent()
506   {
507     return null;
508   }
509 
510   /**
511    * Get any supported accessible selection. The default implementation returns
512    * null.
513    *
514    * @return the supported selection, or null
515    * @see AccessibleSelection
516    */
getAccessibleSelection()517   public AccessibleSelection getAccessibleSelection()
518   {
519     return null;
520   }
521 
522   /**
523    * Get any supported accessible text. The default implementation returns
524    * null.
525    *
526    * @return the supported text, or null
527    * @see AccessibleText
528    */
getAccessibleText()529   public AccessibleText getAccessibleText()
530   {
531     return null;
532   }
533 
534   /**
535    * Get any supported accessible editable text. The default implementation
536    * returns null.
537    *
538    * @return the supported editable text, or null
539    * @see AccessibleEditableText
540    */
getAccessibleEditableText()541   public AccessibleEditableText getAccessibleEditableText()
542   {
543     return null;
544   }
545 
546   /**
547    * Get any supported accessible value. The default implementation returns
548    * null.
549    *
550    * @return the supported value, or null
551    * @see AccessibleValue
552    */
getAccessibleValue()553   public AccessibleValue getAccessibleValue()
554   {
555     return null;
556   }
557 
558   /**
559    * Get all supported accessible icons. The default implementation returns
560    * null.
561    *
562    * @return the supported icons, or null
563    * @see AccessibleIcon
564    */
getAccessibleIcon()565   public AccessibleIcon[] getAccessibleIcon()
566   {
567     return null;
568   }
569 
570   /**
571    * Get any supported accessible relation set. The default implementation
572    * returns an empty AccessibleRelationSet.
573    *
574    * @return the supported relation set, or <code>null</code>
575    *
576    * @see AccessibleRelationSet
577    */
getAccessibleRelationSet()578   public AccessibleRelationSet getAccessibleRelationSet()
579   {
580     return new AccessibleRelationSet();
581   }
582 
583   /**
584    * Get any supported accessible table. The default implementation returns
585    * null.
586    *
587    * @return the supported table, or null
588    * @see AccessibleTable
589    */
getAccessibleTable()590   public AccessibleTable getAccessibleTable()
591   {
592     return null;
593   }
594 
595   /**
596    * Fire an event to report property changes. This is intended for use by
597    * the accessible objects, not general application programs. If oldValue and
598    * newValue differ, and the listenter list is not empty, a PropertyChange
599    * event is fired to each listener.
600    *
601    * @param name the property name
602    * @param oldValue the prior value
603    * @param newValue the updated value
604    * @see PropertyChangeSupport
605    * @see #addPropertyChangeListener(PropertyChangeListener)
606    * @see #removePropertyChangeListener(PropertyChangeListener)
607    * @see #ACCESSIBLE_NAME_PROPERTY
608    * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
609    * @see #ACCESSIBLE_STATE_PROPERTY
610    * @see #ACCESSIBLE_VALUE_PROPERTY
611    * @see #ACCESSIBLE_SELECTION_PROPERTY
612    * @see #ACCESSIBLE_TEXT_PROPERTY
613    * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
614    */
firePropertyChange(String name, Object oldValue, Object newValue)615   public void firePropertyChange(String name, Object oldValue, Object newValue)
616   {
617     listeners.firePropertyChange(name, oldValue, newValue);
618   }
619 } // class AccessibleContext
620