/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * particular file as subject to the "Classpath" exception as provided

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 */

package javax.accessibility;

import java.util.Locale;

import java.beans.PropertyChangeListener;

import java.beans.PropertyChangeSupport;

import java.beans.PropertyChangeEvent;

import java.awt.IllegalComponentStateException;

/**

 * AccessibleContext represents the minimum information all accessible objects

 * return.  This information includes the accessible name, description, role,

 * and state of the object, as well as information about its parent and

 * children.  AccessibleContext also contains methods for

 * obtaining more specific accessibility information about a component.

 * If the component supports them, these methods will return an object that

 * implements one or more of the following interfaces:

 * <P><ul>

 * <li>{@link AccessibleAction} - the object can perform one or more actions.

 * This interface provides the standard mechanism for an assistive

 * technology to determine what those actions are and tell the object

 * to perform them.  Any object that can be manipulated should

 * support this interface.

 * <li>{@link AccessibleComponent} - the object has a graphical representation.

 * This interface provides the standard mechanism for an assistive

 * technology to determine and set the graphical representation of the

 * object.  Any object that is rendered on the screen should support

 * this interface.

 * <li>{@link  AccessibleSelection} - the object allows its children to be

 * selected.  This interface provides the standard mechanism for an

 * assistive technology to determine the currently selected children of the object

 * as well as modify its selection set.  Any object that has children

 * that can be selected should support this interface.

 * <li>{@link AccessibleText} - the object presents editable textual information

 * on the display.  This interface provides the standard mechanism for

 * an assistive technology to access that text via its content, attributes,

 * and spatial location.  Any object that contains editable text should

 * support this interface.

 * <li>{@link AccessibleValue} - the object supports a numerical value.  This

 * interface provides the standard mechanism for an assistive technology

 * to determine and set the current value of the object, as well as obtain its

 * minimum and maximum values.  Any object that supports a numerical value

 * should support this interface.</ul>

 *

 *

 * @beaninfo

 *   attribute: isContainer false

 * description: Minimal information that all accessible objects return

 *

 * @author      Peter Korn

 * @author      Hans Muller

 * @author      Willie Walker

 * @author      Lynn Monsanto

 */

public abstract class AccessibleContext {

   /**

    * Constant used to determine when the accessibleName property has

    * changed.  The old value in the PropertyChangeEvent will be the old

    * accessibleName and the new value will be the new accessibleName.

    *

    * @see #getAccessibleName

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_NAME_PROPERTY = "AccessibleName";

   /**

    * Constant used to determine when the accessibleDescription property has

    * changed.  The old value in the PropertyChangeEvent will be the

    * old accessibleDescription and the new value will be the new

    * accessibleDescription.

    *

    * @see #getAccessibleDescription

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_DESCRIPTION_PROPERTY = "AccessibleDescription";

   /**

    * Constant used to determine when the accessibleStateSet property has

    * changed.  The old value will be the old AccessibleState and the new

    * value will be the new AccessibleState in the accessibleStateSet.

    * For example, if a component that supports the vertical and horizontal

    * states changes its orientation from vertical to horizontal, the old

    * value will be AccessibleState.VERTICAL and the new value will be

    * AccessibleState.HORIZONTAL.  Please note that either value can also

    * be null.  For example, when a component changes from being enabled

    * to disabled, the old value will be AccessibleState.ENABLED

    * and the new value will be null.

    *

    * @see #getAccessibleStateSet

    * @see AccessibleState

    * @see AccessibleStateSet

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_STATE_PROPERTY = "AccessibleState";

   /**

    * Constant used to determine when the accessibleValue property has

    * changed.  The old value in the PropertyChangeEvent will be a Number

    * representing the old value and the new value will be a Number

    * representing the new value

    *

    * @see #getAccessibleValue

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_VALUE_PROPERTY = "AccessibleValue";

   /**

    * Constant used to determine when the accessibleSelection has changed.

    * The old and new values in the PropertyChangeEvent are currently

    * reserved for future use.

    *

    * @see #getAccessibleSelection

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_SELECTION_PROPERTY = "AccessibleSelection";

   /**

    * Constant used to determine when the accessibleText caret has changed.

    * The old value in the PropertyChangeEvent will be an

    * integer representing the old caret position, and the new value will

    * be an integer representing the new/current caret position.

    *

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_CARET_PROPERTY = "AccessibleCaret";

   /**

    * Constant used to determine when the visual appearance of the object

    * has changed.  The old and new values in the PropertyChangeEvent are

    * currently reserved for future use.

    *

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY = "AccessibleVisibleData";

   /**

    * Constant used to determine when Accessible children are added/removed

    * from the object.  If an Accessible child is being added, the old

    * value will be null and the new value will be the Accessible child.  If an

    * Accessible child is being removed, the old value will be the Accessible

    * child, and the new value will be null.

    *

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_CHILD_PROPERTY = "AccessibleChild";

   /**

    * Constant used to determine when the active descendant of a component

    * has changed.  The active descendant is used for objects such as

    * list, tree, and table, which may have transient children.  When the

    * active descendant has changed, the old value of the property change

    * event will be the Accessible representing the previous active child, and

    * the new value will be the Accessible representing the current active

    * child.

    *

    * @see #addPropertyChangeListener

    */

