• Tools attributes reference
    • Error handling attributes
      • tools:ignore
      • tools:targetApi
      • tools:locale
    • Design-time view attributes
      • tools: instead of android:
      • tools:context
      • tools:itemCount
      • tools:layout
      • tools:listitem / tools:listheader / tools:listfooter
      • tools:showIn
      • tools:menu
      • tools:minValue / tools:maxValue
      • tools:openDrawer
      • "@tools:sample/*" resources
    • Resource shrinking attributes
      • tools:shrinkMode
      • tools:keep
      • tools:discard

    Tools attributes reference

    Android Studio supports a variety of XML attributes in the tools namespacethat enable design-time features (such as which layout to show in a fragment) orcompile-time behaviors (such as which shrinking mode to apply to your XMLresources). When you build your app, the build tools remove these attributes sothere is no effect on your APK size or runtime behavior.

    To use these attributes, add the tools namespace to the root element of eachXML file where you'd like to use them, as shown here:

    1. <RootTag xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools" >

    Error handling attributes

    The following attributes help suppress lint warning messages.

    tools:ignore

    Intended for: Any element

    Used by: Lint

    This attribute accepts a comma-separated list of lint issue ID's that you'd likethe tools to ignore on this element or any of its decendents.

    For example, you can tell the tools to ignore the MissingTranslation error:

    1. <string name="show_all_apps" tools:ignore="MissingTranslation">All</string>

    tools:targetApi

    Intended for: Any element

    Used by: Lint

    This attribute works the same as the@TargetApi annotation in Javacode: it lets you specify the API level (either as an integer or as a code name)that supports this element.

    This tells the tools that you believe this element (and any children) will beused only on the specified API level or higher. This stops lint from warning youif that element or its attributes are not available on the API level you specifyas your minSdkVersion.

    For example, you might use this becauseGridLayout is available only onAPI level 14 and higher, but you know this layout is not used for any lowerversions:

    1. <GridLayout xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools"
    3. tools:targetApi="14" >

    However, you should instead use GridLayout from thesupport library.

    tools:locale

    Intended for: <resources>

    Used by: Lint, Android Studio editor

    This tells the tools what the default language/locale is for the resources inthe given <resources> element (because the tools otherwiseassume English) in order to avoid warnings from the spell checker.The value must be a validlocale qualifier.

    For example, you can add this to your values/strings.xml file (the defaultstring values) to indicate that the language used for the default strings isSpanish rather than English:

    1. <resources xmlns:tools="http://schemas.android.com/tools"
    2. tools:locale="es">

    Design-time view attributes

    The following attributes define layout characteristics that are visibleonly in the Android Studio layout preview.

    tools: instead of android:

    Intended for: <View>

    Used by: Android Studio layout editor

    You can insert sample data in your layout preview by using the tools: prefixinstead of android: with any <View> attribute from the Android framework.This is useful when the attribute's value isn't populated until runtime but youwant to see the effect beforehand, in the layout preview.

    For example, if the android:text attribute value is set at runtime or you wantto see the layout with a value different than the default, you can addtools:text to specify some text for the layout preview only.

    Tools attributes reference - 图1

    Figure 1. The tools:text attributesets "Google Voice" as the value for the layout preview

    You can add both the android: namespace attribute (which is used atruntime) and the matching tools: attribute (which overrides the runtimeattribute in the layout preview only).

    You can also use a tools: attribute to unset an attribute only for thelayout preview. For example, if you have a FrameLayout with multiple childrenbut you want to see only one child in the layout preview, you can set one ofthem to be invisible in the layout preview, as shown here:

    1. <Button
    2. android:id="@+id/button"
    3. android:layout_width="wrap_content"
    4. android:layout_height="wrap_content"
    5. android:text="First" />
    6.  
    7. <Button
    8. android:id="@+id/button2"
    9. android:layout_width="wrap_content"
    10. android:layout_height="wrap_content"
    11. android:text="Second"
    12. tools:visibility="invisible" />

    When using the Layout Editor indesign view, the Properties window also allows you to edit some design-timeview attributes. Each design-time attribute is indicated witha wrench icon Tools attributes reference - 图2 next to the attribute name to distinguish it fromthe real attribute of the same name.

    tools:context

    Intended for: Any root <View>

    Used by: Lint, Android Studio layout editor

    This attribute declares which activity this layout is associated with bydefault. This enables features in the editor or layout preview that requireknowledge of the activity, such as what the layout theme should be in thepreview and where to insert onClick handlers when you makethose from a quickfix (figure 2).

    Tools attributes reference - 图3

    Figure 2. Quickfix for the onClick attributeworks only if you've set tools:context

    You can specify the activity class name using the same dot prefix as inthe manifest file (excluding the full package name). For example:

    1. <android.support.constraint.ConstraintLayout
    2. xmlns:android="http://schemas.android.com/apk/res/android"
    3. xmlns:tools="http://schemas.android.com/tools"
    4. tools:context=".MainActivity" >

    Tip:You can also select the theme for the layout preview from theLayout Editor toolbar.

    tools:itemCount

    Intended for: <RecyclerView>

    Used by: Android Studio layout editor

    For a given RecyclerView, this attributespecifies the number of items the layout editor should render in thePreview window.

    For example:

    1. <android.support.v7.widget.RecyclerView
    2. android:id="@+id/recyclerView"
    3. android:layout_width="match_parent"
    4. android:layout_height="match_parent"
    5. tools:itemCount="3"/>

    tools:layout

    Intended for: <fragment>

    Used by: Android Studio layout editor

    This attribute declares which layout you want the layout preview to draw insidethe fragment (because the layout preview cannot execute theactivity code that normally applies the layout).

    For example:

    1. <fragment android:name="com.example.master.ItemListFragment"
    2. tools:layout="@layout/list_content" />

    tools:listitem / tools:listheader / tools:listfooter

    Intended for: <AdapterView> (and subclasses like <ListView>)

    Used by: Android Studio layout editor

    These attributes specify which layout to show in the layout preview for a list'sitems, header, and footer. Any data fields in the layout are filled withnumeric contents such as "Item 1" so that the list items are not repetitive.

    For example:

    1. <ListView xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools"
    3. android:id="@android:id/list"
    4. android:layout_width="match_parent"
    5. android:layout_height="match_parent"
    6. tools:listitem="@layout/sample_list_item"
    7. tools:listheader="@layout/sample_list_header"
    8. tools:listfooter="@layout/sample_list_footer" />

    Note: These attributes don't work for ListView in Android Studio 2.2, butthis is fixed in 2.3(issue 215172).

    tools:showIn

    Intended for: Any root <View> in a layout that's referred to by an<include>

    Used by: Android Studio layout editor

    This attribute allows you to point to a layout that uses this layout as aninclude, so you can preview(and edit) this file as it appears while embedded in its parent layout.

    For example:

    1. <TextView xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools"
    3. android:text="@string/hello_world"
    4. android:layout_width="wrap_content"
    5. android:layout_height="wrap_content"
    6. tools:showIn="@layout/activity_main" />

    Now the layout preview shows this TextView layout as it appears inside theactivity_main layout.

    tools:menu

    Intended for: Any root <View>

    Used by: Android Studio layout editor

    This attribute specifies which menu the layout preview should show in theapp bar. The value can be one or more menu IDs,separated by commas (without @menu/ or any such ID prefix and withoutthe .xml extension). For example:

    1. <?xml version="1.0" encoding="utf-8"?>
    2. <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    3. xmlns:tools="http://schemas.android.com/tools"
    4. android:orientation="vertical"
    5. android:layout_width="match_parent"
    6. android:layout_height="match_parent"
    7. tools:menu="menu1,menu2" />

    tools:minValue / tools:maxValue

    Intended for: <NumberPicker>

    Used by: Android Studio layout editor

    These attributes set minimum and maximum values for aNumberPicker view.

    For example:

    1. <NumberPicker xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools"
    3. android:id="@+id/numberPicker"
    4. android:layout_width="match_parent"
    5. android:layout_height="wrap_content"
    6. tools:minValue="0"
    7. tools:maxValue="10" />

    tools:openDrawer

    Intended for: <DrawerLayout>

    Used by: Android Studio layout editor

    This attribute allows you to open aDrawerLayout in the Preview pane of thelayout editor. You can also modify how the layout editor renders the layout bypassing one of the following values:

    ConstantValueDescription
    end800005Push object to the end of its container, not changing its size.
    left3Push object to the left of its container, not changing its size.
    right5Push object to the right of its container, not changing its size.
    start800003Push object to the beginning of its container, not changing its size.

    For example:

    1. <android.support.v4.widget.DrawerLayout
    2. xmlns:android="http://schemas.android.com/apk/res/android"
    3. xmlns:tools="http://schemas.android.com/tools"
    4. android:id="@+id/drawer_layout"
    5. android:layout_width="match_parent"
    6. android:layout_height="match_parent"
    7. tools:openDrawer="start" />

    "@tools:sample/*" resources

    Intended for: Any view that supports UI text or images.

    Used by: Android Studio layout editor

    This attribute allows you to inject placeholder data or images into your view.For example, if you want to test how your layout behaves with text, but youdon't yet have finalized UI text for your app, you can use placeholder text asfollows:

    1. <TextView xmlns:android="http://schemas.android.com/apk/res/android"
    2. xmlns:tools="http://schemas.android.com/tools"
    3. android:layout_width="wrap_content"
    4. android:layout_height="wrap_content"
    5. tools:text="@tools:sample/lorem" />

    The following table describes the types of placeholder data you caninject into your layouts.

    Attribute valueDescription of placeholder data
    @tools:sample/full_namesFull names that are randomly generated from the combination of @tools:sample/first_names and @tools:sample/last_names.
    @tools:sample/first_namesCommon first names.
    @tools:sample/last_namesCommon last names.
    @tools:sample/citiesNames of cities from across the world.
    @tools:sample/us_zipcodesRandomly generated US zipcodes.
    @tools:sample/us_phonesRandomly generated phone numbers with the following format: (800) 555-xxxx.
    @tools:sample/loremPlaceholder text that is derived from Latin.
    @tools:sample/date/day_of_weekRandomized dates and times for the specified format.
    @tools:sample/date/ddmmyy
    @tools:sample/date/mmddyy
    @tools:sample/date/hhmm
    @tools:sample/date/hhmmss
    @tools:sample/avatarsVector drawables that you can use as profile avatars.
    @tools:sample/backgrounds/scenicImages that you can use as backgrounds.

    Resource shrinking attributes

    The following attributes allow you to enable strict reference checks and declarewhether to keep or discard certain resources when usingresource shrinking.

    To enable resource shrinking, set the shrinkResources property to truein your build.gradle file (alongside minifyEnabled for code shrinking).For example:

    1. android {
    2. ...
    3. buildTypes {
    4. release {
    5. shrinkResources true
    6. minifyEnabled true
    7. proguardFiles getDefaultProguardFile('proguard-android.txt'),
    8. 'proguard-rules.pro'
    9. }
    10. }
    11. }

    tools:shrinkMode

    Intended for: <resources>

    Used by: Build tools with resource shrinking

    This attribute allows you to specify whether the build tools should use"safe mode" (play it safe and keep all resources that are explicitly cited andthat might be referenced dynamically with a call toResources.getIdentifier()))or "strict mode" (keep only the resourcesthat are explicitly cited in code or in other resources).

    The default is to use safe mode (shrinkMode="safe"). To instead usestrict mode, add shrinkMode="strict" to the <resources> tag as shown here:

    1. <?xml version="1.0" encoding="utf-8"?>
    2. <resources xmlns:tools="http://schemas.android.com/tools"
    3. tools:shrinkMode="strict" />

    When you enable strict mode, you may need to use tools:keepto keep resources that were removed but that you actually want, and usetools:discard to explicitly remove even more resources.

    For more information, seeShrink your resources.

    tools:keep

    Intended for: <resources>

    Used by: Build tools with resource shrinking

    When using resource shrinking to remove unused resources, thisattribute allows you to specify resources to keep (typically because they arereferenced in an indirect way at runtime, such as by passing a dynamicallygenerated resource name toResources.getIdentifier())).

    To use, create an XML file in your resources directory (for example, atres/raw/keep.xml) with a <resources> tagand specify each resource to keep in the tools:keep attribute as acomma-separated list. You can use the asterisk character as a wild card.For example:

    1. <?xml version="1.0" encoding="utf-8"?>
    2. <resources xmlns:tools="http://schemas.android.com/tools"
    3. tools:keep="@layout/used_1,@layout/used_2,@layout/*_3" />

    For more information, seeShrink your resources.

    tools:discard

    Intended for: <resources>

    Used by: Build tools with resource shrinking

    When using resource shrinking to strip out unused resources, this attributeallows you to specify resources you want to manually discard (typically becausethe resource is referenced but in a way that does not affect your app, orbecause the Gradle plugin has incorrectly deduced that the resource isreferenced).

    To use, create an XML file in your resources directory (for example, atres/raw/keep.xml) with a <resources> tagand specify each resource to keep in the tools:discard attribute as acomma-separated list. You can use the asterisk character as a wild card.For example:

    1. <?xml version="1.0" encoding="utf-8"?>
    2. <resources xmlns:tools="http://schemas.android.com/tools"
    3. tools:discard="@layout/unused_1" />

    For more information, seeShrink your resources.