Develop Reference

Where is the documentation for Android resource XML's `<attr>` element?

I was reading Ha Duy Trung's tutorial Supporting multiple themes in your Android app and in it he has the following snippet for values/attrs.xml:
<attr name="themedMenuStoryDrawable" format="reference" />
<attr name="themedMenuCommentDrawable" format="reference" />
Where is this <attr> element actually documented? Looking in the Android API Guide Providing Resources, I cannot find any mention of this type of element.
I did find a mention of <attr> elements in Creating a View Class, but there they all appear inside of <declare-styleable> elements, and there is hardly any explanation of how these elements work.
Is there proper reference documentation for the <attr> element? If not, then:
What does it mean to have an <attr> element directly under <resources>?
What is the meaning of the format attribute, and what values can it take?
What other XML attributes can <attr> take?
Can <attr> appear as the child of anything other than <resources> and <declare-styleable>?
I'd specifically like to know how to use <attr> in the context of theming (rather than custom views) though documentation of how it works in general would be even better.

Xamarin custom attribute of reference type does not work

I'm trying to create a custom attribute for my control. Here's my attrs.xml:
<?xml version="1.0" encoding="utf-8" ?>
<resources>
<declare-styleable name="ImageView">
<attr name="testcustom" format="reference"/>
</declare-styleable>
</resources>
In my test app at root, I add this namespace xmlns:TestCustom="http://schemas.android.com/apk/res-auto"
Later in my layout file I have an image view
<ImageView
android:src="#drawable/Icon"
TestCustom:testcustom="#drawable/Icon"/>
The first android:src property is fine, however TestCustom does not work.
The error given is "No resource found that matches the given name (at 'testcustom' with value '#drawable/icon)
So... what's going on here? Anyone have any ideas?

You need to specify your xmlns: to your specific package namespace. For example:
xmlns:custom="http://schemas.android.com/apk/res/com.example.customviews"
Represents custom: for the package namespace of com.example.customviews.
You can read more about this here: https://developer.android.com/training/custom-views/create-view.html#customattr
Note: You may want to consider following the convention of camelCase with regards to your custom attributes, views, etc.

So to recap: The solution here was to use lower case name when referencing the resource via a custom attribute. Apparently Xamarin is doing some work in the background that normally allows resources that start with upper case to be OK, but it probably doesn't address this for custom attributes.
If you are using Xamarin, and custom attributes and you can't reference your resource, try it in lower case!!!
Or as Jon recommends, don't use upper-case stuff at all for resources.

How does "?android:attr/activatedBackgroundIndicator" work?

I was looking for how to highlight a selected item in a list when displaying a contextual action bar for the selection, and the solution I found was to set the android:background attribute of my row layout xml to "?android:attr/activatedBackgroundIndicator".
How does setting this work though?
what is the mechanism involved?
what do the syntax elements like "?", "attr", "activatedBackgroundIndicator" mean?
where is the meaning of "activatedBackgroundIndicator" defined?

If you are in a forensic mood here is how to dig and find out what is going on.
android:background="?android:attr/activatedBackgroundIndicator"?
Intuitively this means set the background to some drawable.
But lets decompose this further to see how we get to our mysterious drawable.
To be precise it means "set the background attribute to what the attribute "activatedBackgroundIndicator" refers to in the current theme.
If you understand "refers to in the current theme" part, you have basically understood everything that is going on behind the covers.
Basically, activatedBackgroundIndicator is not an actual drawable but a reference to a drawable. So where is "activateBackgroundIndictor" attribute actually defined?
Its defined in your sdk directory in a file name attrs.xml. For example:
path_to_android_sdk/platforms/android-17/data/res/values/attrs.xml
If you open that file, you will the declaration as follows:
<attr name="activatedBackgroundIndicator" format="reference" />
attrs.xml is where you declare all the attributes that you are later going to use in your view xml. Note we are declaring the attribute and its type and not actually assigning a value here.
The actual value is assigned in themes.xml. This file is located at:
path_to_android_sdk/platforms/android-17/data/res/values/themes.xml
If you open that file, you will see the multiple definitions depending on what theme you are using. For example, here are the definitions for themes name Theme, Theme.Light, Theme.Holo, Theme.Holo.Light respectively:
<item name="activatedBackgroundIndicator">#android:drawable/activated_background</item>
<item name="activatedBackgroundIndicator">#android:drawable/activated_background_light</item>
<item name="activatedBackgroundIndicator">#android:drawable/activated_background_holo_dark</item>
<item name="activatedBackgroundIndicator">#android:drawable/activated_background_holo_light</item>
Now we have our mysterious drawables. If you pick the first one, it is defined in the drawable folder at:
path_to_android_sdk/platforms/android-17/data/res/drawable/activated_background.xml
If you open that file you will see the definition of the drawable which is important to understanding what is going on.
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_activated="true" android:drawable="#android:drawable/list_selector_background_selected" />
<item android:drawable="#color/transparent" />
</selector>
Here we are defining a drawable with two states - default state is just transparent background and if the state is "state_activated" then our drawable is "list_selector_background_selected".
see this link for background information on on drawables and states.
"list_selector_background_selected" is a 9 patch png file that is located in the drawable-hdpi folder.
Now you can see why we defined activatedBackgroundIndicator as a reference rather than linking directly to the drawable file - it allows you to pick the right drawable depending on your theme.

