/[classpath]/classpath/javax/accessibility/AccessibleContext.java
ViewVC logotype

Diff of /classpath/javax/accessibility/AccessibleContext.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by cbj, Tue Nov 21 04:23:25 2000 UTC revision 1.2 by ericb, Mon Mar 18 22:22:45 2002 UTC
# Line 0  Line 1 
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., 59 Temple Place, Suite 330, Boston, MA
19    02111-1307 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       * Constanat 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       * The accessible parent of this object.
253       *
254       * @see #getAccessibleParent()
255       * @see #setAccessibleParent(Accessible)
256       */
257      protected Accessible accessibleParent;
258    
259      /**
260       * A localized string naming this object.
261       *
262       * @see #getAccessibleName()
263       * @see #setAccessibleName(String)
264       */
265      protected String accessibleName;
266    
267      /**
268       * A localized string describing this object.
269       *
270       * @see #getAccessibleDescription()
271       * @see #setAccessibleDescription(String)
272       */
273      protected String accessibleDescription;
274    
275      /**
276       * The listener tool.
277       *
278       * @see #addPropertyChangeListener(PropertyChangeListener)
279       * @see #removePropertyChangeListener(PropertyChangeListener)
280       * @see #firePropertyChange(String, Object, Object)
281       */
282      private final PropertyChangeSupport listeners
283        = new PropertyChangeSupport(this);
284    
285      /**
286       * Default constructor.
287       */
288      public AccessibleContext()
289      {
290      }
291    
292      /**
293       * Get the localized name of the object. For example, a label may just
294       * return the text of the label, while an entry field for city may return
295       * "city" in en_US.
296       *
297       * @return the accessible object's name, or null if it is unnamed
298       * @see #setAccessibleName(String)
299       */
300      public String getAccessibleName()
301      {
302        return accessibleName;
303      }
304    
305      /**
306       * Set the localized name of the object. This will fire a
307       * PropertyChangeEvent with ACCESSIBLE_NAME_PROPERTY.
308       *
309       * @param s the new name
310       * @see #getAccessibleName()
311       * @see #addPropertyChangeListener(PropertyChangeListener)
312       */
313      public void setAccessibleName(String s)
314      {
315        listeners.firePropertyChange(ACCESSIBLE_NAME_PROPERTY, accessibleName, s);
316        accessibleName = s;
317      }
318    
319      /**
320       * Get the localized description of the object. For example, a 'Cancel'
321       * button may be described as "Ignore changes and close dialog box" in
322       * en_US.
323       *
324       * @return the accessible object's description, or null if there is none
325       * @see #setAccessibleDescription(String)
326       */
327      public String getAccessibleDescription()
328      {
329        return accessibleDescription;
330      }
331    
332      /**
333       * Set the localized name of the object. This will fire a
334       * PropertyChangeEvent with ACCESSIBLE_DESCRIPTION_PROPERTY.
335       *
336       * @param s the new description
337       * @see #getAccessibleDescription()
338       * @see #addPropertyChangeListener(PropertyChangeListener)
339       */
340      public void setAccessibleDescription(String s)
341      {
342        listeners.firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
343                                     accessibleDescription, s);
344        accessibleDescription = s;
345      }
346    
347      /**
348       * Gets the role of this object. For example, a button serves the role of
349       * AccessibleRole.PUSH_BUTTON. This allows assistive technologies to funnel
350       * similar objects into the same assistance classes. Note that the class
351       * is extensible, to define new roles if necessary.
352       *
353       * @return the role of the object
354       * @see AccessibleRole
355       */
356      public abstract AccessibleRole getAccessibleRole();
357    
358      /**
359       * Gets the state set of this object. A change in the state of the object
360       * will fire a PropertyChangeEvent for ACCESSIBLE_STATE_PROPERTY.
361       *
362       * @return the current state of the object
363       * @see AccessibleState
364       * @see AccessibleStateSet
365       * @see #addPropertyChangeListener(PropertyChangeListener)
366       */
367      public abstract AccessibleStateSet getAccessibleStateSet();
368    
369      /**
370       * Return the accessible parent of this object.
371       *
372       * @return the accessible parent, or null if there is none
373       */
374      public Accessible getAccessibleParent()
375      {
376        return accessibleParent;
377      }
378    
379      /**
380       * Sets the accessible parent of this object. This should only be used when
381       * the current parent object should not be the accessible parent; only the
382       * parent of the accessible child should call this method.
383       *
384       * @param a the new parent
385       */
386      public void setAccessibleParent(Accessible a)
387      {
388        accessibleParent = a;
389      }
390    
391      /**
392       * Gets the index of this object within its accessible parent.
393       *
394       * @return the 0-based index, or -1 if there is no accessible parent
395       * @see #getAccessibleParent()
396       * @see #getAccessibleChildrenCount()
397       * @see #getAccessibleChild(int)
398       */
399      public abstract int getAccessibleIndexInParent();
400    
401      /**
402       * Returns the number of accessible children of this object.
403       *
404       * @return the number of accessible children
405       * @see #getAccessibleChild(int)
406       */
407      public abstract int getAccessibleChildrenCount();
408    
409      /**
410       * Returns the specified accessible chile.
411       *
412       * @param i the 0-based index to get
413       * @return the child, or null if out of bounds
414       * @see #getAccessibleChildrenCount()
415       */
416      public abstract Accessible getAccessibleChild(int i);
417    
418      /**
419       * Gets the component locale, deferring to the parent if one is not declared.
420       *
421       * @return the locale
422       * @throws IllegalComponentStateException if there is no locale or parent
423       */
424      public abstract Locale getLocale();
425    
426      /**
427       * Add a PropertyChangeListener to the listener list. This listener will
428       * be notified of all property changes to the accessible object.
429       *
430       * @param l the listener to add
431       * @see #ACCESSIBLE_NAME_PROPERTY
432       * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
433       * @see #ACCESSIBLE_STATE_PROPERTY
434       * @see #ACCESSIBLE_VALUE_PROPERTY
435       * @see #ACCESSIBLE_SELECTION_PROPERTY
436       * @see #ACCESSIBLE_TEXT_PROPERTY
437       * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
438       * @see #removePropertyChangeListener(PropertyChangeListener)
439       */
440      public void addPropertyChangeListener(PropertyChangeListener l)
441      {
442        listeners.addPropertyChangeListener(l);
443      }
444    
445      /**
446       * Remove a PropertyChangeListener from the listener list.
447       *
448       * @param l the listener to remove
449       * @see #addPropertyChangeListener(PropertyChangeListener)
450       */
451      public void removePropertyChangeListener(PropertyChangeListener l)
452      {
453        listeners.removePropertyChangeListener(l);
454      }
455    
456      /**
457       * Get any supported accessible actions. The default implementation returns
458       * null.
459       *
460       * @return the supported action, or null
461       * @see AccessibleAction
462       */
463      public AccessibleAction getAccessibleAction()
464      {
465        return null;
466      }
467    
468      /**
469       * Get any supported accessible compoent. The default implementation returns
470       * null.
471       *
472       * @return the supported component, or null
473       * @see AccessibleComponent
474       */
475      public AccessibleComponent getAccessibleComponent()
476      {
477        return null;
478      }
479    
480      /**
481       * Get any supported accessible selection. The default implementation returns
482       * null.
483       *
484       * @return the supported selection, or null
485       * @see AccessibleSelection
486       */
487      public AccessibleSelection getAccessibleSelection()
488      {
489        return null;
490      }
491    
492      /**
493       * Get any supported accessible text. The default implementation returns
494       * null.
495       *
496       * @return the supported text, or null
497       * @see AccessibleText
498       */
499      public AccessibleText getAccessibleText()
500      {
501        return null;
502      }
503    
504      /**
505       * Get any supported accessible editable text. The default implementation
506       * returns null.
507       *
508       * @return the supported editable text, or null
509       * @see AccessibleEditableText
510       */
511      public AccessibleEditableText getAccessibleEditableText()
512      {
513        return null;
514      }
515    
516      /**
517       * Get any supported accessible value. The default implementation returns
518       * null.
519       *
520       * @return the supported value, or null
521       * @see AccessibleValue
522       */
523      public AccessibleValue getAccessibleValue()
524      {
525        return null;
526      }
527    
528      /**
529       * Get all supported accessible icons. The default implementation returns
530       * null.
531       *
532       * @return the supported icons, or null
533       * @see AccessibleIcon
534       */
535      public AccessibleIcon[] getAccessibleIcon()
536      {
537        return null;
538      }
539    
540      /**
541       * Get any supported accessible relation set. The default implementation
542       * returns null.
543       *
544       * @return the supported relation set, or null
545       * @see AccessibleRelationSet
546       */
547      public AccessibleRelationSet getAccessibleRelationSet()
548      {
549        return null;
550      }
551    
552      /**
553       * Get any supported accessible table. The default implementation returns
554       * null.
555       *
556       * @return the supported table, or null
557       * @see AccessibleTable
558       */
559      public AccessibleTable getAccessibleTable()
560      {
561        return null;
562      }
563    
564      /**
565       * Fire an event to report property changes. This is intended for use by
566       * the accessible objects, not general application programs. If oldValue and
567       * newValue differ, and the listenter list is not empty, a PropertyChange
568       * event is fired to each listener.
569       *
570       * @param name the property name
571       * @param oldValue the prior value
572       * @param newValue the updated value
573       * @see PropertyChangeSupport
574       * @see #addPropertyChangeListener(PropertyChangeListener)
575       * @see #removePropertyChangeListener(PropertyChangeListener)
576       * @see #ACCESSIBLE_NAME_PROPERTY
577       * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
578       * @see #ACCESSIBLE_STATE_PROPERTY
579       * @see #ACCESSIBLE_VALUE_PROPERTY
580       * @see #ACCESSIBLE_SELECTION_PROPERTY
581       * @see #ACCESSIBLE_TEXT_PROPERTY
582       * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
583       */
584      public void firePropertyChange(String name, Object oldValue, Object newValue)
585      {
586        listeners.firePropertyChange(name, oldValue, newValue);
587      }
588    } // class AccessibleContext

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26