1/*
2 * Copyright (c) 1999, 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
28/**
29 * Class {@code AccessibleRelation} describes a relation between the object that
30 * implements the {@code AccessibleRelation} and one or more other objects. The
31 * actual relations that an object has with other objects are defined as an
32 * {@code AccessibleRelationSet}, which is a composed set of
33 * {@code AccessibleRelations}.
34 * <p>
35 * The {@link #toDisplayString()} method allows you to obtain the localized
36 * string for a locale independent key from a predefined {@code ResourceBundle}
37 * for the keys defined in this class.
38 * <p>
39 * The constants in this class present a strongly typed enumeration of common
40 * object roles. If the constants in this class are not sufficient to describe
41 * the role of an object, a subclass should be generated from this class and it
42 * should provide constants in a similar manner.
43 *
44 * @author Lynn Monsanto
45 * @since 1.3
46 */
47public class AccessibleRelation extends AccessibleBundle {
48
49    /**
50     * The group of objects that participate in the relation. The relation may
51     * be one-to-one or one-to-many. For example, in the case of a
52     * {@code LABEL_FOR} relation, the target vector would contain a list of
53     * objects labeled by the object that implements this
54     * {@code AccessibleRelation}. In the case of a {@code MEMBER_OF} relation,
55     * the target vector would contain all of the components that are members of
56     * the same group as the object that implements this
57     * {@code AccessibleRelation}.
58     */
59    private Object [] target = new Object[0];
60
61    /**
62     * Indicates an object is a label for one or more target objects.
63     *
64     * @see #getTarget
65     * @see #CONTROLLER_FOR
66     * @see #CONTROLLED_BY
67     * @see #LABELED_BY
68     * @see #MEMBER_OF
69     */
70    public static final String LABEL_FOR = new String("labelFor");
71
72    /**
73     * Indicates an object is labeled by one or more target objects.
74     *
75     * @see #getTarget
76     * @see #CONTROLLER_FOR
77     * @see #CONTROLLED_BY
78     * @see #LABEL_FOR
79     * @see #MEMBER_OF
80     */
81    public static final String LABELED_BY = new String("labeledBy");
82
83    /**
84     * Indicates an object is a member of a group of one or more target objects.
85     *
86     * @see #getTarget
87     * @see #CONTROLLER_FOR
88     * @see #CONTROLLED_BY
89     * @see #LABEL_FOR
90     * @see #LABELED_BY
91     */
92    public static final String MEMBER_OF = new String("memberOf");
93
94    /**
95     * Indicates an object is a controller for one or more target objects.
96     *
97     * @see #getTarget
98     * @see #CONTROLLED_BY
99     * @see #LABEL_FOR
100     * @see #LABELED_BY
101     * @see #MEMBER_OF
102     */
103    public static final String CONTROLLER_FOR = new String("controllerFor");
104
105    /**
106     * Indicates an object is controlled by one or more target objects.
107     *
108     * @see #getTarget
109     * @see #CONTROLLER_FOR
110     * @see #LABEL_FOR
111     * @see #LABELED_BY
112     * @see #MEMBER_OF
113     */
114    public static final String CONTROLLED_BY = new String("controlledBy");
115
116    /**
117     * Indicates an object is logically contiguous with a second object where
118     * the second object occurs after the object. An example is a paragraph of
119     * text that runs to the end of a page and continues on the next page with
120     * an intervening text footer and/or text header. The two parts of the
121     * paragraph are separate text elements but are related in that the second
122     * element is a continuation of the first element. In other words, the first
123     * element "flows to" the second element.
124     *
125     * @since 1.5
126     */
127    public static final String FLOWS_TO = "flowsTo";
128
129    /**
130     * Indicates an object is logically contiguous with a second object where
131     * the second object occurs before the object. An example is a paragraph of
132     * text that runs to the end of a page and continues on the next page with
133     * an intervening text footer and/or text header. The two parts of the
134     * paragraph are separate text elements but are related in that the second
135     * element is a continuation of the first element. In other words, the
136     * second element "flows from" the second element.
137     *
138     * @since 1.5
139     */
140    public static final String FLOWS_FROM = "flowsFrom";
141
142    /**
143     * Indicates that an object is a subwindow of one or more objects.
144     *
145     * @since 1.5
146     */
147    public static final String SUBWINDOW_OF = "subwindowOf";
148
149    /**
150     * Indicates that an object is a parent window of one or more objects.
151     *
152     * @since 1.5
153     */
154    public static final String PARENT_WINDOW_OF = "parentWindowOf";
155
156    /**
157     * Indicates that an object has one or more objects embedded in it.
158     *
159     * @since 1.5
160     */
161    public static final String EMBEDS = "embeds";
162
163    /**
164     * Indicates that an object is embedded in one or more objects.
165     *
166     * @since 1.5
167     */
168    public static final String EMBEDDED_BY = "embeddedBy";
169
170    /**
171     * Indicates that an object is a child node of one or more objects.
172     *
173     * @since 1.5
174     */
175    public static final String CHILD_NODE_OF = "childNodeOf";
176
177    /**
178     * Identifies that the target group for a label has changed.
179     */
180    public static final String LABEL_FOR_PROPERTY = "labelForProperty";
181
182    /**
183     * Identifies that the objects that are doing the labeling have changed.
184     */
185    public static final String LABELED_BY_PROPERTY = "labeledByProperty";
186
187    /**
188     * Identifies that group membership has changed.
189     */
190    public static final String MEMBER_OF_PROPERTY = "memberOfProperty";
191
192    /**
193     * Identifies that the controller for the target object has changed.
194     */
195    public static final String CONTROLLER_FOR_PROPERTY = "controllerForProperty";
196
197    /**
198     * Identifies that the target object that is doing the controlling has
199     * changed.
200     */
201    public static final String CONTROLLED_BY_PROPERTY = "controlledByProperty";
202
203    /**
204     * Indicates the {@code FLOWS_TO} relation between two objects has changed.
205     *
206     * @since 1.5
207     */
208    public static final String FLOWS_TO_PROPERTY = "flowsToProperty";
209
210    /**
211     * Indicates the {@code FLOWS_FROM} relation between two objects has
212     * changed.
213     *
214     * @since 1.5
215     */
216    public static final String FLOWS_FROM_PROPERTY = "flowsFromProperty";
217
218    /**
219     * Indicates the {@code SUBWINDOW_OF} relation between two or more objects
220     * has changed.
221     *
222     * @since 1.5
223     */
224    public static final String SUBWINDOW_OF_PROPERTY = "subwindowOfProperty";
225
226    /**
227     * Indicates the {@code PARENT_WINDOW_OF} relation between two or more
228     * objects has changed.
229     *
230     * @since 1.5
231     */
232    public static final String PARENT_WINDOW_OF_PROPERTY = "parentWindowOfProperty";
233
234    /**
235     * Indicates the {@code EMBEDS} relation between two or more objects has
236     * changed.
237     *
238     * @since 1.5
239     */
240    public static final String EMBEDS_PROPERTY = "embedsProperty";
241
242    /**
243     * Indicates the {@code EMBEDDED_BY} relation between two or more objects
244     * has changed.
245     *
246     * @since 1.5
247     */
248    public static final String EMBEDDED_BY_PROPERTY = "embeddedByProperty";
249
250    /**
251     * Indicates the {@code CHILD_NODE_OF} relation between two or more objects
252     * has changed.
253     *
254     * @since 1.5
255     */
256    public static final String CHILD_NODE_OF_PROPERTY = "childNodeOfProperty";
257
258    /**
259     * Create a new {@code AccessibleRelation} using the given locale
260     * independent key. The key {@code String} should be a locale independent
261     * key for the relation. It is not intended to be used as the actual
262     * {@code String} to display to the user. To get the localized string, use
263     * {@link #toDisplayString()}.
264     *
265     * @param  key the locale independent name of the relation
266     * @see AccessibleBundle#toDisplayString
267     */
268    public AccessibleRelation(String key) {
269        this.key = key;
270        this.target = null;
271    }
272
273    /**
274     * Creates a new {@code AccessibleRelation} using the given locale
275     * independent key. The key {@code String} should be a locale independent
276     * key for the relation. It is not intended to be used as the actual
277     * {@code String} to display to the user. To get the localized string, use
278     * {@link #toDisplayString()}.
279     *
280     * @param  key the locale independent name of the relation
281     * @param  target the target object for this relation
282     * @see AccessibleBundle#toDisplayString
283     */
284    public AccessibleRelation(String key, Object target) {
285        this.key = key;
286        this.target = new Object[1];
287        this.target[0] = target;
288    }
289
290    /**
291     * Creates a new {@code AccessibleRelation} using the given locale
292     * independent key. The key {@code String} should be a locale independent
293     * key for the relation. It is not intended to be used as the actual
294     * {@code String} to display to the user. To get the localized string, use
295     * {@link #toDisplayString()}.
296     *
297     * @param  key the locale independent name of the relation
298     * @param  target the target object(s) for this relation
299     * @see AccessibleBundle#toDisplayString
300     */
301    public AccessibleRelation(String key, Object[] target) {
302        this.key = key;
303        this.target = target;
304    }
305
306    /**
307     * Returns the key for this relation.
308     *
309     * @return the key for this relation
310     * @see #CONTROLLER_FOR
311     * @see #CONTROLLED_BY
312     * @see #LABEL_FOR
313     * @see #LABELED_BY
314     * @see #MEMBER_OF
315     */
316    public String getKey() {
317        return this.key;
318    }
319
320    /**
321     * Returns the target objects for this relation.
322     *
323     * @return an array containing the target objects for this relation
324     */
325    public Object [] getTarget() {
326        if (target == null) {
327            target = new Object[0];
328        }
329        Object [] retval = new Object[target.length];
330        for (int i = 0; i < target.length; i++) {
331            retval[i] = target[i];
332        }
333        return retval;
334    }
335
336    /**
337     * Sets the target object for this relation.
338     *
339     * @param  target the target object for this relation
340     */
341    public void setTarget(Object target) {
342        this.target = new Object[1];
343        this.target[0] = target;
344    }
345
346    /**
347     * Sets the target objects for this relation.
348     *
349     * @param  target an array containing the target objects for this relation
350     */
351    public void setTarget(Object [] target) {
352        this.target = target;
353    }
354}
355