jdk-sandbox: comparison jdk/src/java.desktop/share/classes/javax/accessibility/AccessibleComponent.java

equal deleted inserted replaced

-:87c997b74bb8
+:499d43823920
 /*
-* Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
+* 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
 * questions.
 */
 package javax.accessibility;
-import java.awt.*;
+import java.awt.Color;
-import java.awt.event.*;
+import java.awt.Cursor;
+import java.awt.Dimension;
+import java.awt.Font;
+import java.awt.FontMetrics;
+import java.awt.Point;
+import java.awt.Rectangle;
+import java.awt.event.FocusListener;
 /**
-* The AccessibleComponent interface should be supported by any object
+* The {@code AccessibleComponent} interface should be supported by any object
-* that is rendered on the screen.  This interface provides the standard
+* that is rendered on the screen. This interface provides the standard
-* mechanism for an assistive technology to determine and set the
+* mechanism for an assistive technology to determine and set the graphical
-* graphical representation of an object.  Applications can determine
+* representation of an object. Applications can determine if an object supports
-* if an object supports the AccessibleComponent interface by first
+* the {@code AccessibleComponent} interface by first obtaining its
-* obtaining its AccessibleContext
+* {@code AccessibleContext} and then calling the
-* and then calling the
+* {@link AccessibleContext#getAccessibleComponent} method. If the return value
-* {@link AccessibleContext#getAccessibleComponent} method.
+* is not {@code null}, the object supports this interface.
-* If the return value is not null, the object supports this interface.
+*
-*
+* @author Peter Korn
+* @author Hans Muller
+* @author Willie Walker
 * @see Accessible
 * @see Accessible#getAccessibleContext
 * @see AccessibleContext
 * @see AccessibleContext#getAccessibleComponent
-*
-* @author      Peter Korn
-* @author      Hans Muller
-* @author      Willie Walker
 */
 public interface AccessibleComponent {
 /**
 * Gets the background color of this object.
 *
-* @return the background color, if supported, of the object;
+* @return the background color, if supported, of the object; otherwise,
-* otherwise, null
+*         {@code null}
 * @see #setBackground
 */
 public Color getBackground();
 /**
 * Sets the background color of this object.
 *
-* @param c the new Color for the background
+* @param  c the new color for the background
 * @see #setBackground
 */
 public void setBackground(Color c);
 /**
 * Gets the foreground color of this object.
 *
-* @return the foreground color, if supported, of the object;
+* @return the foreground color, if supported, of the object; otherwise,
-* otherwise, null
+*         {@code null}
 * @see #setForeground
 */
 public Color getForeground();
 /**
 * Sets the foreground color of this object.
 *
-* @param c the new Color for the foreground
+* @param  c the new color for the foreground
 * @see #getForeground
 */
 public void setForeground(Color c);
 /**
-* Gets the Cursor of this object.
+* Gets the cursor of this object.
 *
-* @return the Cursor, if supported, of the object; otherwise, null
+* @return the cursor, if supported, of the object; otherwise, {@code null}
 * @see #setCursor
 */
 public Cursor getCursor();
 /**
-* Sets the Cursor of this object.
+* Sets the cursor of this object.
 *
-* @param cursor  the new Cursor for the object
+* @param  cursor the new cursor for the object
 * @see #getCursor
 */
 public void setCursor(Cursor cursor);
 /**
-* Gets the Font of this object.
+* Gets the font of this object.
 *
-* @return the Font,if supported, for the object; otherwise, null
+* @return the font, if supported, for the object; otherwise, {@code null}
 * @see #setFont
 */
 public Font getFont();
 /**
-* Sets the Font of this object.
+* Sets the font of this object.
 *
-* @param f the new Font for the object
+* @param  f the new font for the object
 * @see #getFont
 */
 public void setFont(Font f);
 /**
-* Gets the FontMetrics of this object.
+* Gets the {@code FontMetrics} of this object.
 *
-* @param f the Font
+* @param  f the font for which font metrics is to be obtained
-* @return the FontMetrics, if supported, the object; otherwise, null
+* @return the {@code FontMetrics}, if supported, the object; otherwise,
+*         {@code null}
 * @see #getFont
 */
 public FontMetrics getFontMetrics(Font f);
 /**
-* Determines if the object is enabled.  Objects that are enabled
+* Determines if the object is enabled. Objects that are enabled will also
-* will also have the AccessibleState.ENABLED state set in their
+* have the {@code AccessibleState.ENABLED} state set in their
-* AccessibleStateSets.
+* {@code AccessibleStateSets}.
 *
-* @return true if object is enabled; otherwise, false
+* @return {@code true} if object is enabled; otherwise, {@code false}
 * @see #setEnabled
 * @see AccessibleContext#getAccessibleStateSet
 * @see AccessibleState#ENABLED
 * @see AccessibleStateSet
 */
 public boolean isEnabled();
 /**
 * Sets the enabled state of the object.
 *
-* @param b if true, enables this object; otherwise, disables it
+* @param  b if {@code true}, enables this object; otherwise, disables it
 * @see #isEnabled
 */
 public void setEnabled(boolean b);
 /**
-* Determines if the object is visible.  Note: this means that the
+* Determines if the object is visible. Note: this means that the object
-* object intends to be visible; however, it may not be
+* intends to be visible; however, it may not be showing on the screen
-* showing on the screen because one of the objects that this object
+* because one of the objects that this object is contained by is currently
-* is contained by is currently not visible.  To determine if an object is
+* not visible. To determine if an object is showing on the screen, use
-* showing on the screen, use isShowing().
+* {@link #isShowing()}
-* <p>Objects that are visible will also have the
+* <p>
-* AccessibleState.VISIBLE state set in their AccessibleStateSets.
+* Objects that are visible will also have the
-*
+* {@code AccessibleState.VISIBLE} state set in their
-* @return true if object is visible; otherwise, false
+* {@code AccessibleStateSets}.
+*
+* @return {@code true} if object is visible; otherwise, {@code false}
 * @see #setVisible
 * @see AccessibleContext#getAccessibleStateSet
 * @see AccessibleState#VISIBLE
 * @see AccessibleStateSet
 */
 public boolean isVisible();
 /**
 * Sets the visible state of the object.
 *
-* @param b if true, shows this object; otherwise, hides it
+* @param  b if {@code true}, shows this object; otherwise, hides it
 * @see #isVisible
 */
 public void setVisible(boolean b);
 /**
-* Determines if the object is showing.  This is determined by checking
+* Determines if the object is showing. This is determined by checking the
-* the visibility of the object and its ancestors.
+* visibility of the object and its ancestors. Note: this will return
-* Note: this
+* {@code true} even if the object is obscured by another (for example, it
-* will return true even if the object is obscured by another (for example,
+* is underneath a menu that was pulled down).
-* it is underneath a menu that was pulled down).
+*
-*
+* @return {@code true} if object is showing; otherwise, {@code false}
-* @return true if object is showing; otherwise, false
 */
 public boolean isShowing();
 /**
-* Checks whether the specified point is within this object's bounds,
+* Checks whether the specified point is within this object's bounds, where
-* where the point's x and y coordinates are defined to be relative to the
+* the point's x and y coordinates are defined to be relative to the
 * coordinate system of the object.
 *
-* @param p the Point relative to the coordinate system of the object
+* @param  p the point relative to the coordinate system of the object
-* @return true if object contains Point; otherwise false
+* @return {@code true} if object contains point; otherwise {@code false}
 * @see #getBounds
 */
 public boolean contains(Point p);
 /**
 * Returns the location of the object on the screen.
 *
-* @return the location of the object on screen; null if this object
+* @return the location of the object on screen; {@code null} if this object
-* is not on the screen
+*         is not on the screen
 * @see #getBounds
 * @see #getLocation
 */
 public Point getLocationOnScreen();
 /**
-* Gets the location of the object relative to the parent in the form
+* Gets the location of the object relative to the parent in the form of a
-* of a point specifying the object's top-left corner in the screen's
+* point specifying the object's top-left corner in the screen's coordinate
-* coordinate space.
+* space.
 *
-* @return An instance of Point representing the top-left corner of the
+* @return An instance of {@code Point} representing the top-left corner of
-* object's bounds in the coordinate space of the screen; null if
+*         the object's bounds in the coordinate space of the screen;
-* this object or its parent are not on the screen
+*         {@code null} if this object or its parent are not on the screen
 * @see #getBounds
 * @see #getLocationOnScreen
 */
 public Point getLocation();
 /**
 * Sets the location of the object relative to the parent.
-* @param p the new position for the top-left corner
+*
+* @param  p the new position for the top-left corner
 * @see #getLocation
 */
 public void setLocation(Point p);
 /**
-* Gets the bounds of this object in the form of a Rectangle object.
+* Gets the bounds of this object in the form of a {@code Rectangle} object.
-* The bounds specify this object's width, height, and location
+* The bounds specify this object's width, height, and location relative to
-* relative to its parent.
+* its parent.
 *
-* @return A rectangle indicating this component's bounds; null if
+* @return A rectangle indicating this component's bounds; {@code null} if
-* this object is not on the screen.
+*         this object is not on the screen.
 * @see #contains
 */
 public Rectangle getBounds();
 /**
-* Sets the bounds of this object in the form of a Rectangle object.
+* Sets the bounds of this object in the form of a {@code Rectangle} object.
-* The bounds specify this object's width, height, and location
+* The bounds specify this object's width, height, and location relative to
-* relative to its parent.
+* its parent.
 *
-* @param r rectangle indicating this component's bounds
+* @param  r rectangle indicating this component's bounds
 * @see #getBounds
 */
 public void setBounds(Rectangle r);
 /**
-* Returns the size of this object in the form of a Dimension object.
+* Returns the size of this object in the form of a {@code Dimension}
-* The height field of the Dimension object contains this object's
+* object. The {@code height} field of the {@code Dimension} object contains
-* height, and the width field of the Dimension object contains this
+* this object's height, and the {@code width} field of the
-* object's width.
+* {@code Dimension} object contains this object's width.
 *
-* @return A Dimension object that indicates the size of this component;
+* @return A {@code Dimension} object that indicates the size of this
-* null if this object is not on the screen
+*         component; {@code null} if this object is not on the screen
 * @see #setSize
 */
 public Dimension getSize();
 /**
 * Resizes this object so that it has width and height.
 *
-* @param d The dimension specifying the new size of the object.
+* @param  d The dimension specifying the new size of the object
 * @see #getSize
 */
 public void setSize(Dimension d);
 /**
-* Returns the Accessible child, if one exists, contained at the local
+* Returns the {@code Accessible} child, if one exists, contained at the
-* coordinate Point.
+* local coordinate {@code Point}.
 *
-* @param p The point relative to the coordinate system of this object.
+* @param  p The point relative to the coordinate system of this object
-* @return the Accessible, if it exists, at the specified location;
+* @return the {@code Accessible}, if it exists, at the specified location;
-* otherwise null
+*         otherwise {@code null}
 */
 public Accessible getAccessibleAt(Point p);
 /**
-* Returns whether this object can accept focus or not.   Objects that
+* Returns whether this object can accept focus or not. Objects that can
-* can accept focus will also have the AccessibleState.FOCUSABLE state
+* accept focus will also have the {@code AccessibleState.FOCUSABLE} state
-* set in their AccessibleStateSets.
+* set in their {@code AccessibleStateSets}.
 *
-* @return true if object can accept focus; otherwise false
+* @return {@code true} if object can accept focus; otherwise {@code false}
 * @see AccessibleContext#getAccessibleStateSet
 * @see AccessibleState#FOCUSABLE
 * @see AccessibleState#FOCUSED
 * @see AccessibleStateSet
 */
 public boolean isFocusTraversable();
 /**
-* Requests focus for this object.  If this object cannot accept focus,
+* Requests focus for this object. If this object cannot accept focus,
-* nothing will happen.  Otherwise, the object will attempt to take
+* nothing will happen. Otherwise, the object will attempt to take focus.
-* focus.
+*
 * @see #isFocusTraversable
 */
 public void requestFocus();
 /**
 * Adds the specified focus listener to receive focus events from this
 * component.
 *
-* @param l the focus listener
+* @param  l the focus listener
 * @see #removeFocusListener
 */
 public void addFocusListener(FocusListener l);
 /**
 * Removes the specified focus listener so it no longer receives focus
 * events from this component.
 *
-* @param l the focus listener
+* @param  l the focus listener
 * @see #addFocusListener
 */
 public void removeFocusListener(FocusListener l);
 }

changeset 45649	499d43823920
parent 25859	3317bb8137f4