   public static final String ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY = "AccessibleActiveDescendant";

    /**

     * Constant used to indicate that the table caption has changed

     * The old value in the PropertyChangeEvent will be an Accessible

     * representing the previous table caption and the new value will

     * be an Accessible representing the new table caption.

     * @see Accessible

     * @see AccessibleTable

     */

    public static final String ACCESSIBLE_TABLE_CAPTION_CHANGED =

        "accessibleTableCaptionChanged";

    /**

     * Constant used to indicate that the table summary has changed

     * The old value in the PropertyChangeEvent will be an Accessible

     * representing the previous table summary and the new value will

     * be an Accessible representing the new table summary.

     * @see Accessible

     * @see AccessibleTable

     */

    public static final String ACCESSIBLE_TABLE_SUMMARY_CHANGED =

        "accessibleTableSummaryChanged";

    /**

     * Constant used to indicate that table data has changed.

     * The old value in the PropertyChangeEvent will be null and the

     * new value will be an AccessibleTableModelChange representing

     * the table change.

     * @see AccessibleTable

     * @see AccessibleTableModelChange

     */

    public static final String ACCESSIBLE_TABLE_MODEL_CHANGED =

        "accessibleTableModelChanged";

    /**

     * Constant used to indicate that the row header has changed

     * The old value in the PropertyChangeEvent will be null and the

     * new value will be an AccessibleTableModelChange representing

     * the header change.

     * @see AccessibleTable

     * @see AccessibleTableModelChange

     */

    public static final String ACCESSIBLE_TABLE_ROW_HEADER_CHANGED =

        "accessibleTableRowHeaderChanged";

    /**

     * Constant used to indicate that the row description has changed

     * The old value in the PropertyChangeEvent will be null and the

     * new value will be an Integer representing the row index.

     * @see AccessibleTable

     */

    public static final String ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED =

        "accessibleTableRowDescriptionChanged";

    /**

     * Constant used to indicate that the column header has changed

     * The old value in the PropertyChangeEvent will be null and the

     * new value will be an AccessibleTableModelChange representing

     * the header change.

     * @see AccessibleTable

     * @see AccessibleTableModelChange

     */

    public static final String ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED =

        "accessibleTableColumnHeaderChanged";

    /**

     * Constant used to indicate that the column description has changed

     * The old value in the PropertyChangeEvent will be null and the

     * new value will be an Integer representing the column index.

     * @see AccessibleTable

     */

    public static final String ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED =

        "accessibleTableColumnDescriptionChanged";

    /**

     * Constant used to indicate that the supported set of actions

     * has changed.  The old value in the PropertyChangeEvent will

     * be an Integer representing the old number of actions supported

     * and the new value will be an Integer representing the new

     * number of actions supported.

     * @see AccessibleAction

     */

    public static final String ACCESSIBLE_ACTION_PROPERTY =

        "accessibleActionProperty";

