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 */ 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
