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