    /**

     * Constant used to indicate that a hypertext element has received focus.

     * The old value in the PropertyChangeEvent will be an Integer

     * representing the start index in the document of the previous element

     * that had focus and the new value will be an Integer representing

     * the start index in the document of the current element that has

     * focus.  A value of -1 indicates that an element does not or did

     * not have focus.

     * @see AccessibleHyperlink

     */

    public static final String ACCESSIBLE_HYPERTEXT_OFFSET =

        "AccessibleHypertextOffset";

    /**

     * PropertyChangeEvent which indicates that text has changed.

     * <br>

     * For text insertion, the oldValue is null and the newValue

     * is an AccessibleTextSequence specifying the text that was

     * inserted.

     * <br>

     * For text deletion, the oldValue is an AccessibleTextSequence

     * specifying the text that was deleted and the newValue is null.

     * <br>

     * For text replacement, the oldValue is an AccessibleTextSequence

     * specifying the old text and the newValue is an AccessibleTextSequence

     * specifying the new text.

     *

     * @see #getAccessibleText

     * @see #addPropertyChangeListener

     * @see AccessibleTextSequence

     */

    public static final String ACCESSIBLE_TEXT_PROPERTY

        = "AccessibleText";

    /**

     * PropertyChangeEvent which indicates that a significant change

     * has occurred to the children of a component like a tree or text.

     * This change notifies the event listener that it needs to

     * reacquire the state of the subcomponents. The oldValue is

     * null and the newValue is the component whose children have

     * become invalid.

     *

     * @see #getAccessibleText

     * @see #addPropertyChangeListener

     * @see AccessibleTextSequence

     *

     * @since 1.5

     */

    public static final String ACCESSIBLE_INVALIDATE_CHILDREN =

        "accessibleInvalidateChildren";

     /**

     * PropertyChangeEvent which indicates that text attributes have changed.

     * <br>

     * For attribute insertion, the oldValue is null and the newValue

     * is an AccessibleAttributeSequence specifying the attributes that were

     * inserted.

     * <br>

     * For attribute deletion, the oldValue is an AccessibleAttributeSequence

     * specifying the attributes that were deleted and the newValue is null.

     * <br>

     * For attribute replacement, the oldValue is an AccessibleAttributeSequence

     * specifying the old attributes and the newValue is an

     * AccessibleAttributeSequence specifying the new attributes.

     *

     * @see #getAccessibleText

     * @see #addPropertyChangeListener

     * @see AccessibleAttributeSequence

     *

     * @since 1.5

     */

    public static final String ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED =

        "accessibleTextAttributesChanged";

   /**

     * PropertyChangeEvent which indicates that a change has occurred

     * in a component's bounds.

     * The oldValue is the old component bounds and the newValue is

     * the new component bounds.

     *

     * @see #addPropertyChangeListener

     *

     * @since 1.5

     */

    public static final String ACCESSIBLE_COMPONENT_BOUNDS_CHANGED =

        "accessibleComponentBoundsChanged";

    /**

     * The accessible parent of this object.

     *

     * @see #getAccessibleParent

     * @see #setAccessibleParent

     */

    protected Accessible accessibleParent = null;

    /**

     * A localized String containing the name of the object.

     *

     * @see #getAccessibleName

     * @see #setAccessibleName

     */

    protected String accessibleName = null;

    /**

     * A localized String containing the description of the object.

     *

     * @see #getAccessibleDescription

     * @see #setAccessibleDescription

     */

    protected String accessibleDescription = null;

    /**

     * Used to handle the listener list for property change events.

     *

     * @see #addPropertyChangeListener

     * @see #removePropertyChangeListener

     * @see #firePropertyChangeListener

     */

    private PropertyChangeSupport accessibleChangeSupport = null;

    /**

     * Used to represent the context's relation set

     * @see #getAccessibleRelationSet

     */

    private AccessibleRelationSet relationSet

        = new AccessibleRelationSet();

    /**

     * Gets the accessibleName property of this object.  The accessibleName

     * property of an object is a localized String that designates the purpose

     * of the object.  For example, the accessibleName property of a label

     * or button might be the text of the label or button itself.  In the

     * case of an object that doesn't display its name, the accessibleName

     * should still be set.  For example, in the case of a text field used

     * to enter the name of a city, the accessibleName for the en_US locale

     * could be 'city.'

     *

     * @return the localized name of the object; null if this

     * object does not have a name

     *

     * @see #setAccessibleName

     */

