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
20/**
21 * A collection of attributes, as found associated with a tag in an XML
22 * document.  Often you will not want to use this interface directly, instead
23 * passing it to {@link android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)
24 * Resources.Theme.obtainStyledAttributes()}
25 * which will take care of parsing the attributes for you.  In particular,
26 * the Resources API will convert resource references (attribute values such as
27 * "@string/my_label" in the original XML) to the desired type
28 * for you; if you use AttributeSet directly then you will need to manually
29 * check for resource references
30 * (with {@link #getAttributeResourceValue(int, int)}) and do the resource
31 * lookup yourself if needed.  Direct use of AttributeSet also prevents the
32 * application of themes and styles when retrieving attribute values.
33 *
34 * <p>This interface provides an efficient mechanism for retrieving
35 * data from compiled XML files, which can be retrieved for a particular
36 * XmlPullParser through {@link Xml#asAttributeSet
37 * Xml.asAttributeSet()}.  Normally this will return an implementation
38 * of the interface that works on top of a generic XmlPullParser, however it
39 * is more useful in conjunction with compiled XML resources:
40 *
41 * <pre>
42 * XmlPullParser parser = resources.getXml(myResouce);
43 * AttributeSet attributes = Xml.asAttributeSet(parser);</pre>
44 *
45 * <p>The implementation returned here, unlike using
46 * the implementation on top of a generic XmlPullParser,
47 * is highly optimized by retrieving pre-computed information that was
48 * generated by aapt when compiling your resources.  For example,
49 * the {@link #getAttributeFloatValue(int, float)} method returns a floating
50 * point number previous stored in the compiled resource instead of parsing
51 * at runtime the string originally in the XML file.
52 *
53 * <p>This interface also provides additional information contained in the
54 * compiled XML resource that is not available in a normal XML file, such
55 * as {@link #getAttributeNameResource(int)} which returns the resource
56 * identifier associated with a particular XML attribute name.
57 */
58public interface AttributeSet {
59    /**
60     * Returns the number of attributes available in the set.
61     *
62     * @return A positive integer, or 0 if the set is empty.
63     */
64    public int getAttributeCount();
65
66    /**
67     * Returns the name of the specified attribute.
68     *
69     * @param index Index of the desired attribute, 0...count-1.
70     *
71     * @return A String containing the name of the attribute, or null if the
72     *         attribute cannot be found.
73     */
74    public String getAttributeName(int index);
75
76    /**
77     * Returns the value of the specified attribute as a string representation.
78     *
79     * @param index Index of the desired attribute, 0...count-1.
80     *
81     * @return A String containing the value of the attribute, or null if the
82     *         attribute cannot be found.
83     */
84    public String getAttributeValue(int index);
85
86    /**
87     * Returns the value of the specified attribute as a string representation.
88     * The lookup is performed using the attribute name.
89     *
90     * @param namespace The namespace of the attribute to get the value from.
91     * @param name The name of the attribute to get the value from.
92     *
93     * @return A String containing the value of the attribute, or null if the
94     *         attribute cannot be found.
95     */
96    public String getAttributeValue(String namespace, String name);
97
98    /**
99     * Returns a description of the current position of the attribute set.
100     * For instance, if the attribute set is loaded from an XML document,
101     * the position description could indicate the current line number.
102     *
103     * @return A string representation of the current position in the set,
104     *         may be null.
105     */
106    public String getPositionDescription();
107
108    /**
109     * Return the resource ID associated with the given attribute name.  This
110     * will be the identifier for an attribute resource, which can be used by
111     * styles.  Returns 0 if there is no resource associated with this
112     * attribute.
113     *
114     * <p>Note that this is different than {@link #getAttributeResourceValue}
115     * in that it returns a resource identifier for the attribute name; the
116     * other method returns this attribute's value as a resource identifier.
117     *
118     * @param index Index of the desired attribute, 0...count-1.
119     *
120     * @return The resource identifier, 0 if none.
121     */
122    public int getAttributeNameResource(int index);
123
124    /**
125     * Return the index of the value of 'attribute' in the list 'options'.
126     *
127     * @param namespace Namespace of attribute to retrieve.
128     * @param attribute Name of attribute to retrieve.
129     * @param options List of strings whose values we are checking against.
130     * @param defaultValue Value returned if attribute doesn't exist or no
131     *                     match is found.
132     *
133     * @return Index in to 'options' or defaultValue.
134     */
135    public int getAttributeListValue(String namespace, String attribute,
136                                     String[] options, int defaultValue);
137
138    /**
139     * Return the boolean value of 'attribute'.
140     *
141     * @param namespace Namespace of attribute to retrieve.
142     * @param attribute The attribute to retrieve.
143     * @param defaultValue What to return if the attribute isn't found.
144     *
145     * @return Resulting value.
146     */
147    public boolean getAttributeBooleanValue(String namespace, String attribute,
148                                            boolean defaultValue);
149
150    /**
151     * Return the value of 'attribute' as a resource identifier.
152     *
153     * <p>Note that this is different than {@link #getAttributeNameResource}
154     * in that it returns a the value contained in this attribute as a
155     * resource identifier (i.e., a value originally of the form
156     * "@package:type/resource"); the other method returns a resource
157     * identifier that identifies the name of the attribute.
158     *
159     * @param namespace Namespace of attribute to retrieve.
160     * @param attribute The attribute to retrieve.
161     * @param defaultValue What to return if the attribute isn't found.
162     *
163     * @return Resulting value.
164     */
165    public int getAttributeResourceValue(String namespace, String attribute,
166                                         int defaultValue);
167
168    /**
169     * Return the integer value of 'attribute'.
170     *
171     * @param namespace Namespace of attribute to retrieve.
172     * @param attribute The attribute to retrieve.
173     * @param defaultValue What to return if the attribute isn't found.
174     *
175     * @return Resulting value.
176     */
177    public int getAttributeIntValue(String namespace, String attribute,
178                                    int defaultValue);
179
180    /**
181     * Return the boolean value of 'attribute' that is formatted as an
182     * unsigned value.  In particular, the formats 0xn...n and #n...n are
183     * handled.
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 getAttributeUnsignedIntValue(String namespace, String attribute,
192                                            int defaultValue);
193
194    /**
195     * Return the float 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 float getAttributeFloatValue(String namespace, String attribute,
204                                        float defaultValue);
205
206    /**
207     * Return the index of the value of attribute at 'index' in the list
208     * 'options'.
209     *
210     * @param index Index of the desired attribute, 0...count-1.
211     * @param options List of strings whose values we are checking against.
212     * @param defaultValue Value returned if attribute doesn't exist or no
213     *                     match is found.
214     *
215     * @return Index in to 'options' or defaultValue.
216     */
217    public int getAttributeListValue(int index, String[] options, int defaultValue);
218
219    /**
220     * Return the boolean value of attribute at 'index'.
221     *
222     * @param index Index of the desired attribute, 0...count-1.
223     * @param defaultValue What to return if the attribute isn't found.
224     *
225     * @return Resulting value.
226     */
227    public boolean getAttributeBooleanValue(int index, boolean defaultValue);
228
229    /**
230     * Return the value of attribute at 'index' as a resource identifier.
231     *
232     * <p>Note that this is different than {@link #getAttributeNameResource}
233     * in that it returns a the value contained in this attribute as a
234     * resource identifier (i.e., a value originally of the form
235     * "@package:type/resource"); the other method returns a resource
236     * identifier that identifies the name of the attribute.
237     *
238     * @param index Index of the desired attribute, 0...count-1.
239     * @param defaultValue What to return if the attribute isn't found.
240     *
241     * @return Resulting value.
242     */
243    public int getAttributeResourceValue(int index, int defaultValue);
244
245    /**
246     * Return the integer 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 int getAttributeIntValue(int index, int defaultValue);
254
255    /**
256     * Return the integer value of attribute at 'index' that is formatted as an
257     * unsigned value.  In particular, the formats 0xn...n and #n...n are
258     * handled.
259     *
260     * @param index Index of the desired attribute, 0...count-1.
261     * @param defaultValue What to return if the attribute isn't found.
262     *
263     * @return Resulting value.
264     */
265    public int getAttributeUnsignedIntValue(int index, int defaultValue);
266
267    /**
268     * Return the float value of attribute at 'index'.
269     *
270     * @param index Index of the desired attribute, 0...count-1.
271     * @param defaultValue What to return if the attribute isn't found.
272     *
273     * @return Resulting value.
274     */
275    public float getAttributeFloatValue(int index, float defaultValue);
276
277    /**
278     * Return the value of the "id" attribute or null if there is not one.
279     * Equivalent to getAttributeValue(null, "id").
280     *
281     * @return The id attribute's value or null.
282     */
283    public String getIdAttribute();
284
285    /**
286     * Return the value of the "class" attribute or null if there is not one.
287     * Equivalent to getAttributeValue(null, "class").
288     *
289     * @return The class attribute's value or null.
290     */
291    public String getClassAttribute();
292
293    /**
294     * Return the integer value of the "id" attribute or defaultValue if there
295     * is none.
296     * Equivalent to getAttributeResourceValue(null, "id", defaultValue);
297     *
298     * @param defaultValue What to return if the "id" attribute isn't found.
299     * @return int Resulting value.
300     */
301    public int getIdAttributeResourceValue(int defaultValue);
302
303    /**
304
305     * Return the value of the "style" attribute or 0 if there is not one.
306     * Equivalent to getAttributeResourceValue(null, "style").
307     *
308     * @return The style attribute's resource identifier or 0.
309     */
310    public int getStyleAttribute();
311}
312