I wondered this as well at one point. A large amount of the Android resources seem to be like a black-box and can't see them directly. I may be missing them someplace, but I can't find them in the SDK source code. Here is what I do know.
android:background will take a drawable.
The syntax is in the style
Must be a reference to another resource, in the form "#[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name"
In this case the ? signifies to look at a theme in package android and it is of type attr where the name is activatedBackgroundIndicator.
You should be able to access this in the code-behind with android.R.attr.activatedBackgroundIndicator as well.
A list of Android attr properties can be found at R.attr
activatedBackgroundIndicator is a defined drawable in Android 3.0+ as
Drawable used as a background for activated items.
It's basically just a standard item defined in the OS. I can't seem to find in in the Android source, but here is a link to the documentation. activatedBackgroundIndicator

This is a form of attaching a value from a theme. The value is technically not known during resource compilation because the theme values may not be known at that point. Instead the value is resolved at runtime based on the actual theme taken from (most commonly) ContextThemeWrapper.
This provides a way of reusing resource values. I'm not talking performance-wise here, but rather organization and maintenance-wise. The attribute acts as it were a variable with the promise that it will hold an actual value at runtime.
This approach also allows for greater customization - instead of hardcoding the value of e.g. window background drawable it gets the actual drawable from a theme, supplying a chosen attribute as the key. This lets you override the value for that attribute. You simply need to:
Create your own theme (which is just a fancy name for a "style" resource), most commonly deriving from one of default themes.
Supply your own value for the attribute in question.
The platform will automatically use your value provided that you have specified your theme for an activity or application. You do this like described in the question. The general syntax of theme-attribute references is described here: Referencing style attributes. You will also find an example and description of the whole mechanism there.
Edit
One thing that should be noted is the actual attribute names and their existence in various platform versions. It's fairly common for new attributes to be introduced in next platform versions - for example some were added in version 3.0 for the purpose of ActionBar styling.
You should treat attribute names as part of the API - in other words, they are part of the contract you are allowed to use. This is very similar to classes and their signatures - you use LocationManager class for the purpose of obtaining last device location because you know from some source (tutorials, reference, official guides, etc.) what's the purpose of this class. Similarly, the attribute names and their purpose are (sometimes well, sometimes miserably) defined in the Android Platform documentation.

