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