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 
17 package android.util;
18 
19 
20 import 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  */
62 public 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      */
getAttributeCount()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      */
getAttributeNamespace(int index)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      */
getAttributeName(int index)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      */
getAttributeValue(int index)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      */
getAttributeValue(String namespace, String name)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      */
getPositionDescription()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      */
getAttributeNameResource(int index)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      */
getAttributeListValue(String namespace, String attribute, String[] options, int defaultValue)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      */
getAttributeBooleanValue(String namespace, String attribute, boolean defaultValue)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      */
getAttributeResourceValue(String namespace, String attribute, int defaultValue)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      */
getAttributeIntValue(String namespace, String attribute, int defaultValue)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      */
getAttributeUnsignedIntValue(String namespace, String attribute, int defaultValue)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      */
getAttributeFloatValue(String namespace, String attribute, float defaultValue)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      */
getAttributeListValue(int index, String[] options, int defaultValue)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      */
getAttributeBooleanValue(int index, boolean defaultValue)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      */
getAttributeResourceValue(int index, int defaultValue)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      */
getAttributeIntValue(int index, int defaultValue)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      */
getAttributeUnsignedIntValue(int index, int defaultValue)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      */
getAttributeFloatValue(int index, float defaultValue)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      */
getIdAttribute()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      */
getClassAttribute()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      */
getIdAttributeResourceValue(int defaultValue)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      */
getStyleAttribute()336     public int getStyleAttribute();
337 }
338