1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.util;
18
19
20import org.xmlpull.v1.XmlPullParser;
21
22/**
23 * A collection of attributes, as found associated with a tag in an XML
24 * document.  Often you will not want to use this interface directly, instead
25 * passing it to {@link android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)
26 * Resources.Theme.obtainStyledAttributes()}
27 * which will take care of parsing the attributes for you.  In particular,
28 * the Resources API will convert resource references (attribute values such as
29 * "@string/my_label" in the original XML) to the desired type
30 * for you; if you use AttributeSet directly then you will need to manually
31 * check for resource references
32 * (with {@link #getAttributeResourceValue(int, int)}) and do the resource
33 * lookup yourself if needed.  Direct use of AttributeSet also prevents the
34 * application of themes and styles when retrieving attribute values.
35 *
36 * <p>This interface provides an efficient mechanism for retrieving
37 * data from compiled XML files, which can be retrieved for a particular
38 * XmlPullParser through {@link Xml#asAttributeSet
39 * Xml.asAttributeSet()}.  Normally this will return an implementation
40 * of the interface that works on top of a generic XmlPullParser, however it
41 * is more useful in conjunction with compiled XML resources:
42 *
43 * <pre>
44 * XmlPullParser parser = resources.getXml(myResource);
45 * AttributeSet attributes = Xml.asAttributeSet(parser);</pre>
46 *
47 * <p>The implementation returned here, unlike using
48 * the implementation on top of a generic XmlPullParser,
49 * is highly optimized by retrieving pre-computed information that was
50 * generated by aapt when compiling your resources.  For example,
51 * the {@link #getAttributeFloatValue(int, float)} method returns a floating
52 * point number previous stored in the compiled resource instead of parsing
53 * at runtime the string originally in the XML file.
54 *
55 * <p>This interface also provides additional information contained in the
56 * compiled XML resource that is not available in a normal XML file, such
57 * as {@link #getAttributeNameResource(int)} which returns the resource
58 * identifier associated with a particular XML attribute name.
59 *
60 * @see XmlPullParser
61 */
62public interface AttributeSet {
63    /**
64     * Returns the number of attributes available in the set.
65     *
66     * <p>See also {@link XmlPullParser#getAttributeCount XmlPullParser.getAttributeCount()},
67     * which this method corresponds to when parsing a compiled XML file.</p>
68     *
69     * @return A positive integer, or 0 if the set is empty.
70     */
71    public int getAttributeCount();
72
73    /**
74     * Returns the namespace of the specified attribute.
75     *
76     * <p>See also {@link XmlPullParser#getAttributeNamespace XmlPullParser.getAttributeNamespace()},
77     * which this method corresponds to when parsing a compiled XML file.</p>
78     *
79     * @param index Index of the desired attribute, 0...count-1.
80     *
81     * @return A String containing the namespace of the attribute, or null if th
82     *         attribute cannot be found.
83     */
84    default String getAttributeNamespace (int index) {
85        // This is a new method since the first interface definition, so add stub impl.
86        return null;
87    }
88
89    /**
90     * Returns the name of the specified attribute.
91     *
92     * <p>See also {@link XmlPullParser#getAttributeName XmlPullParser.getAttributeName()},
93     * which this method corresponds to when parsing a compiled XML file.</p>
94     *
95     * @param index Index of the desired attribute, 0...count-1.
96     *
97     * @return A String containing the name of the attribute, or null if the
98     *         attribute cannot be found.
99     */
100    public String getAttributeName(int index);
101
102    /**
103     * Returns the value of the specified attribute as a string representation.
104     *
105     * @param index Index of the desired attribute, 0...count-1.
106     *
107     * @return A String containing the value of the attribute, or null if the
108     *         attribute cannot be found.
109     */
110    public String getAttributeValue(int index);
111
112    /**
113     * Returns the value of the specified attribute as a string representation.
114     * The lookup is performed using the attribute name.
115     *
116     * @param namespace The namespace of the attribute to get the value from.
117     * @param name The name of the attribute to get the value from.
118     *
119     * @return A String containing the value of the attribute, or null if the
120     *         attribute cannot be found.
121     */
122    public String getAttributeValue(String namespace, String name);
123
124    /**
125     * Returns a description of the current position of the attribute set.
126     * For instance, if the attribute set is loaded from an XML document,
127     * the position description could indicate the current line number.
128     *
129     * @return A string representation of the current position in the set,
130     *         may be null.
131     */
132    public String getPositionDescription();
133
134    /**
135     * Return the resource ID associated with the given attribute name.  This
136     * will be the identifier for an attribute resource, which can be used by
137     * styles.  Returns 0 if there is no resource associated with this
138     * attribute.
139     *
140     * <p>Note that this is different than {@link #getAttributeResourceValue}
141     * in that it returns a resource identifier for the attribute name; the
142     * other method returns this attribute's value as a resource identifier.
143     *
144     * @param index Index of the desired attribute, 0...count-1.
145     *
146     * @return The resource identifier, 0 if none.
147     */
148    public int getAttributeNameResource(int index);
149
150    /**
151     * Return the index of the value of 'attribute' in the list 'options'.
152     *
153     * @param namespace Namespace of attribute to retrieve.
154     * @param attribute Name of attribute to retrieve.
155     * @param options List of strings whose values we are checking against.
156     * @param defaultValue Value returned if attribute doesn't exist or no
157     *                     match is found.
158     *
159     * @return Index in to 'options' or defaultValue.
160     */
161    public int getAttributeListValue(String namespace, String attribute,
162                                     String[] options, int defaultValue);
163
164    /**
165     * Return the boolean value of 'attribute'.
166     *
167     * @param namespace Namespace of attribute to retrieve.
168     * @param attribute The attribute to retrieve.
169     * @param defaultValue What to return if the attribute isn't found.
170     *
171     * @return Resulting value.
172     */
173    public boolean getAttributeBooleanValue(String namespace, String attribute,
174                                            boolean defaultValue);
175
176    /**
177     * Return the value of 'attribute' as a resource identifier.
178     *
179     * <p>Note that this is different than {@link #getAttributeNameResource}
180     * in that it returns the value contained in this attribute as a
181     * resource identifier (i.e., a value originally of the form
182     * "@package:type/resource"); the other method returns a resource
183     * identifier that identifies the name of the attribute.
184     *
185     * @param namespace Namespace of attribute to retrieve.
186     * @param attribute The attribute to retrieve.
187     * @param defaultValue What to return if the attribute isn't found.
188     *
189     * @return Resulting value.
190     */
191    public int getAttributeResourceValue(String namespace, String attribute,
192                                         int defaultValue);
193
194    /**
195     * Return the integer value of 'attribute'.
196     *
197     * @param namespace Namespace of attribute to retrieve.
198     * @param attribute The attribute to retrieve.
199     * @param defaultValue What to return if the attribute isn't found.
200     *
201     * @return Resulting value.
202     */
203    public int getAttributeIntValue(String namespace, String attribute,
204                                    int defaultValue);
205
206    /**
207     * Return the boolean value of 'attribute' that is formatted as an
208     * unsigned value.  In particular, the formats 0xn...n and #n...n are
209     * handled.
210     *
211     * @param namespace Namespace of attribute to retrieve.
212     * @param attribute The attribute to retrieve.
213     * @param defaultValue What to return if the attribute isn't found.
214     *
215     * @return Resulting value.
216     */
217    public int getAttributeUnsignedIntValue(String namespace, String attribute,
218                                            int defaultValue);
219
220    /**
221     * Return the float value of 'attribute'.
222     *
223     * @param namespace Namespace of attribute to retrieve.
224     * @param attribute The attribute to retrieve.
225     * @param defaultValue What to return if the attribute isn't found.
226     *
227     * @return Resulting value.
228     */
229    public float getAttributeFloatValue(String namespace, String attribute,
230                                        float defaultValue);
231
232    /**
233     * Return the index of the value of attribute at 'index' in the list
234     * 'options'.
235     *
236     * @param index Index of the desired attribute, 0...count-1.
237     * @param options List of strings whose values we are checking against.
238     * @param defaultValue Value returned if attribute doesn't exist or no
239     *                     match is found.
240     *
241     * @return Index in to 'options' or defaultValue.
242     */
243    public int getAttributeListValue(int index, String[] options, int defaultValue);
244
245    /**
246     * Return the boolean value of attribute at 'index'.
247     *
248     * @param index Index of the desired attribute, 0...count-1.
249     * @param defaultValue What to return if the attribute isn't found.
250     *
251     * @return Resulting value.
252     */
253    public boolean getAttributeBooleanValue(int index, boolean defaultValue);
254
255    /**
256     * Return the value of attribute at 'index' as a resource identifier.
257     *
258     * <p>Note that this is different than {@link #getAttributeNameResource}
259     * in that it returns the value contained in this attribute as a
260     * resource identifier (i.e., a value originally of the form
261     * "@package:type/resource"); the other method returns a resource
262     * identifier that identifies the name of the attribute.
263     *
264     * @param index Index of the desired attribute, 0...count-1.
265     * @param defaultValue What to return if the attribute isn't found.
266     *
267     * @return Resulting value.
268     */
269    public int getAttributeResourceValue(int index, int defaultValue);
270
271    /**
272     * Return the integer value of attribute at 'index'.
273     *
274     * @param index Index of the desired attribute, 0...count-1.
275     * @param defaultValue What to return if the attribute isn't found.
276     *
277     * @return Resulting value.
278     */
279    public int getAttributeIntValue(int index, int defaultValue);
280
281    /**
282     * Return the integer value of attribute at 'index' that is formatted as an
283     * unsigned value.  In particular, the formats 0xn...n and #n...n are
284     * handled.
285     *
286     * @param index Index of the desired attribute, 0...count-1.
287     * @param defaultValue What to return if the attribute isn't found.
288     *
289     * @return Resulting value.
290     */
291    public int getAttributeUnsignedIntValue(int index, int defaultValue);
292
293    /**
294     * Return the float value of attribute at 'index'.
295     *
296     * @param index Index of the desired attribute, 0...count-1.
297     * @param defaultValue What to return if the attribute isn't found.
298     *
299     * @return Resulting value.
300     */
301    public float getAttributeFloatValue(int index, float defaultValue);
302
303    /**
304     * Return the value of the "id" attribute or null if there is not one.
305     * Equivalent to getAttributeValue(null, "id").
306     *
307     * @return The id attribute's value or null.
308     */
309    public String getIdAttribute();
310
311    /**
312     * Return the value of the "class" attribute or null if there is not one.
313     * Equivalent to getAttributeValue(null, "class").
314     *
315     * @return The class attribute's value or null.
316     */
317    public String getClassAttribute();
318
319    /**
320     * Return the integer value of the "id" attribute or defaultValue if there
321     * is none.
322     * Equivalent to getAttributeResourceValue(null, "id", defaultValue);
323     *
324     * @param defaultValue What to return if the "id" attribute isn't found.
325     * @return int Resulting value.
326     */
327    public int getIdAttributeResourceValue(int defaultValue);
328
329    /**
330
331     * Return the value of the "style" attribute or 0 if there is not one.
332     * Equivalent to getAttributeResourceValue(null, "style").
333     *
334     * @return The style attribute's resource identifier or 0.
335     */
336    public int getStyleAttribute();
337}
338