Update: There is a more detailed version available from the API Guide so I'd like to quote it.
A style attribute resource allows you to reference the value of an attribute in the currently-applied theme. Referencing a style attribute allows you to customize the look of UI elements by styling them to match standard variations supplied by the current theme, instead of supplying a hard-coded value. Referencing a style attribute essentially says, "use the style that is defined by this attribute, in the current theme."
To reference a style attribute, the name syntax is almost identical to the normal resource format, but instead of the at-symbol (#), use a question-mark (?), and the resource type portion is optional. For instance:`
Original Answer:
numan salati already offered an perfect answer but it have not addressed the "?" syntax. Here's a quote from API Guide Accessing Resources
To reference a style attribute, the name syntax is almost identical to the normal resource format, but instead of the at-symbol (#), use a question-mark (?), and the resource type portion is optional. For instance:
?[<package_name>:][<resource_type>/]<resource_name>

Do com.android.internal.R.attr and android.R.attr have the same set of values?

I need to use a built in value from Android resources. This value is stored com.android.internal.R.attr.listViewStyle. Being unable to get that from within my code, I tried to find the appropriate value I can use insted. Well, I've just found android.R.attr.listViewStyle.
Question 1: Are these values same?
Question 2: Where can I find the XML for com.android.internal.R.attr.listViewStyle? May be I have to create my own style instead that one. In order to find it out I should look at that file.
Sorry if these questions are silly. I'm new to Android development yet.

com.android.internal classes are internal to android, they are only accessible within frameworks.
I think com.android.internal.R.attr.listViewStyle and android.R.attr.listViewStyle are same.
If you want to create your own style you can check here . This contains two listViewStyle. They are used based on the device default theme(Light or dark).
If you want to use this style, then i think you dont need to specify anything in your code, this is default theme, so it is picked automatically, if no attributes are specified.

You can add listViewStyle in values/attr.xml with this code :
<attr name="listViewStyle" format="reference" />
Change com.android.internal.R.attr.listViewStyle in your code to R.attr.listViewStyle
I find it in this
Example for attr.xml
< ?xml version="1.0" encoding="utf-8"?>
< resources>
< attr name="listViewStyle" format="reference" />
</resources>

Can someone explain me declare-styleable XML tag in this example and the theory behind its use?

I'm reading Beginning Android 4 Development and in chapter 5 it talks about Gallery and ImageVievs and introduces the declare-styleable XML tag without explaining its purpose.. I tried to find some info also on the reference, without luck.. For example we have the following:
res/values/attrs.xml
<?xml version=”1.0” encoding=”utf-8”?>
<resources>
<declare-styleable name=”Gallery1”>
<attr name=”android:galleryItemBackground” />
</declare-styleable>
</resources>
example.java
public class GalleryActivity extends Activity {
[...]
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
Gallery gallery = (Gallery) findViewById(R.id.gallery1);
gallery.setAdapter(new ImageAdapter(this));
[...]
}
[...]
public class ImageAdapter extends BaseAdapter {
[...]
int itemBackground;
public ImageAdapter(Context c) {
context = c;
//---setting the style---
TypedArray a = obtainStyledAttributes(
R.styleable.Gallery1);
itemBackground = a.getResourceId(
R.styleable.Gallery1_android_galleryItemBackground, 0);
a.recycle();
}
public View getView(int position, View convertView, ViewGroup parent) {
ImageView imageView;
[...]
imageView.setBackgroundResource(itemBackground);
return imageView;
}
}
}
I've read the code a few times and I don't really understand the purpose of defining this styleable Gallery1 with a single attr child only with a name attribute.. can you help me? Is this galleryItemBackground something provided by the system or is it something defined by us? What are we doing in this piece of code?
Thank you in advance for any help!

This tag is part of a set of premade Android attributes defined in R.Styleable, which can be told apart from a custom styleable tag from the android: xml namespace prefix before the attribute name.
This particular attribute is described as:
The preferred background for gallery items. This should be set as the
background of any Views you provide from the Adapter.
You are right, however, that custom attribute tags would require not only the name of the attribute but what its type is, for example adding a custom element to your attrs.xml file might look like this:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<declare-styleable name="MyCustomView">
<attr name=”android:galleryItemBackground” />
<attr name="myCustomAttr" format="string" />
</declare-styleable>
</resources>
Note the lack of the android: namespace on the second attribute as well.
Edit:
Is there any official documentation page that explains in depth this
Styleables?
Check out R.attr (click for link) for various attributes included in Android. You do not need to declare a type for them, because they are all already declared. To know what type has been declared for a particular attribute, find the description for the one you are interested in. galleryItemBackground is, as you may expect, a reference to another resource; other possibilities are booleans, floats, colors, etc.
Additional references: Andtoid uses the <declare-styleable> tag to create an AttributeSet. TypedArray is used to parse the AttributeSet.
If the purpose of the code above [...] is simply get a default
Drawable for the view's background, couldn't I set the variable
itemBackground with getDrawable(android.R.attr.galleryItemBackground)?
In the example, it is hard to see the usefulness of this pattern when there is only one attribute. You can do what you ask, and it may be easier. The construct, however, is part of Android's mantra to separate the UI's "look" from its "functionaly" by letting you set certain attributes in xml instead of having to do everything in code. Take the View class, for example. It has over 30 attributes that can be set in an xml file (size, padding, clickable, focusable, etc); someone making a custom subclass of View can set a few, all or none of these attributes in xml and they are automatically handled for you when the view is created. There are code equivalents to set the attributes if needed, but imagine every time you subclassed View you HAD to set all attributes in code instead of having an option to set them in xml.
It would also be a trivial matter to just make your own resources for your classes that do exactly the same thing, however using the built in styles will provide default resources that match the look and feel of the Android framework if you do not override them.
Hope this helps.