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    public int getAttributeCount();
60    public String getAttributeName(int index);
61    public String getAttributeValue(int index);
62    public String getAttributeValue(String namespace, String name);
63    public String getPositionDescription();
64
65    /**
66     * Return the resource ID associated with the given attribute name.  This
67     * will be the identifier for an attribute resource, which can be used by
68     * styles.  Returns 0 if there is no resource associated with this
69     * attribute.
70     *
71     * <p>Note that this is different than {@link #getAttributeResourceValue}
72     * in that it returns a resource identifier for the attribute name; the
73     * other method returns this attribute's value as a resource identifier.
74     *
75     * @param index Index of the desired attribute, 0...count-1.
76     *
77     * @return The resource identifier, 0 if none.
78     */
79    public int getAttributeNameResource(int index);
80
81    /**
82     * Return the index of the value of 'attribute' in the list 'options'.
83     *
84     * @param attribute Name of attribute to retrieve.
85     * @param options List of strings whose values we are checking against.
86     * @param defaultValue Value returned if attribute doesn't exist or no
87     *                     match is found.
88     *
89     * @return Index in to 'options' or defaultValue.
90     */
91    public int getAttributeListValue(String namespace, String attribute,
92                                     String[] options, int defaultValue);
93
94    /**
95     * Return the boolean value of 'attribute'.
96     *
97     * @param attribute The attribute to retrieve.
98     * @param defaultValue What to return if the attribute isn't found.
99     *
100     * @return Resulting value.
101     */
102    public boolean getAttributeBooleanValue(String namespace, String attribute,
103                                            boolean defaultValue);
104
105    /**
106     * Return the value of 'attribute' as a resource identifier.
107     *
108     * <p>Note that this is different than {@link #getAttributeNameResource}
109     * in that it returns a the value contained in this attribute as a
110     * resource identifier (i.e., a value originally of the form
111     * "@package:type/resource"); the other method returns a resource
112     * identifier that identifies the name of the attribute.
113     *
114     * @param attribute The attribute to retrieve.
115     * @param defaultValue What to return if the attribute isn't found.
116     *
117     * @return Resulting value.
118     */
119    public int getAttributeResourceValue(String namespace, String attribute,
120                                         int defaultValue);
121
122    /**
123     * Return the integer value of 'attribute'.
124     *
125     * @param attribute The attribute to retrieve.
126     * @param defaultValue What to return if the attribute isn't found.
127     *
128     * @return Resulting value.
129     */
130    public int getAttributeIntValue(String namespace, String attribute,
131                                    int defaultValue);
132
133    /**
134     * Return the boolean value of 'attribute' that is formatted as an
135     * unsigned value.  In particular, the formats 0xn...n and #n...n are
136     * handled.
137     *
138     * @param attribute The attribute to retrieve.
139     * @param defaultValue What to return if the attribute isn't found.
140     *
141     * @return Resulting value.
142     */
143    public int getAttributeUnsignedIntValue(String namespace, String attribute,
144                                            int defaultValue);
145
146    /**
147     * Return the float value of 'attribute'.
148     *
149     * @param attribute The attribute to retrieve.
150     * @param defaultValue What to return if the attribute isn't found.
151     *
152     * @return Resulting value.
153     */
154    public float getAttributeFloatValue(String namespace, String attribute,
155                                        float defaultValue);
156
157    /**
158     * Return the index of the value of attribute at 'index' in the list
159     * 'options'.
160     *
161     * @param index Index of the desired attribute, 0...count-1.
162     * @param options List of strings whose values we are checking against.
163     * @param defaultValue Value returned if attribute doesn't exist or no
164     *                     match is found.
165     *
166     * @return Index in to 'options' or defaultValue.
167     */
168    public int getAttributeListValue(int index,
169                                     String[] options, int defaultValue);
170
171    /**
172     * Return the boolean value of attribute at 'index'.
173     *
174     * @param index Index of the desired attribute, 0...count-1.
175     * @param defaultValue What to return if the attribute isn't found.
176     *
177     * @return Resulting value.
178     */
179    public boolean getAttributeBooleanValue(int index,
180                                            boolean defaultValue);
181
182    /**
183     * Return the value of attribute at 'index' as a resource identifier.
184     *
185     * <p>Note that this is different than {@link #getAttributeNameResource}
186     * in that it returns a the value contained in this attribute as a
187     * resource identifier (i.e., a value originally of the form
188     * "@package:type/resource"); the other method returns a resource
189     * identifier that identifies the name of the attribute.
190     *
191     * @param index Index of the desired attribute, 0...count-1.
192     * @param defaultValue What to return if the attribute isn't found.
193     *
194     * @return Resulting value.
195     */
196    public int getAttributeResourceValue(int index,
197                                         int defaultValue);
198
199    /**
200     * Return the integer value of attribute at 'index'.
201     *
202     * @param index Index of the desired attribute, 0...count-1.
203     * @param defaultValue What to return if the attribute isn't found.
204     *
205     * @return Resulting value.
206     */
207    public int getAttributeIntValue(int index,
208                                    int defaultValue);
209
210    /**
211     * Return the integer value of attribute at 'index' that is formatted as an
212     * unsigned value.  In particular, the formats 0xn...n and #n...n are
213     * handled.
214     *
215     * @param index Index of the desired attribute, 0...count-1.
216     * @param defaultValue What to return if the attribute isn't found.
217     *
218     * @return Resulting value.
219     */
220    public int getAttributeUnsignedIntValue(int index,
221                                            int defaultValue);
222
223    /**
224     * Return the float value of attribute at 'index'.
225     *
226     * @param index Index of the desired attribute, 0...count-1.
227     * @param defaultValue What to return if the attribute isn't found.
228     *
229     * @return Resulting value.
230     */
231    public float getAttributeFloatValue(int index,
232                                        float defaultValue);
233
234    /**
235     * Return the value of the "id" attribute or null if there is not one.
236     * Equivalent to getAttributeValue(null, "id").
237     *
238     * @return The id attribute's value or null.
239     */
240    public String getIdAttribute();
241
242    /**
243     * Return the value of the "class" attribute or null if there is not one.
244     * Equivalent to getAttributeValue(null, "class").
245     *
246     * @return The class attribute's value or null.
247     */
248    public String getClassAttribute();
249
250    /**
251     * Return the integer value of the "id" attribute or defaultValue if there
252     * is none.
253     * Equivalent to getAttributeResourceValue(null, "id", defaultValue);
254     *
255     * @param defaultValue What to return if the "id" attribute isn't found.
256     * @return int Resulting value.
257     */
258    public int getIdAttributeResourceValue(int defaultValue);
259
260    /**
261
262     * Return the value of the "style" attribute or 0 if there is not one.
263     * Equivalent to getAttributeResourceValue(null, "style").
264     *
265     * @return The style attribute's resource identifier or 0.
266     */
267    public int getStyleAttribute();
268}
269
270