The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | |
Dianne Hackborn | 12ff371 | 2018-02-08 17:47:53 -0800 | [diff] [blame] | 20 | import org.xmlpull.v1.XmlPullParser; |
| 21 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 |
Dirk Dougherty | 6b13bc0 | 2009-10-30 19:05:53 -0700 | [diff] [blame] | 39 | * Xml.asAttributeSet()}. Normally this will return an implementation |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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> |
Chet Haase | d430753 | 2014-12-01 06:32:38 -0800 | [diff] [blame] | 44 | * XmlPullParser parser = resources.getXml(myResource); |
Dirk Dougherty | 6b13bc0 | 2009-10-30 19:05:53 -0700 | [diff] [blame] | 45 | * AttributeSet attributes = Xml.asAttributeSet(parser);</pre> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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. |
Dianne Hackborn | 12ff371 | 2018-02-08 17:47:53 -0800 | [diff] [blame] | 59 | * |
| 60 | * @see XmlPullParser |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 61 | */ |
| 62 | public interface AttributeSet { |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 63 | /** |
| 64 | * Returns the number of attributes available in the set. |
Dianne Hackborn | 12ff371 | 2018-02-08 17:47:53 -0800 | [diff] [blame] | 65 | * |
| 66 | * <p>See also {@link XmlPullParser#getAttributeCount XmlPullParser.getAttributeCount()}, |
| 67 | * which this method corresponds to when parsing a compiled XML file.</p> |
| 68 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 69 | * @return A positive integer, or 0 if the set is empty. |
| 70 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 71 | public int getAttributeCount(); |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 72 | |
| 73 | /** |
Dianne Hackborn | 12ff371 | 2018-02-08 17:47:53 -0800 | [diff] [blame] | 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 | /** |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 90 | * Returns the name of the specified attribute. |
Dianne Hackborn | 12ff371 | 2018-02-08 17:47:53 -0800 | [diff] [blame] | 91 | * |
| 92 | * <p>See also {@link XmlPullParser#getAttributeName XmlPullParser.getAttributeName()}, |
| 93 | * which this method corresponds to when parsing a compiled XML file.</p> |
| 94 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 100 | public String getAttributeName(int index); |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 110 | public String getAttributeValue(int index); |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 122 | public String getAttributeValue(String namespace, String name); |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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'. |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 152 | * |
| 153 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 167 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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} |
kmccormick | 50e27c8 | 2013-03-28 16:33:11 -0700 | [diff] [blame] | 180 | * in that it returns the value contained in this attribute as a |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 185 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 197 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 211 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | * |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 223 | * @param namespace Namespace of attribute to retrieve. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 243 | public int getAttributeListValue(int index, String[] options, int defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 253 | public boolean getAttributeBooleanValue(int index, boolean defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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} |
kmccormick | 50e27c8 | 2013-03-28 16:33:11 -0700 | [diff] [blame] | 259 | * in that it returns the value contained in this attribute as a |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 269 | public int getAttributeResourceValue(int index, int defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 279 | public int getAttributeIntValue(int index, int defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 291 | public int getAttributeUnsignedIntValue(int index, int defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Romain Guy | d379d53 | 2011-02-22 11:32:29 -0800 | [diff] [blame] | 301 | public float getAttributeFloatValue(int index, float defaultValue); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | } |