JDK14/Java14源码在线阅读

/*
 * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
 * 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
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * 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.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.accessibility;

import java.awt.IllegalComponentStateException;
import java.beans.BeanProperty;
import java.beans.JavaBean;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.beans.PropertyChangeSupport;
import java.util.Locale;

import sun.awt.AWTAccessor;
import sun.awt.AppContext;

/**
 * {@code 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. {@code 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:
 * <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>
 *
 * @author Peter Korn
 * @author Hans Muller
 * @author Willie Walker
 * @author Lynn Monsanto
 */
@JavaBean(description = "Minimal information that all accessible objects return")
public abstract class AccessibleContext {

    /**
     * The {@code AppContext} that should be used to dispatch events for this
     * {@code AccessibleContext}.
     */
    private volatile AppContext targetAppContext;

    static {
        AWTAccessor.setAccessibleContextAccessor(new AWTAccessor.AccessibleContextAccessor() {
            @Override
            public void setAppContext(AccessibleContext accessibleContext, AppContext appContext) {
                accessibleContext.targetAppContext = appContext;
            }

            @Override
            public AppContext getAppContext(AccessibleContext accessibleContext) {
                return accessibleContext.targetAppContext;
            }

            @Override
            public Object getNativeAXResource(AccessibleContext accessibleContext) {
                return accessibleContext.nativeAXResource;
            }

            @Override
            public void setNativeAXResource(AccessibleContext accessibleContext, Object value) {
                accessibleContext.nativeAXResource = value;
            }
        });
    }

    /**
     * Constant used to determine when the {@link #accessibleName} property has
     * changed. The old value in the {@code PropertyChangeEvent} will be the old
     * {@code accessibleName} and the new value will be the new
     * {@code accessibleName}.
     *
     * @see #getAccessibleName
     * @see #addPropertyChangeListener
     */
    public static final String ACCESSIBLE_NAME_PROPERTY = "AccessibleName";

    /**
     * Constant used to determine when the {@link #accessibleDescription}
     * property has changed. The old value in the {@code PropertyChangeEvent}
     * will be the old {@code accessibleDescription} and the new value will be
     * the new {@code accessibleDescription}.
     *
     * @see #getAccessibleDescription
     * @see #addPropertyChangeListener
     */
    public static final String ACCESSIBLE_DESCRIPTION_PROPERTY = "AccessibleDescription";

    /**
     * Constant used to determine when the {@code accessibleStateSet} property
     * has changed. The old value will be the old {@code AccessibleState} and
     * the new value will be the new {@code AccessibleState} in the
     * {@code 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 {@code AccessibleState.VERTICAL} and
     * the new value will be {@code AccessibleState.HORIZONTAL}. Please note
     * that either value can also be {@code null}. For example, when a component
     * changes from being enabled to disabled, the old value will be
     * {@code AccessibleState.ENABLED} and the new value will be {@code null}.
     *
     * @see #getAccessibleStateSet
     * @see AccessibleState
     * @see AccessibleStateSet
     * @see #addPropertyChangeListener
     */
    public static final String ACCESSIBLE_STATE_PROPERTY = "AccessibleState";

    /**
     * Constant used to determine when the {@code accessibleValue} property has
     * changed. The old value in the {@code PropertyChangeEvent} will be a
     * {@code Number} representing the old value and the new value will be a
     * {@code Number} representing the new value.
     *
     * @see #getAccessibleValue
     * @see #addPropertyChangeListener
     */
    public static final String ACCESSIBLE_VALUE_PROPERTY = "AccessibleValue";

    /**
     * Constant used to determine when the {@code accessibleSelection} has
     * changed. The old and new values in the {@code 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 {@code accessibleText} caret has
     * changed. The old value in the {@code 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 {@code PropertyChangeEvent} are
     * currently reserved for future use.
     *
     * @see #addPropertyChangeListener
     */
    public static final String ACCESSIBLE_VISIBLE_DATA_PROPERTY = "AccessibleVisibleData";

