How to compose an 'attrs.xml' in android?

There are a lot of blogs which describe how to create custom attributes [3-5]. But I couldn't find anyone which describes the syntax and possible xml attributes for each of the elements inside it. Also, there aren't any documentations available for this as well!

In order to figure out this syntax, I had dig into some internal android code! I know that android is open-source. I like open-source and it's cool. But one shouldn't have to dig into the code in order to understand this simple information, which could have been documented.

Thus this blog is an attempt from my side to document this feature, so as to keep others from wasting their time in doing the same!

declare-styleable

List of possible xml-attributes for this element:

1. name: name of this styleable.
2. parent: name of the styleable from which to inherit the attributes.

List of possible children:

1. attr: the attribute which needs to be defined inside this styleable.

attr

This element can either be found as a tag outside the 'declare-styleable' tag or as an child inside it. List of possible xml-attributes for this element:

1. name: name of this attribute.
2. format: data-type represented by this attribute. (This is optional)

List of possible children:

1. enum: If the current 'attr' is of type 'enum', then you have to define possible enumerations for this attribute.
2. flag: If the current 'attr' is of type 'flag', then you have to declare this.

enum

List of possible xml-attributes for this element:

1. name: name of the enum element.
2. value: the value to be used for this element.

flag

I'm still unable to figure out the syntax for this element. Whenever I'll find out, I'll update this section. So, please do check-back here for more info on this!

format

One small catch here! I just said that this is an optional attribute to 'attr' element. However, from the code [1] it seems that an 'attr' with not 'format' will be silently ignored! Hence, I would recommend putting one of the values below for this attribute. Possible values for 'format' attribute of 'attr' are: [2]

• reference
• string
• color
• dimension
• boolean
• integer
• float
• fraction
• enum
• flag

That said, an example should clarify much of the stuffs here. Given below is an example 'attrs.xml' which contains all the above elements/attributes. Go through this carefully in order to understand the syntax.

An example 'attrs.xml':

<resources>
    <attr name="global1" format="float"/>
    <declare-styleable name="parent-attr">
        <attr name="attr1" format="integer" />
        <attr name="global1" />
    </declare-styleable>
    <declare-styleable name="myattr" parent="parent-attr">
        <attr name="attr2" format="integer" />
        <attr name="attr3" format="enum">
            <enum name="name1" value="value1" />
            <enum name="name2" value="value2" />
        </attr>
    </declare-styleable>
    <declare-styleable>
        <attr name="global1" />
        <attr name="attr4" format="boolean"/>
    </declare-styleable>
</resources>

NOTE:

1. All the 'attr' elements in the current xml file will be parsed into a single 'Map'. So, you have to make sure that all 'attr' elements have unique names! [1]
2. However, if there is an 'attr' element which needs to be shared between 2 styleables, then make it global. (But make sure that you specify a 'format' for this!) Now inside the 'declare-styleable's where you want to define this 'attr', just put this without the 'format'. There is an example of this in the sample xml above. [1]

REFERENCES:

[1] http://code.google.com/p/idea-android/source/browse/trunk/src/org/jetbrains/android/dom/attrs/AttributeDefinitions.java?r=96

[2] http://code.google.com/p/idea-android/source/browse/trunk/src/org/jetbrains/android/dom/attrs/AttributeFormat.java?r=96
[3] http://developer.android.com/resources/samples/ApiDemos/res/values/attrs.html
[4] http://developer.android.com/resources/samples/ApiDemos/src/com/example/android/apis/view/LabelView.html
[5] http://blog.pocketjourney.com/2008/05/02/android-tutorial-42-passing-custom-variables-via-xml-resource-files/

PS: Please do leave comments if you find anything incorrect. I'll update the blog accordingly.