Java tutorial
/* * Copyright (C) 2006 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.util; import org.xmlpull.v1.XmlPullParser; /** * A collection of attributes, as found associated with a tag in an XML * document. Often you will not want to use this interface directly, instead * passing it to {@link android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int) * Resources.Theme.obtainStyledAttributes()} * which will take care of parsing the attributes for you. In particular, * the Resources API will convert resource references (attribute values such as * "@string/my_label" in the original XML) to the desired type * for you; if you use AttributeSet directly then you will need to manually * check for resource references * (with {@link #getAttributeResourceValue(int, int)}) and do the resource * lookup yourself if needed. Direct use of AttributeSet also prevents the * application of themes and styles when retrieving attribute values. * * <p>This interface provides an efficient mechanism for retrieving * data from compiled XML files, which can be retrieved for a particular * XmlPullParser through {@link Xml#asAttributeSet * Xml.asAttributeSet()}. Normally this will return an implementation * of the interface that works on top of a generic XmlPullParser, however it * is more useful in conjunction with compiled XML resources: * * <pre> * XmlPullParser parser = resources.getXml(myResource); * AttributeSet attributes = Xml.asAttributeSet(parser);</pre> * * <p>The implementation returned here, unlike using * the implementation on top of a generic XmlPullParser, * is highly optimized by retrieving pre-computed information that was * generated by aapt when compiling your resources. For example, * the {@link #getAttributeFloatValue(int, float)} method returns a floating * point number previous stored in the compiled resource instead of parsing * at runtime the string originally in the XML file. * * <p>This interface also provides additional information contained in the * compiled XML resource that is not available in a normal XML file, such * as {@link #getAttributeNameResource(int)} which returns the resource * identifier associated with a particular XML attribute name. * * @see XmlPullParser */ public interface AttributeSet { /** * Returns the number of attributes available in the set. * * <p>See also {@link XmlPullParser#getAttributeCount XmlPullParser.getAttributeCount()}, * which this method corresponds to when parsing a compiled XML file.</p> * * @return A positive integer, or 0 if the set is empty. */ public int getAttributeCount(); /** * Returns the namespace of the specified attribute. * * <p>See also {@link XmlPullParser#getAttributeNamespace XmlPullParser.getAttributeNamespace()}, * which this method corresponds to when parsing a compiled XML file.</p> * * @param index Index of the desired attribute, 0...count-1. * * @return A String containing the namespace of the attribute, or null if th * attribute cannot be found. */ default String getAttributeNamespace(int index) { // This is a new method since the first interface definition, so add stub impl. return null; } /** * Returns the name of the specified attribute. * * <p>See also {@link XmlPullParser#getAttributeName XmlPullParser.getAttributeName()}, * which this method corresponds to when parsing a compiled XML file.</p> * * @param index Index of the desired attribute, 0...count-1. * * @return A String containing the name of the attribute, or null if the * attribute cannot be found. */ public String getAttributeName(int index); /** * Returns the value of the specified attribute as a string representation. * * @param index Index of the desired attribute, 0...count-1. * * @return A String containing the value of the attribute, or null if the * attribute cannot be found. */ public String getAttributeValue(int index); /** * Returns the value of the specified attribute as a string representation. * The lookup is performed using the attribute name. * * @param namespace The namespace of the attribute to get the value from. * @param name The name of the attribute to get the value from. * * @return A String containing the value of the attribute, or null if the * attribute cannot be found. */ public String getAttributeValue(String namespace, String name); /** * Returns a description of the current position of the attribute set. * For instance, if the attribute set is loaded from an XML document, * the position description could indicate the current line number. * * @return A string representation of the current position in the set, * may be null. */ public String getPositionDescription(); /** * Return the resource ID associated with the given attribute name. This * will be the identifier for an attribute resource, which can be used by * styles. Returns 0 if there is no resource associated with this * attribute. * * <p>Note that this is different than {@link #getAttributeResourceValue} * in that it returns a resource identifier for the attribute name; the * other method returns this attribute's value as a resource identifier. * * @param index Index of the desired attribute, 0...count-1. * * @return The resource identifier, 0 if none. */ public int getAttributeNameResource(int index); /** * Return the index of the value of 'attribute' in the list 'options'. * * @param namespace Namespace of attribute to retrieve. * @param attribute Name of attribute to retrieve. * @param options List of strings whose values we are checking against. * @param defaultValue Value returned if attribute doesn't exist or no * match is found. * * @return Index in to 'options' or defaultValue. */ public int getAttributeListValue(String namespace, String attribute, String[] options, int defaultValue); /** * Return the boolean value of 'attribute'. * * @param namespace Namespace of attribute to retrieve. * @param attribute The attribute to retrieve. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public boolean getAttributeBooleanValue(String namespace, String attribute, boolean defaultValue); /** * Return the value of 'attribute' as a resource identifier. * * <p>Note that this is different than {@link #getAttributeNameResource} * in that it returns the value contained in this attribute as a * resource identifier (i.e., a value originally of the form * "@package:type/resource"); the other method returns a resource * identifier that identifies the name of the attribute. * * @param namespace Namespace of attribute to retrieve. * @param attribute The attribute to retrieve. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeResourceValue(String namespace, String attribute, int defaultValue); /** * Return the integer value of 'attribute'. * * @param namespace Namespace of attribute to retrieve. * @param attribute The attribute to retrieve. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeIntValue(String namespace, String attribute, int defaultValue); /** * Return the boolean value of 'attribute' that is formatted as an * unsigned value. In particular, the formats 0xn...n and #n...n are * handled. * * @param namespace Namespace of attribute to retrieve. * @param attribute The attribute to retrieve. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeUnsignedIntValue(String namespace, String attribute, int defaultValue); /** * Return the float value of 'attribute'. * * @param namespace Namespace of attribute to retrieve. * @param attribute The attribute to retrieve. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public float getAttributeFloatValue(String namespace, String attribute, float defaultValue); /** * Return the index of the value of attribute at 'index' in the list * 'options'. * * @param index Index of the desired attribute, 0...count-1. * @param options List of strings whose values we are checking against. * @param defaultValue Value returned if attribute doesn't exist or no * match is found. * * @return Index in to 'options' or defaultValue. */ public int getAttributeListValue(int index, String[] options, int defaultValue); /** * Return the boolean value of attribute at 'index'. * * @param index Index of the desired attribute, 0...count-1. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public boolean getAttributeBooleanValue(int index, boolean defaultValue); /** * Return the value of attribute at 'index' as a resource identifier. * * <p>Note that this is different than {@link #getAttributeNameResource} * in that it returns the value contained in this attribute as a * resource identifier (i.e., a value originally of the form * "@package:type/resource"); the other method returns a resource * identifier that identifies the name of the attribute. * * @param index Index of the desired attribute, 0...count-1. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeResourceValue(int index, int defaultValue); /** * Return the integer value of attribute at 'index'. * * @param index Index of the desired attribute, 0...count-1. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeIntValue(int index, int defaultValue); /** * Return the integer value of attribute at 'index' that is formatted as an * unsigned value. In particular, the formats 0xn...n and #n...n are * handled. * * @param index Index of the desired attribute, 0...count-1. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public int getAttributeUnsignedIntValue(int index, int defaultValue); /** * Return the float value of attribute at 'index'. * * @param index Index of the desired attribute, 0...count-1. * @param defaultValue What to return if the attribute isn't found. * * @return Resulting value. */ public float getAttributeFloatValue(int index, float defaultValue); /** * Return the value of the "id" attribute or null if there is not one. * Equivalent to getAttributeValue(null, "id"). * * @return The id attribute's value or null. */ public String getIdAttribute(); /** * Return the value of the "class" attribute or null if there is not one. * Equivalent to getAttributeValue(null, "class"). * * @return The class attribute's value or null. */ public String getClassAttribute(); /** * Return the integer value of the "id" attribute or defaultValue if there * is none. * Equivalent to getAttributeResourceValue(null, "id", defaultValue); * * @param defaultValue What to return if the "id" attribute isn't found. * @return int Resulting value. */ public int getIdAttributeResourceValue(int defaultValue); /** * Return the value of the "style" attribute or 0 if there is not one. * Equivalent to getAttributeResourceValue(null, "style"). * * @return The style attribute's resource identifier or 0. */ public int getStyleAttribute(); }