    /**
     * Constant used to determine when {@code Accessible} children are
     * added/removed from the object. If an {@code Accessible} child is being
     * added, the old value will be {@code null} and the new value will be the
     * {@code Accessible} child. If an {@code Accessible} child is being
     * removed, the old value will be the {@code Accessible} child, and the new
     * value will be {@code 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
     * {@code Accessible} representing the previous active child, and the new
     * value will be the {@code 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 {@code PropertyChangeEvent} will be an {@code Accessible}
     * representing the previous table caption and the new value will be an
     * {@code 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 {@code PropertyChangeEvent} will be an {@code Accessible}
     * representing the previous table summary and the new value will be an
     * {@code 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 {@code PropertyChangeEvent} will be {@code null} and the new value
     * will be an {@code 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 {@code PropertyChangeEvent} will be {@code null} and the new value
     * will be an {@code 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 {@code PropertyChangeEvent} will be {@code null} and the new
     * value will be an {@code 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 {@code PropertyChangeEvent} will be {@code null} and the new
     * value will be an {@code 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 {@code PropertyChangeEvent} will be {@code null} and the
     * new value will be an {@code 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 {@code PropertyChangeEvent} will be an
     * {@code Integer} representing the old number of actions supported and the
     * new value will be an {@code 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 {@code PropertyChangeEvent} will be an
     * {@code Integer} representing the start index in the document of the
     * previous element that had focus and the new value will be an
     * {@code 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";

    /**
     * {@code PropertyChangeEvent} which indicates that text has changed.
     * <br>
     * For text insertion, the {@code oldValue} is {@code null} and the
     * {@code newValue} is an {@code AccessibleTextSequence} specifying the text
     * that was inserted.
     * <br>
     * For text deletion, the {@code oldValue} is an
     * {@code AccessibleTextSequence} specifying the text that was deleted and
     * the {@code newValue} is {@code null}.
     * <br>
     * For text replacement, the {@code oldValue} is an
     * {@code AccessibleTextSequence} specifying the old text and the
     * {@code newValue} is an {@code AccessibleTextSequence} specifying the new
     * text.
     *
     * @see #getAccessibleText
     * @see #addPropertyChangeListener
     * @see AccessibleTextSequence
     */
    public static final String ACCESSIBLE_TEXT_PROPERTY
        = "AccessibleText";

    /**
     * {@code 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 {@code oldValue} is {@code null} and the
     * {@code 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";

    /**
     * {@code PropertyChangeEvent} which indicates that text attributes have
     * changed.
     * <br>
     * For attribute insertion, the {@code oldValue} is {@code null} and the
     * {@code newValue} is an {@code AccessibleAttributeSequence} specifying the
     * attributes that were inserted.
     * <br>
     * For attribute deletion, the {@code oldValue} is an
     * {@code AccessibleAttributeSequence} specifying the attributes that were
     * deleted and the {@code newValue} is {@code null}.
     * <br>
     * For attribute replacement, the {@code oldValue} is an
     * {@code AccessibleAttributeSequence} specifying the old attributes and the
     * {@code newValue} is an {@code AccessibleAttributeSequence} specifying the
     * new attributes.
     *
     * @see #getAccessibleText
     * @see #addPropertyChangeListener
     * @see AccessibleAttributeSequence
     * @since 1.5
     */
    public static final String ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED =
        "accessibleTextAttributesChanged";

    /**
     * {@code PropertyChangeEvent} which indicates that a change has occurred in
     * a component's bounds. The {@code oldValue} is the old component bounds
     * and the {@code 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 #firePropertyChange
     */
    private PropertyChangeSupport accessibleChangeSupport = null;

    /**
     * Used to represent the context's relation set.
     *
     * @see #getAccessibleRelationSet
     */
    private AccessibleRelationSet relationSet
        = new AccessibleRelationSet();

    private Object nativeAXResource;