    public String getAccessibleName() {

        return accessibleName;

    }

    /**

     * Sets the localized accessible name of this object.  Changing the

     * name will cause a PropertyChangeEvent to be fired for the

     * ACCESSIBLE_NAME_PROPERTY property.

     *

     * @param s the new localized name of the object.

     *

     * @see #getAccessibleName

     * @see #addPropertyChangeListener

     *

     * @beaninfo

     *    preferred:   true

     *    description: Sets the accessible name for the component.

     */

    public void setAccessibleName(String s) {

        String oldName = accessibleName;

        accessibleName = s;

        firePropertyChange(ACCESSIBLE_NAME_PROPERTY,oldName,accessibleName);

    }

    /**

     * Gets the accessibleDescription property of this object.  The

     * accessibleDescription property of this object is a short localized

     * phrase describing the purpose of the object.  For example, in the

     * case of a 'Cancel' button, the accessibleDescription could be

     * 'Ignore changes and close dialog box.'

     *

     * @return the localized description of the object; null if

     * this object does not have a description

     *

     * @see #setAccessibleDescription

     */

    public String getAccessibleDescription() {

        return accessibleDescription;

    }

    /**

     * Sets the accessible description of this object.  Changing the

     * name will cause a PropertyChangeEvent to be fired for the

     * ACCESSIBLE_DESCRIPTION_PROPERTY property.

     *

     * @param s the new localized description of the object

     *

     * @see #setAccessibleName

     * @see #addPropertyChangeListener

     *

     * @beaninfo

     *    preferred:   true

     *    description: Sets the accessible description for the component.

     */

    public void setAccessibleDescription(String s) {

        String oldDescription = accessibleDescription;

        accessibleDescription = s;

        firePropertyChange(ACCESSIBLE_DESCRIPTION_PROPERTY,

                           oldDescription,accessibleDescription);

    }

    /**

     * Gets the role of this object.  The role of the object is the generic

     * purpose or use of the class of this object.  For example, the role

     * of a push button is AccessibleRole.PUSH_BUTTON.  The roles in

     * AccessibleRole are provided so component developers can pick from

     * a set of predefined roles.  This enables assistive technologies to

     * provide a consistent interface to various tweaked subclasses of

     * components (e.g., use AccessibleRole.PUSH_BUTTON for all components

     * that act like a push button) as well as distinguish between sublasses

     * that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes

     * and AccessibleRole.RADIO_BUTTON for radio buttons).

     * <p>Note that the AccessibleRole class is also extensible, so

     * custom component developers can define their own AccessibleRole's

     * if the set of predefined roles is inadequate.

     *

     * @return an instance of AccessibleRole describing the role of the object

     * @see AccessibleRole

     */

    public abstract AccessibleRole getAccessibleRole();

    /**

     * Gets the state set of this object.  The AccessibleStateSet of an object

     * is composed of a set of unique AccessibleStates.  A change in the

     * AccessibleStateSet of an object will cause a PropertyChangeEvent to

     * be fired for the ACCESSIBLE_STATE_PROPERTY property.

     *

     * @return an instance of AccessibleStateSet containing the

     * current state set of the object

     * @see AccessibleStateSet

     * @see AccessibleState

     * @see #addPropertyChangeListener

     */

    public abstract AccessibleStateSet getAccessibleStateSet();

    /**

     * Gets the Accessible parent of this object.

     *

     * @return the Accessible parent of this object; null if this

     * object does not have an Accessible parent

     */

    public Accessible getAccessibleParent() {

        return accessibleParent;

    }

    /**

     * Sets the Accessible parent of this object.  This is meant to be used

     * only in the situations where the actual component's parent should

     * not be treated as the component's accessible parent and is a method

     * that should only be called by the parent of the accessible child.

     *

     * @param a - Accessible to be set as the parent

     */

    public void setAccessibleParent(Accessible a) {

        accessibleParent = a;

    }