home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / accessibility / AccessibleContext.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  19.1 KB  |  499 lines
  1. /*
  2.  * @(#)AccessibleContext.java    1.17 98/02/04
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20.  
  21. package java.awt.accessibility;
  22.  
  23. import java.util.Locale;
  24. import java.beans.PropertyChangeListener;
  25. import java.beans.PropertyChangeSupport;
  26. import java.awt.IllegalComponentStateException;
  27.  
  28. /**
  29.  * AccessibleContext represents the minimum information all accessible objects
  30.  * return.  This information includes the accessible name, description, role,
  31.  * and state of the object, as well as information about the parent and 
  32.  * children of the object.  AccessibleContext also contains methods for
  33.  * obtaining more specific accessibility information about a component.
  34.  * If the component supports it, these methods will return an object that
  35.  * implements one or more of the following interfaces:
  36.  * <P><ul>
  37.  * <li><a href="java.awt.accessibility.AccessibleAction.html">
  38.  * AccessibleAction</a> - the object can perform one or more actions.  
  39.  * This interface provides the standard mechanism for an assistive
  40.  * technology to determine what those actions are and tell the object
  41.  * to perform those actions.  Any object that can be manipulated should
  42.  * support this interface.
  43.  * <li><a href="java.awt.accessibility.AccessibleComponent.html">
  44.  * AccessibleComponent</a> - the object has a graphical representation.
  45.  * This interface provides the standard mechanism for an assistive 
  46.  * technology to determine and set the graphical representation of the 
  47.  * object.  Any object that is rendered on the screen should support
  48.  * this interface.
  49.  * <li><a href="java.awt.accessibility.AccessibleSelection.html">
  50.  * AccessibleSelection</a> - the object allows its children to be 
  51.  * selected.  This interface provides the standard mechanism for an
  52.  * assistive technology to determine the currently selected children
  53.  * as well as modify the selection set.  Any object that has children
  54.  * that can be selected should support this interface.
  55.  * <li><a href="java.awt.accessibility.AccessibleText.html">
  56.  * AccessibleText</a> - the object presents editable textual information
  57.  * on the display.  This interface provides the standard mechanism for
  58.  * an assistive technology to access that text via its content, attributes,
  59.  * and spatial location.  Any object that contains editable text should
  60.  * support this interface.
  61.  * <li><a href="java.awt.accessibility.AccessibleValue.html">
  62.  * AccessibleValue</a> - the object supports a numerical value.  This
  63.  * interface provides the standard mechanism for an assistive technology
  64.  * to determine and set the current value of the object, as well as the
  65.  * minimum and maximum values.  Any object that supports a numerical value
  66.  * should support this interface.</ul>
  67.  * <P>In the future, additional interfaces (e.g., AccessibleTable) may be 
  68.  * added, and the abstract class AccessibleContext will be updated
  69.  * accordingly.
  70.  *
  71.  * @version     1.17 02/04/98 11:50:50
  72.  * @author    Peter Korn
  73.  * @author      Hans Muller
  74.  * @author      Willie Walker
  75.  */
  76. public abstract class AccessibleContext {
  77.  
  78.    /**
  79.     * Constant used to determine when the accessibleName property has
  80.     * changed.  The old value in the PropertyChangeEvent will be the old 
  81.     * accessibleName and the new value will be the new accessibleName.
  82.     *
  83.     * @see #getAccessibleName
  84.     * @see #addPropertyChangeListener
  85.     */
  86.    public static final String ACCESSIBLE_NAME_PROPERTY = "AccessibleName";
  87.  
  88.    /**
  89.     * Constant used to determine when the accessibleDescription property has
  90.     * changed.  The old value in the PropertyChangeEvent will be the
  91.     * old accessibleDescription and the new value will be the new
  92.     * accessibleDescription.
  93.     *
  94.     * @see #getAccessibleDescription
  95.     * @see #addPropertyChangeListener
  96.     */
  97.    public static final String ACCESSIBLE_DESCRIPTION_PROPERTY = "AccessibleDescription";
  98.  
  99.    /**
  100.     * Constant used to determine when the accessibleStateSet property has 
  101.     * changed.  The old value will be the old AccessibleState and the new
  102.     * value will be the new AccessibleState in the accessibleStateSet.  
  103.     * For example, if a component that supports the vertical and horizontal
  104.     * states changes its orientation from vertical to horizontal, the old
  105.     * value will be AccessibleState.VERTICAL and the new value will be
  106.     * AccessibleState.HORIZONTAL.  Please note that either value can also 
  107.     * be null.  For example, when a component changes from being enabled 
  108.     * to disabled, the old value will be AccessibleState.ENABLED
  109.     * and the new value will null.
  110.     *
  111.     * @see #getAccessibleStateSet
  112.     * @see AccessibleState
  113.     * @see AccessibleStateSet
  114.     * @see #addPropertyChangeListener
  115.     */
  116.    public static final String ACCESSIBLE_STATE_PROPERTY = "AccessibleState";
  117.  
  118.    /**
  119.     * Constant used to determine when the accessibleValue property has
  120.     * changed.  The old value in the PropertyChangeEvent will be a Number 
  121.     * representing the old value and the new value will be a Number 
  122.     * representing the new value.
  123.     *
  124.     * @see #getAccessibleValue
  125.     * @see #addPropertyChangeListener
  126.     */
  127.    public static final String ACCESSIBLE_VALUE_PROPERTY = "AccessibleValue";
  128.  
  129.    /**
  130.     * Constant used to determine when the accessibleSelection has changed.
  131.     * The old and new values in the PropertyChangeEvent are currently 
  132.     * reserved for future use.
  133.     *
  134.     * @see #getAccessibleSelection
  135.     * @see #addPropertyChangeListener
  136.     */
  137.    public static final String ACCESSIBLE_SELECTION_PROPERTY = "AccessibleSelection";
  138.  
  139.    /**
  140.     * Constant used to determine when the accessibleText has changed.
  141.     * The old and new values in the PropertyChangeEvent are currently 
  142.     * reserved for future use.
  143.     *
  144.     * @see #getAccessibleText
  145.     * @see #addPropertyChangeListener
  146.     */
  147.    public static final String ACCESSIBLE_TEXT_PROPERTY = "AccessibleText";
  148.  
  149.    /**
  150.     * Constant used to determine when the accessibleText caret has changed.
  151.     * The old and new values in the PropertyChangeEvent are currently 
  152.     * reserved for future use.
  153.     *
  154.     * @see #addPropertyChangeListener
  155.     */
  156.    public static final String ACCESSIBLE_CARET_PROPERTY = "AccessibleCaret";
  157.  
  158.    /**
  159.     * Constant used to determine when the visual appearance of the object
  160.     * has changed.  The old value in the PropertyChangeEvent will be an
  161.     * integer representing the old caret position, and the new value will 
  162.     * be an integer representing the new/current caret position.
  163.     *
  164.     * @see #addPropertyChangeListener
  165.     */
  166.    public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY = "AccessibleVisibleData";
  167.  
  168.     /** 
  169.      * The accessible parent of this object.
  170.      *
  171.      * @see #getAccessibleParent
  172.      * @see #setAccessibleParent
  173.      */
  174.     protected Accessible accessibleParent = null;
  175.  
  176.     /**
  177.      * A localized String containing the name of the object.
  178.      *
  179.      * @see #getAccessibleName
  180.      * @see #setAccessibleName 
  181.      */
  182.     protected String accessibleName = null;
  183.  
  184.     /**
  185.      * A localized String containing the description of the object.
  186.      *
  187.      * @see #getAccessibleDescription
  188.      * @see #setAccessibleDescription 
  189.      */
  190.     protected String accessibleDescription = null;
  191.  
  192.     /**
  193.      * Used to handle the listener list for property change events.
  194.      *
  195.      * @see #addPropertyChangeListener
  196.      * @see #removePropertyChangeListener
  197.      * @see #firePropertyChangeListener
  198.      */
  199.     private PropertyChangeSupport accessibleChangeSupport = null;
  200.  
  201.     /**
  202.      * Get the accessibleName property of this object.  The accessibleName
  203.      * property of an object is a localized String that designates the purpose
  204.      * of the object.  For example, the accessibleName property of a label
  205.      * or button might be the text of the label or button itself.  In the
  206.      * case of an object that doesn't display its name, the accessibleName
  207.      * should still be set.  For example, in the case of a text field used
  208.      * to enter the name of a city, the accessibleName for the en_US locale
  209.      * could be 'city.'
  210.      *
  211.      * @return the localized name of the object; null if this 
  212.      * object does not have a name
  213.      *
  214.      * @see #setAccessibleName
  215.      */
  216.     public String getAccessibleName() {
  217.     return accessibleName;
  218.     }
  219.     
  220.     /**
  221.      * Set the localized accessible name of this object.  Changing the
  222.      * name will cause a PropertyChangeEvent to be fired for the
  223.      * ACCESSIBLE_NAME_PROPERTY property.
  224.      *
  225.      * @param s the new localized name of the object.
  226.      *
  227.      * @see #getAccessibleName
  228.      * @see #addPropertyChangeListener
  229.      */
  230.     public void setAccessibleName(String s) {
  231.     String oldName = accessibleName;
  232.     accessibleName = s;
  233.     firePropertyChange(ACCESSIBLE_NAME_PROPERTY,oldName,accessibleName);
  234.     }
  235.  
  236.     /**
  237.      * Get the accessibleDescription property of this object.  The
  238.      * accessibleDescription property of this object is a short localized
  239.      * phrase describing the purpose of the object.  For example, in the 
  240.      * case of a 'Cancel' button, the accessibleDescription could be
  241.      * 'Ignore changes and close dialog box.'
  242.      *
  243.      * @return the localized description of the object; null if 
  244.      * this object does not have a description
  245.      *
  246.      * @see #setAccessibleDescription
  247.      */
  248.     public String getAccessibleDescription() {
  249.     return accessibleDescription;
  250.     }
  251.  
  252.     /**
  253.      * Set the accessible description of this object.  Changing the
  254.      * name will cause a PropertyChangeEvent to be fired for the
  255.      * ACCESSIBLE_DESCRIPTION_PROPERTY property.
  256.      *
  257.      * @param s the new localized description of the object
  258.      *
  259.      * @see #setAccessibleName
  260.      * @see #addPropertyChangeListener
  261.      */
  262.     public void setAccessibleDescription(String s) {
  263.     String oldDescription = accessibleDescription;
  264.     accessibleDescription = s;
  265.     firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,
  266.                oldDescription,accessibleDescription);
  267.     }
  268.  
  269.     /**
  270.      * Get the role of this object.  The role of the object is the generic
  271.      * purpose or use of the class of this object.  For example, the role
  272.      * of a push button is AccessibleRole.PUSH_BUTTON.  The roles in 
  273.      * AccessibleRole are provided so component developers can pick from
  274.      * a set of predefined roles.  This enables assistive technologies to
  275.      * provide a consistent interface to various tweaked subclasses of 
  276.      * components (e.g., use AccessibleRole.PUSH_BUTTON for all components
  277.      * that act like a push button) as well as distinguish between sublasses
  278.      * that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes
  279.      * and AccessibleRole.RADIO_BUTTON for radio buttons).
  280.      * <p>Note that the AccessibleRole class is also extensible, so 
  281.      * custom component developers can define their own AccessibleRole's
  282.      * if the set of predefined roles is inadequate.
  283.      *
  284.      * @return an instance of AccessibleRole describing the role of the object
  285.      * @see AccessibleRole
  286.      */
  287.     public abstract AccessibleRole getAccessibleRole();
  288.     
  289.     /**
  290.      * Get the state set of this object.  The AccessibleStateSet of an object
  291.      * is composed of a set of unique AccessibleState's.  A change in the 
  292.      * AccessibleStateSet of an object will cause a PropertyChangeEvent to 
  293.      * be fired for the ACCESSIBLE_STATE_PROPERTY property.
  294.      *
  295.      * @return an instance of AccessibleStateSet containing the 
  296.      * current state set of the object
  297.      * @see AccessibleStateSet
  298.      * @see AccessibleState
  299.      * @see #addPropertyChangeListener
  300.      */
  301.     public abstract AccessibleStateSet getAccessibleStateSet();
  302.  
  303.     /**
  304.      * Get the Accessible parent of this object.
  305.      *
  306.      * @return the Accessible parent of this object; null if this
  307.      * object does not have an Accessible parent
  308.      */
  309.     public Accessible getAccessibleParent() {
  310.     return accessibleParent;
  311.     }
  312.  
  313.     /**
  314.      * Set the Accessible parent of this object.  This is meant to be used
  315.      * only in the situations where the actual component's parent should 
  316.      * not be treated as the component's accessible parent and is a method 
  317.      * that should only be called by the parent of the accessible child. 
  318.      *
  319.      * @param a - Accessible to be set as the parent    
  320.      */
  321.     public void setAccessibleParent(Accessible a) {
  322.         accessibleParent = a;
  323.     }
  324.  
  325.     /**
  326.      * Get the 0-based index of this object in its accessible parent.
  327.      *
  328.      * @return the 0-based index of this object in its parent; -1 if this 
  329.      * object does not have an accessible parent.
  330.      *
  331.      * @see #getAccessibleParent 
  332.      * @see #getAccessibleChildrenCount
  333.      * @see #getAccessibleChild
  334.      */
  335.     public abstract int getAccessibleIndexInParent();
  336.  
  337.     /**
  338.      * Returns the number of accessible children of the object.
  339.      *
  340.      * @return the number of accessible children of the object.
  341.      */
  342.     public abstract int getAccessibleChildrenCount();
  343.  
  344.     /**
  345.      * Return the specified Accessible child of the object.  The Accessible
  346.      * children of an Accessible object are zero-based, so the first child 
  347.      * of an Accessible child is at index 0, the second child is at index 1,
  348.      * and so on.
  349.      *
  350.      * @param i zero-based index of child
  351.      * @return the Accessible child of the object
  352.      * @see #getAccessibleChildrenCount
  353.      */
  354.     public abstract Accessible getAccessibleChild(int i);
  355.  
  356.     /** 
  357.      * Gets the locale of the component. If the component does not have a 
  358.      * locale, then the locale of its parent is returned.  
  359.      *
  360.      * @return This component's locale.  If this component does not have 
  361.      * a locale, the locale of its parent is returned.
  362.      *
  363.      * @exception IllegalComponentStateException 
  364.      * If the Component does not have its own locale and has not yet been 
  365.      * added to a containment hierarchy such that the locale can be
  366.      * determined from the containing parent. 
  367.      */
  368.     public abstract Locale getLocale() throws IllegalComponentStateException;
  369.  
  370.     /**
  371.      * Add a PropertyChangeListener to the listener list.
  372.      * The listener is registered for all Accessible properties and will
  373.      * be called when those properties change.
  374.      *
  375.      * @see #ACCESSIBLE_NAME_PROPERTY
  376.      * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  377.      * @see #ACCESSIBLE_STATE_PROPERTY
  378.      * @see #ACCESSIBLE_VALUE_PROPERTY
  379.      * @see #ACCESSIBLE_SELECTION_PROPERTY
  380.      * @see #ACCESSIBLE_TEXT_PROPERTY
  381.      * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  382.      *
  383.      * @param listener  The PropertyChangeListener to be added
  384.      */
  385.     public void addPropertyChangeListener(PropertyChangeListener listener) {
  386.         if (accessibleChangeSupport == null) {
  387.             accessibleChangeSupport = new PropertyChangeSupport(this);
  388.         }
  389.         accessibleChangeSupport.addPropertyChangeListener(listener);
  390.     }
  391.  
  392.     /**
  393.      * Remove a PropertyChangeListener from the listener list.
  394.      * This removes a PropertyChangeListener that was registered
  395.      * for all properties.
  396.      *
  397.      * @param listener  The PropertyChangeListener to be removed
  398.      */
  399.     public void removePropertyChangeListener(PropertyChangeListener listener) {
  400.         if (accessibleChangeSupport != null) {
  401.             accessibleChangeSupport.removePropertyChangeListener(listener);
  402.         }
  403.     }
  404.  
  405.     /**
  406.      * Get the AccessibleAction associated with this object that supports
  407.      * one or more actions. 
  408.      *
  409.      * @return AccessibleAction if supported by object; else return null
  410.      * @see AccessibleAction
  411.      */
  412.     public AccessibleAction getAccessibleAction() {
  413.     return null;
  414.     }
  415.  
  416.     /**
  417.      * Get the AccessibleComponent associated with this object that has a 
  418.      * graphical representation.
  419.      *
  420.      * @return AccessibleComponent if supported by object; else return null
  421.      * @see AccessibleComponent
  422.      */
  423.     public AccessibleComponent getAccessibleComponent() {
  424.     return null;
  425.     }
  426.  
  427.     /**
  428.      * Get the AccessibleSelection associated with this object which allows its
  429.      * Accessible children to be selected.  
  430.      * 
  431.      * @return AccessibleSelection if supported by object; else return null
  432.      * @see AccessibleSelection
  433.      */
  434.     public AccessibleSelection getAccessibleSelection() {
  435.     return null;
  436.     }
  437.  
  438. //    /**
  439. //     * Get the AccessibleTable associated with this object if one
  440. //     * exists.  Otherwise return null.
  441. //     */
  442. //    public AccessibleTable getAccessibleTable() {
  443. //        return null;
  444. //    }
  445.  
  446.     /**
  447.      * Get the AccessibleText associated with this object presently editable
  448.      * text on the display.
  449.      *
  450.      * @return AccessibleText if supported by object; else return null
  451.      * @see AccessibleText
  452.      */
  453.     public AccessibleText getAccessibleText() {
  454.     return null;
  455.     }
  456.  
  457.     /**
  458.      * Get the AccessibleValue associated with this object that supports a 
  459.      * Numerical value. 
  460.      * 
  461.      * @return AccessibleValue if supported by object; else return null 
  462.      * @see AccessibleValue
  463.      */
  464.     public AccessibleValue getAccessibleValue() {
  465.     return null;
  466.     }
  467.  
  468.     /**
  469.      * Support for reporting bound property changes.  If oldValue and 
  470.      * newValue are not equal and the PropertyChangeEvent listener list 
  471.      * is not empty, then fire a PropertyChange event to each listener.
  472.      * In general, this is for use by the Accessible objects themselves
  473.      * and should not be called by an application program.
  474.      * @param propertyName  The programmatic name of the property that
  475.      * was changed.
  476.      * @param oldValue  The old value of the property.
  477.      * @param newValue  The new value of the property.
  478.      * @see java.beans.PropertyChangeSupport
  479.      * @see #addPropertyChangeListener
  480.      * @see #removePropertyChangeListener
  481.      * @see #ACCESSIBLE_NAME_PROPERTY
  482.      * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
  483.      * @see #ACCESSIBLE_STATE_PROPERTY
  484.      * @see #ACCESSIBLE_VALUE_PROPERTY
  485.      * @see #ACCESSIBLE_SELECTION_PROPERTY
  486.      * @see #ACCESSIBLE_TEXT_PROPERTY
  487.      * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
  488.      */
  489.     public void firePropertyChange(String propertyName, 
  490.                    Object oldValue, 
  491.                    Object newValue) {
  492.         if (accessibleChangeSupport != null) {
  493.         accessibleChangeSupport.firePropertyChange(propertyName, 
  494.                                oldValue, 
  495.                                newValue);
  496.     }
  497.     }
  498. }
  499.