    /**
     * Gets the {@code accessibleName} property of this object. The
     * {@code accessibleName} property of an object is a localized
     * {@code String} that designates the purpose of the object. For example,
     * the {@code 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 {@code accessibleName} should still be set. For
     * example, in the case of a text field used to enter the name of a city,
     * the {@code accessibleName} for the {@code en_US} locale could be 'city.'
     *
     * @return the localized name of the object; {@code 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 {@code PropertyChangeEvent} to be fired for the
     * {@code ACCESSIBLE_NAME_PROPERTY} property.
     *
     * @param  s the new localized name of the object
     * @see #getAccessibleName
     * @see #addPropertyChangeListener
     */
    @BeanProperty(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 {@code accessibleDescription} property of this object. The
     * {@code 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 {@code accessibleDescription} could be
     * 'Ignore changes and close dialog box.'
     *
     * @return the localized description of the object; {@code 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 {@code PropertyChangeEvent} to be fired for the
     * {@code ACCESSIBLE_DESCRIPTION_PROPERTY} property.
     *
     * @param  s the new localized description of the object
     * @see #setAccessibleName
     * @see #addPropertyChangeListener
     */
    @BeanProperty(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 {@code AccessibleRole.PUSH_BUTTON}. The roles in
     * {@code 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 {@code AccessibleRole.PUSH_BUTTON} for all components that act like a
     * push button) as well as distinguish between subclasses that behave
     * differently (e.g., {@code AccessibleRole.CHECK_BOX} for check boxes and
     * {@code AccessibleRole.RADIO_BUTTON} for radio buttons).
     * <p>
     * Note that the {@code AccessibleRole} class is also extensible, so custom
     * component developers can define their own {@code AccessibleRole}'s if the
     * set of predefined roles is inadequate.
     *
     * @return an instance of {@code AccessibleRole} describing the role of the
     *         object
     * @see AccessibleRole
     */
    public abstract AccessibleRole getAccessibleRole();

    /**
     * Gets the state set of this object. The {@code AccessibleStateSet} of an
     * object is composed of a set of unique {@code AccessibleStates}. A change
     * in the {@code AccessibleStateSet} of an object will cause a
     * {@code PropertyChangeEvent} to be fired for the
     * {@code ACCESSIBLE_STATE_PROPERTY} property.
     *
     * @return an instance of {@code AccessibleStateSet} containing the current
     *         state set of the object
     * @see AccessibleStateSet
     * @see AccessibleState
     * @see #addPropertyChangeListener
     */
    public abstract AccessibleStateSet getAccessibleStateSet();

    /**
     * Gets the {@code Accessible} parent of this object.
     *
     * @return the {@code Accessible} parent of this object; {@code null} if
     *         this object does not have an {@code Accessible} parent
     */
    public Accessible getAccessibleParent() {
        return accessibleParent;
    }

    /**
     * Sets the {@code 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 - {@code Accessible} to be set as the parent
     */
    public void setAccessibleParent(Accessible a) {
        accessibleParent = a;
    }

    /**
     * Gets the 0-based index of this object in its accessible parent.
     *
     * @return the 0-based index of this object in its parent; -1 if this object
     *         does not have an accessible parent.
     * @see #getAccessibleParent
     * @see #getAccessibleChildrenCount
     * @see #getAccessibleChild
     */
    public abstract int getAccessibleIndexInParent();

    /**
     * Returns the number of accessible children of the object.
     *
     * @return the number of accessible children of the object.
     */
    public abstract int getAccessibleChildrenCount();

    /**
     * Returns the specified {@code Accessible} child of the object. The
     * {@code Accessible} children of an {@code Accessible} object are
     * zero-based, so the first child of an {@code Accessible} child is at index
     * 0, the second child is at index 1, and so on.
     *
     * @param  i zero-based index of child
     * @return the {@code Accessible} child of the object
     * @see #getAccessibleChildrenCount
     */
    public abstract Accessible getAccessibleChild(int i);

    /**
     * Gets the locale of the component. If the component does not have a
     * locale, then the locale of its parent is returned.
     *
     * @return this component's locale. If this component does not have a
     *         locale, the locale of its parent is returned.
     * @throws IllegalComponentStateException If the component does not have its
     *         own locale and has not yet been added to a containment hierarchy
     *         such that the locale can be determined from the containing
     *         parent
     */
    public abstract Locale getLocale() throws IllegalComponentStateException;

    /**
     * Adds a {@code PropertyChangeListener} to the listener list. The listener
     * is registered for all {@code Accessible} properties and will be called
     * when those properties change.
     *
     * @param  listener The PropertyChangeListener to be added
     * @see #ACCESSIBLE_NAME_PROPERTY
     * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
     * @see #ACCESSIBLE_STATE_PROPERTY
     * @see #ACCESSIBLE_VALUE_PROPERTY
     * @see #ACCESSIBLE_SELECTION_PROPERTY
     * @see #ACCESSIBLE_TEXT_PROPERTY
     * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
     */
    public void addPropertyChangeListener(PropertyChangeListener listener) {
        if (accessibleChangeSupport == null) {
            accessibleChangeSupport = new PropertyChangeSupport(this);
        }
        accessibleChangeSupport.addPropertyChangeListener(listener);
    }

    /**
     * Removes a {@code PropertyChangeListener} from the listener list. This
     * removes a {@code PropertyChangeListener} that was registered for all
     * properties.
     *
     * @param  listener The PropertyChangeListener to be removed
     */
    public void removePropertyChangeListener(PropertyChangeListener listener) {
        if (accessibleChangeSupport != null) {
            accessibleChangeSupport.removePropertyChangeListener(listener);
        }
    }

    /**
     * Gets the {@code AccessibleAction} associated with this object that
     * supports one or more actions.
     *
     * @return {@code AccessibleAction} if supported by object; else return
     *         {@code null}
     * @see AccessibleAction
     */
    public AccessibleAction getAccessibleAction() {
        return null;
    }

    /**
     * Gets the {@code AccessibleComponent} associated with this object that has
     * a graphical representation.
     *
     * @return {@code AccessibleComponent} if supported by object; else return
     *         {@code null}
     * @see AccessibleComponent
     */
    public AccessibleComponent getAccessibleComponent() {
        return null;
    }

    /**
     * Gets the {@code AccessibleSelection} associated with this object which
     * allows its {@code Accessible} children to be selected.
     *
     * @return {@code AccessibleSelection} if supported by object; else return
     *         {@code null}
     * @see AccessibleSelection
     */
    public AccessibleSelection getAccessibleSelection() {
        return null;
    }

    /**
     * Gets the {@code AccessibleText} associated with this object presenting
     * text on the display.
     *
     * @return {@code AccessibleText} if supported by object; else return
     *         {@code null}
     * @see AccessibleText
     */
    public AccessibleText getAccessibleText() {
        return null;
    }

    /**
     * Gets the {@code AccessibleEditableText} associated with this object
     * presenting editable text on the display.
     *
     * @return {@code AccessibleEditableText} if supported by object; else
     *         return {@code null}
     * @see AccessibleEditableText
     * @since 1.4
     */

/**代码未完, 请加载全部代码(NowJava.com).**/