Technical docs‎ > ‎

Tools Attributes







Android has a dedicated XML namespace intended for tools to be able to record information in XML files, and have that information stripped when the application is packaged such that there is no runtime or download size penalty. The namespace URI is http://schemas.android.com/tools and is usually bound to the tools: prefix:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent" >
    ....

This document records our current uses of tools attributes. (NOTE: These may change over time.)

tools:ignore

This attribute can be set on any XML element, and is a comma separated list of lint issue ID's that should be ignored on this element or any of its children, recursively.
<string name="show_all_apps" tools:ignore="MissingTranslation">All</string>

Used by: Lint

tools:targetApi

This attribute is like the @TargetApi annotation in Java classes: it lets you specify an API level, either as an integer or as code name, that this element is known to be running on.

    <GridLayout tools:targetApi="ICE_CREAM_SANDWICH" >

Used by: Lint

tools:locale

This attribute can be set on the root element in a resource value file and should correspond to a language and optionally a region. This will let tools know what language (locale) the strings in the file are assumed to be. For example, values/strings.xml can have this root element:

<resources xmlns:tools="http://schemas.android.com/tools" tools:locale="es">
Now we know that the language used for strings in the default values folder is Spanish rather than English.

Used by: Lint, Studio (to disable spell checking in non-English resource files)

tools:context

This attribute is typically set on the root element in a layout XML file, and records which activity the layout is associated with (at designtime, since obviously a layout can be used by more than one layout). This will for example be used by the layout editor to guess a default theme, since themes are defined in the Manifest and are associated with activities, not layouts. You can use the same dot prefix as in manifests to just specify the activity class without the full application package name as a prefix.
<android.support.v7.widget.GridLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"
    tools:context=".MainActivity" ... >

Used by: Layout editors in Studio & Eclipse, Lint

tools:layout

This attribute is typically set in a <fragment> tag and is used to record which layout you want to see rendered at designtime (at runtime, this will be determined by the actions of the fragment class listed by the tag).
<fragment android:name="com.example.master.ItemListFragment" tools:layout="@android:layout/list_content" />

Used by: Layout editors in Studio & Eclipse

tools:listitem / listheader / listfooter

These attributes can be used on a <ListView> (or other AdapterView children like <GridView>, <ExpandableListView> etc) to specify layouts to use for the list items, as well as list headers and list footers, at designtime. The tool will fill in dummy data to show a list with some representative contents.
    <ListView
        android:id="@android:id/list"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:listitem="@android:layout/simple_list_item_2" />

Used by: Layout editors in Studio & Eclipse

tools:showIn

Attribute set on the root element of a layout that <include>'ed by another layout. This allows you to point to one of the layouts which includes this layout, and at designtime this included layout will be rendered with the outer layout surrounding it. That allows you to view and edit the layout "in context".  Requires Studio 0.5.8 or later. More information in the release announcement.
<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:text="@string/hello_world"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    tools:showIn="@layout/activity_main" />
Used by: Layout editor in Studio

tools:menu

Attribute set on the root element of a layout to configure the menus to be shown in the Action Bar. Android Studio tries to figure out which menus to use in the ActionBar by looking at the onCreateOptionsMenu() method in the activity linked to the layout (by tools:context). This allows you to override that search and explicitly state which menus to show. The value is a comma separated list of ids (without @id/ or any such prefix). You can also use the file names of the menu xml without the .xml extension. Requires Studio 0.8.0 or later.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:menu="menu1,menu2" />
Used by: Layout editor in Studio

tools:actionBarNavMode

Attribute set on the root element of a layout to configure the navigation mode used by the Action Bar. Possible values include: "standard", "list" and "tabs" Requires Studio 0.8.0 or later.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:actionBarNavMode="tabs" />
Used by: Layout editor in Studio

tools:shrinkMode

When using resource shrinking to automatically strip out unused resources, you can specify whether the Gradle plugin should play it safe and whitelist all resources that might be referenced via a getIdentifier lookup from string resources, or whether it should only consider resources explicitly listed in code and in other resources. The default is to play it safe; this is shrinkMode="safe". To instead have the Gradle plugin only consider explicitly referenced resources, use shrinkMode="strict". In that case, you can use the tools:keep and tools:discard attributes to explicitly list resources to keep or remove.

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:shrinkMode="safe"
    tools:discard="@layout/unused2" />

Used by: Gradle plugin with resource shrinking. More information about resource shrinking.

tools:keep

When using resource shrinking to automatically strip out unused resources, and when using shrinkMode="strict", you can specify specific resources to keep (typically because they are referenced in an indirect way via runtime code, such as Resources#getIdentifier(some dynamically computed resource name). 

The value is a comma separated list of resource references (and a globbing pattern is allowed.)

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/l_used*_c,@layout/l_used_a,@layout/l_used_b*" />

Used by: Gradle plugin with resource shrinking. More information about resource shrinking.

tools:discard

When using resource shrinking to automatically strip out unused resources, you can specify specific resources to discard (typically because the resource is referenced in some way that you know does not affect your app, or the Gradle plugin has incorrectly deduced that the resource is referenced (which can happen because resource identifiers are inlined by the compiler, so the resource analyzer can't tell the difference between a genuinely referenced resource and an integer value in the program that happens to have the same value.)

The value is a comma separated list of resource references (and a globbing pattern is allowed.)

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:discard="@layout/unused2" />
Used by: Gradle plugin with resource shrinking. More information about resource shrinking.

Other: Designtime Attributes

In layouts, any other attribute can be aliasing a builtin Android attribute. For example, this can let you set a designtime-only alternate text which is used in the tools, but not at runtime. For more, see Designtime Layout Attributes.

Comments