1/*
2 * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.accessibility;
27
28import java.awt.Color;
29import java.awt.Cursor;
30import java.awt.Dimension;
31import java.awt.Font;
32import java.awt.FontMetrics;
33import java.awt.Point;
34import java.awt.Rectangle;
35import java.awt.event.FocusListener;
36
37/**
38 * The {@code AccessibleComponent} interface should be supported by any object
39 * that is rendered on the screen. This interface provides the standard
40 * mechanism for an assistive technology to determine and set the graphical
41 * representation of an object. Applications can determine if an object supports
42 * the {@code AccessibleComponent} interface by first obtaining its
43 * {@code AccessibleContext} and then calling the
44 * {@link AccessibleContext#getAccessibleComponent} method. If the return value
45 * is not {@code null}, the object supports this interface.
46 *
47 * @author Peter Korn
48 * @author Hans Muller
49 * @author Willie Walker
50 * @see Accessible
51 * @see Accessible#getAccessibleContext
52 * @see AccessibleContext
53 * @see AccessibleContext#getAccessibleComponent
54 */
55public interface AccessibleComponent {
56
57    /**
58     * Gets the background color of this object.
59     *
60     * @return the background color, if supported, of the object; otherwise,
61     *         {@code null}
62     * @see #setBackground
63     */
64    public Color getBackground();
65
66    /**
67     * Sets the background color of this object.
68     *
69     * @param  c the new color for the background
70     * @see #setBackground
71     */
72    public void setBackground(Color c);
73
74    /**
75     * Gets the foreground color of this object.
76     *
77     * @return the foreground color, if supported, of the object; otherwise,
78     *         {@code null}
79     * @see #setForeground
80     */
81    public Color getForeground();
82
83    /**
84     * Sets the foreground color of this object.
85     *
86     * @param  c the new color for the foreground
87     * @see #getForeground
88     */
89    public void setForeground(Color c);
90
91    /**
92     * Gets the cursor of this object.
93     *
94     * @return the cursor, if supported, of the object; otherwise, {@code null}
95     * @see #setCursor
96     */
97    public Cursor getCursor();
98
99    /**
100     * Sets the cursor of this object.
101     *
102     * @param  cursor the new cursor for the object
103     * @see #getCursor
104     */
105    public void setCursor(Cursor cursor);
106
107    /**
108     * Gets the font of this object.
109     *
110     * @return the font, if supported, for the object; otherwise, {@code null}
111     * @see #setFont
112     */
113    public Font getFont();
114
115    /**
116     * Sets the font of this object.
117     *
118     * @param  f the new font for the object
119     * @see #getFont
120     */
121    public void setFont(Font f);
122
123    /**
124     * Gets the {@code FontMetrics} of this object.
125     *
126     * @param  f the font for which font metrics is to be obtained
127     * @return the {@code FontMetrics}, if supported, the object; otherwise,
128     *         {@code null}
129     * @see #getFont
130     */
131    public FontMetrics getFontMetrics(Font f);
132
133    /**
134     * Determines if the object is enabled. Objects that are enabled will also
135     * have the {@code AccessibleState.ENABLED} state set in their
136     * {@code AccessibleStateSets}.
137     *
138     * @return {@code true} if object is enabled; otherwise, {@code false}
139     * @see #setEnabled
140     * @see AccessibleContext#getAccessibleStateSet
141     * @see AccessibleState#ENABLED
142     * @see AccessibleStateSet
143     */
144    public boolean isEnabled();
145
146    /**
147     * Sets the enabled state of the object.
148     *
149     * @param  b if {@code true}, enables this object; otherwise, disables it
150     * @see #isEnabled
151     */
152    public void setEnabled(boolean b);
153
154    /**
155     * Determines if the object is visible. Note: this means that the object
156     * intends to be visible; however, it may not be showing on the screen
157     * because one of the objects that this object is contained by is currently
158     * not visible. To determine if an object is showing on the screen, use
159     * {@link #isShowing()}
160     * <p>
161     * Objects that are visible will also have the
162     * {@code AccessibleState.VISIBLE} state set in their
163     * {@code AccessibleStateSets}.
164     *
165     * @return {@code true} if object is visible; otherwise, {@code false}
166     * @see #setVisible
167     * @see AccessibleContext#getAccessibleStateSet
168     * @see AccessibleState#VISIBLE
169     * @see AccessibleStateSet
170     */
171    public boolean isVisible();
172
173    /**
174     * Sets the visible state of the object.
175     *
176     * @param  b if {@code true}, shows this object; otherwise, hides it
177     * @see #isVisible
178     */
179    public void setVisible(boolean b);
180
181    /**
182     * Determines if the object is showing. This is determined by checking the
183     * visibility of the object and its ancestors. Note: this will return
184     * {@code true} even if the object is obscured by another (for example, it
185     * is underneath a menu that was pulled down).
186     *
187     * @return {@code true} if object is showing; otherwise, {@code false}
188     */
189    public boolean isShowing();
190
191    /**
192     * Checks whether the specified point is within this object's bounds, where
193     * the point's x and y coordinates are defined to be relative to the
194     * coordinate system of the object.
195     *
196     * @param  p the point relative to the coordinate system of the object
197     * @return {@code true} if object contains point; otherwise {@code false}
198     * @see #getBounds
199     */
200    public boolean contains(Point p);
201
202    /**
203     * Returns the location of the object on the screen.
204     *
205     * @return the location of the object on screen; {@code null} if this object
206     *         is not on the screen
207     * @see #getBounds
208     * @see #getLocation
209     */
210    public Point getLocationOnScreen();
211
212    /**
213     * Gets the location of the object relative to the parent in the form of a
214     * point specifying the object's top-left corner in the screen's coordinate
215     * space.
216     *
217     * @return An instance of {@code Point} representing the top-left corner of
218     *         the object's bounds in the coordinate space of the screen;
219     *         {@code null} if this object or its parent are not on the screen
220     * @see #getBounds
221     * @see #getLocationOnScreen
222     */
223    public Point getLocation();
224
225    /**
226     * Sets the location of the object relative to the parent.
227     *
228     * @param  p the new position for the top-left corner
229     * @see #getLocation
230     */
231    public void setLocation(Point p);
232
233    /**
234     * Gets the bounds of this object in the form of a {@code Rectangle} object.
235     * The bounds specify this object's width, height, and location relative to
236     * its parent.
237     *
238     * @return A rectangle indicating this component's bounds; {@code null} if
239     *         this object is not on the screen.
240     * @see #contains
241     */
242    public Rectangle getBounds();
243
244    /**
245     * Sets the bounds of this object in the form of a {@code Rectangle} object.
246     * The bounds specify this object's width, height, and location relative to
247     * its parent.
248     *
249     * @param  r rectangle indicating this component's bounds
250     * @see #getBounds
251     */
252    public void setBounds(Rectangle r);
253
254    /**
255     * Returns the size of this object in the form of a {@code Dimension}
256     * object. The {@code height} field of the {@code Dimension} object contains
257     * this object's height, and the {@code width} field of the
258     * {@code Dimension} object contains this object's width.
259     *
260     * @return A {@code Dimension} object that indicates the size of this
261     *         component; {@code null} if this object is not on the screen
262     * @see #setSize
263     */
264    public Dimension getSize();
265
266    /**
267     * Resizes this object so that it has width and height.
268     *
269     * @param  d The dimension specifying the new size of the object
270     * @see #getSize
271     */
272    public void setSize(Dimension d);
273
274    /**
275     * Returns the {@code Accessible} child, if one exists, contained at the
276     * local coordinate {@code Point}.
277     *
278     * @param  p The point relative to the coordinate system of this object
279     * @return the {@code Accessible}, if it exists, at the specified location;
280     *         otherwise {@code null}
281     */
282    public Accessible getAccessibleAt(Point p);
283
284    /**
285     * Returns whether this object can accept focus or not. Objects that can
286     * accept focus will also have the {@code AccessibleState.FOCUSABLE} state
287     * set in their {@code AccessibleStateSets}.
288     *
289     * @return {@code true} if object can accept focus; otherwise {@code false}
290     * @see AccessibleContext#getAccessibleStateSet
291     * @see AccessibleState#FOCUSABLE
292     * @see AccessibleState#FOCUSED
293     * @see AccessibleStateSet
294     */
295    public boolean isFocusTraversable();
296
297    /**
298     * Requests focus for this object. If this object cannot accept focus,
299     * nothing will happen. Otherwise, the object will attempt to take focus.
300     *
301     * @see #isFocusTraversable
302     */
303    public void requestFocus();
304
305    /**
306     * Adds the specified focus listener to receive focus events from this
307     * component.
308     *
309     * @param  l the focus listener
310     * @see #removeFocusListener
311     */
312    public void addFocusListener(FocusListener l);
313
314    /**
315     * Removes the specified focus listener so it no longer receives focus
316     * events from this component.
317     *
318     * @param  l the focus listener
319     * @see #addFocusListener
320     */
321    public void removeFocusListener(FocusListener l);
322}
323