| page.title=Styles and Themes |
| parent.title=User Interface |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#DefiningStyles">Defining Styles</a> |
| <ol> |
| <li><a href="#Inheritance">Inheritance</a></li> |
| <li><a href="#Properties">Style Properties</a></li> |
| </ol> |
| </li> |
| <li><a href="#ApplyingStyles">Applying Styles and Themes to the UI</a> |
| <ol> |
| <li><a href="#ApplyAStyle">Apply a style to a View</a></li> |
| <li><a href="#ApplyATheme">Apply a theme to an Activity or application</a></li> |
| <li><a href="#SelectATheme">Select a theme based on platform version</a></li> |
| </ol> |
| </li> |
| <li><a href="#PlatformStyles">Using Platform Styles and Themes</a></li> |
| </ol> |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}guide/topics/resources/available-resources.html#stylesandthemes">Style |
| and Theme Resources</a></li> |
| <li>{@link android.R.style} for Android styles and themes</li> |
| <li>{@link android.R.attr} for all style attributes</li> |
| </ol> |
| </div> |
| </div> |
| |
| |
| <p>A <strong>style</strong> is a collection of properties that |
| specify the look and format for a {@link android.view.View} or window. |
| A style can specify properties such as height, padding, font color, font size, |
| background color, and much more. A style is defined in an XML resource that is |
| separate from the XML that specifies the layout.</p> |
| |
| <p>Styles in Android share a similar philosophy to cascading stylesheets in web |
| design—they allow you to separate the design from the |
| content.</p> |
| |
| <p>For example, by using a style, you can take this layout XML:</p> |
| <pre> |
| <TextView |
| android:layout_width="fill_parent" |
| android:layout_height="wrap_content" |
| android:textColor="#00FF00" |
| android:typeface="monospace" |
| android:text="@string/hello" /> |
| </pre> |
| <p>And turn it into this:</p> |
| <pre> |
| <TextView |
| style="@style/CodeFont" |
| android:text="@string/hello" /> |
| </pre> |
| |
| <p>All of the attributes related to style have been removed from the layout XML and put into a |
| style definition called {@code CodeFont}, which is then applied with the <code>style</code> |
| attribute. You'll see the definition for this style in the following section.</p> |
| |
| <p>A <strong>theme</strong> is a style applied to an entire {@link android.app.Activity} or |
| application, rather than an individual {@link android.view.View} (as in the example above). When a |
| style is applied as a theme, every View in the Activity or application will apply each style |
| property that it supports. For example, you can apply the same {@code CodeFont} style |
| as a theme for an Activity and then all text inside that Activity will have green monospace |
| font.</p> |
| |
| |
| <h2 id="DefiningStyles">Defining Styles</h2> |
| |
| <p>To create a set of styles, save an XML file in the {@code res/values/} |
| directory of your project. The name of the XML file is arbitrary, but it must use the |
| {@code .xml} extension and be saved in the {@code res/values/} folder.</p> |
| |
| <p>The root node of the XML file must be {@code <resources>}.</p> |
| |
| <p>For each style you want to create, add a {@code <style>} element to the file |
| with a {@code name} that uniquely identifies the style (this attribute is required). |
| Then add an {@code <item>} element for each property of that style, with a |
| {@code name} that declares the style property and a value to go with it (this attribute |
| is required). The value for the {@code <item>} can |
| be a keyword string, a hex color, a reference to another resource type, or other value |
| depending on the style property. |
| Here's an example file with a single style:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <style name="CodeFont" parent="@android:style/TextAppearance.Medium"> |
| <item name="android:layout_width">fill_parent</item> |
| <item name="android:layout_height">wrap_content</item> |
| <item name="android:textColor">#00FF00</item> |
| <item name="android:typeface">monospace</item> |
| </style> |
| </resources> |
| </pre> |
| |
| <p>Each child of the {@code <resources>} element is converted into an application resource |
| object at compile-time, which can be referenced by the value in the {@code <style>} element's |
| {@code name} attribute. This example style can be referenced from an XML layout as |
| {@code @style/CodeFont} (as demonstrated in the introduction above).</p> |
| |
| <p>The <code>parent</code> attribute in the {@code <style>} element is optional and |
| specifies the resource ID of another style from which this style should inherit |
| properties. You can then override the inherited style properties if you want to.</p> |
| |
| <p>Remember, a style that you want to use as an Activity or application theme is defined in XML |
| exactly the same as a style for a View. A style such as the one defined above can be applied as a |
| style for a single View or as a theme for an entire Activity or application. How to apply a style |
| for a single View or as an application theme is discussed later.</p> |
| |
| |
| <h3 id="Inheritance">Inheritance</h3> |
| |
| <p>The {@code parent} attribute in the {@code <style>} element lets you specify a style |
| from which your style should inherit properties. |
| You can use this to inherit properties from an existing style and |
| then define only the properties that you want to change or add. You can |
| inherit from styles that you've created yourself or from styles that are built into the |
| platform. (See <a href="#PlatformStyles">Using Platform Styles and Themes</a>, below, for |
| information about inheriting from styles defined by the Android platform.) For example, you can |
| inherit the Android platform's default text appearance and then modify it:</p> |
| |
| <pre> |
| <style name="GreenText" parent="@android:style/TextAppearance"> |
| <item name="android:textColor">#00FF00</item> |
| </style> |
| </pre> |
| |
| <p>If you want to inherit from styles that you've defined yourself, you <em>do not</em> have to use |
| the <code>parent</code> attribute. Instead, just prefix the name of the style you want to |
| inherit to the name of your new style, separated by a period. For example, to create a new style |
| that inherits the <code>CodeFont</code> style defined above, but make the color red, |
| you can author the new style like this:</p> |
| |
| <pre> |
| <style name="CodeFont.Red"> |
| <item name="android:textColor">#FF0000</item> |
| </style> |
| </pre> |
| |
| <p>Notice that there is no {@code parent} attribute in the {@code <style>} tag, but because |
| the {@code name} attribute begins with the {@code CodeFont} style name (which |
| is a style that you have created), this style inherits all style properties from that style. This |
| style then overrides the {@code android:textColor} property to make the text red. You can |
| reference this new style as {@code @style/CodeFont.Red}.</p> |
| |
| <p>You can continue inheriting like |
| this as many times as you'd like, by chaining names with periods. For example, you can |
| extend {@code CodeFont.Red} to be bigger, with:</p> |
| <pre> |
| <style name="CodeFont.Red.Big"> |
| <item name="android:textSize">30sp</item> |
| </style> |
| </pre> |
| <p>This inherits from both {@code CodeFont} and {@code CodeFont.Red} styles, then adds the |
| {@code android:textSize} property.</p> |
| |
| <p class="note"><strong>Note:</strong> This technique for inheritance by chaining together |
| names only works for styles defined by your own resources. You can't inherit Android built-in styles |
| this way. To reference a built-in style, such as {@link android.R.style#TextAppearance}, you must |
| use the {@code parent} attribute.</p> |
| |
| |
| <h3 id="Properties">Style Properties</h3> |
| |
| <p>Now that you understand how a style is defined, you need to learn what kind |
| of style properties—defined by the {@code <item>} element—are available. |
| You're probably familiar with some already, such as {@link android.R.attr#layout_width} and |
| {@link android.R.attr#textColor}. Of course, there are many more style properties you can use.</p> |
| |
| <p>The best place to find properties that apply to a specific {@link android.view.View} is the |
| corresponding class reference, which lists all of the supported XML attributes. For example, all of the |
| attributes listed in the table of |
| <a href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML |
| attributes</a> can be used in a style definition for a {@link android.widget.TextView} element (or one of |
| its subclasses). One of the attributes listed in the reference is <a |
| href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| android:inputType}</a>, so where you might normally place the <a |
| href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| android:inputType}</a> |
| attribute in an {@code <EditText>} element, like this:</p> |
| <pre> |
| <EditText |
| android:inputType="number" |
| ... /> |
| </pre> |
| |
| <p>You can instead create a style for the {@link android.widget.EditText} element that includes this property:</p> |
| <pre> |
| <style name="Numbers"> |
| <item name="android:inputType">number</item> |
| ... |
| </style> |
| </pre> |
| <p>So your XML for the layout can now implement this style:</p> |
| <pre> |
| <EditText |
| style="@style/Numbers" |
| ... /> |
| </pre> |
| |
| <p>This simple example may look like more work, but when you add more style properties and |
| factor-in the ability to re-use the style in various places, the pay-off can be huge.</p> |
| |
| <p>For a reference of all available style properties, see the {@link android.R.attr} |
| reference. Keep in mind that all View objects don't accept all the same style attributes, so you |
| should normally refer to the specific {@link android.view.View} class for supported style |
| properties. However, if you |
| apply a style to a View that does not support all of the style properties, the View will |
| apply only those properties that are supported and simply ignore the others.</p> |
| |
| <p>Some style properties, however, are not supported by any View element and can only be applied |
| as a theme. These style properties apply to the entire window and not to any type of View. |
| For example, style properties for a theme can hide the application title, hide the status bar, |
| or change the window's background. These kind of style properties do not belong to any View object. |
| To discover these theme-only style properties, look at the {@link android.R.attr} reference for |
| attributes that begin with {@code window}. For instance, {@code windowNoTitle} and {@code |
| windowBackground} are style properties that are effective only when the style is applied as |
| a theme to an Activity or application. See the next section for information about applying a |
| style as a theme.</p> |
| |
| <p class="note"><strong>Note:</strong> Don't forget to prefix the property names in each |
| {@code <item>} element with the <code>android:</code> namespace. For example: |
| {@code <item name="android:inputType">}.</p> |
| |
| |
| |
| <h2 id="ApplyingStyles">Applying Styles and Themes to the UI</h2> |
| |
| <p>There are two ways to set a style:</p> |
| <ul> |
| <li>To an individual View, by adding the <code>style</code> attribute to a View |
| element in the XML for your layout.</li> |
| <li>Or, to an entire Activity or application, by adding the <code>android:theme</code> |
| attribute to the <code><activity></code> or <code><application></code> element |
| in the Android manifest.</li> |
| </ul> |
| |
| <p>When you apply a style to a single {@link android.view.View} in the layout, the properties |
| defined by the style are applied only to that {@link android.view.View}. If a style is applied to a |
| {@link android.view.ViewGroup}, the child {@link android.view.View} elements will |
| <strong>not</strong> inherit the style properties—only the element to which you directly apply |
| the style will apply its properties. However, you <em>can</em> apply a style so that it |
| applies to all {@link android.view.View} elements—by applying the style as a theme.</p> |
| |
| <p>To apply a style definition as a theme, you must apply the style to an |
| {@link android.app.Activity} or application in the Android manifest. When you do so, |
| every {@link android.view.View} within the Activity or |
| application will apply each property that it supports. For example, if you apply the {@code |
| CodeFont} style from the previous examples to an Activity, then all View elements |
| that support the text style properties will apply them. Any View that does not support |
| the properties will ignore them. If a View supports only some of the properties, then |
| it will apply only those properties.</p> |
| |
| |
| <h3 id="ApplyAStyle">Apply a style to a View</h3> |
| |
| <p>Here's how to set a style for a View in the XML layout:</p> |
| |
| <pre> |
| <TextView |
| style="@style/CodeFont" |
| android:text="@string/hello" /> |
| </pre> |
| |
| <p>Now this TextView will be styled as defined by the style named {@code CodeFont}. |
| (See the sample above, in <a href="#DefiningStyles">Defining Styles</a>.)</p> |
| |
| <p class="note"><strong>Note:</strong> The <code>style</code> attribute |
| does <em>not</em> use the <code>android:</code> namespace prefix.</p> |
| |
| |
| <h3 id="ApplyATheme">Apply a theme to an Activity or application</h3> |
| |
| <p>To set a theme for all the activities of your application, open the {@code AndroidManifest.xml} file and |
| edit the <code><application></code> tag to include the <code>android:theme</code> attribute with the |
| style name. For example:</p> |
| |
| <pre> |
| <application android:theme="@style/CustomTheme"> |
| </pre> |
| |
| <p>If you want a theme applied to just one Activity in your application, then add the |
| <code>android:theme</code> attribute to the <code><activity></code> tag instead.</p> |
| |
| <p>Just as Android provides other built-in resources, there are many pre-defined themes that you can use, to avoid |
| writing them yourself. For example, you can use the {@code Dialog} theme and make your Activity |
| appear like a dialog box:</p> |
| |
| <pre> |
| <activity android:theme="@android:style/Theme.Dialog"> |
| </pre> |
| |
| <p>Or if you want the background to be transparent, use the Translucent theme:</p> |
| |
| <pre> |
| <activity android:theme="@android:style/Theme.Translucent"> |
| </pre> |
| |
| <p>If you like a theme, but want to tweak it, just add the theme as the <code>parent</code> |
| of your custom theme. For example, you can modify the traditional light theme to use your own |
| color like this:</p> |
| <pre> |
| <color name="custom_theme_color">#b0b0ff</color> |
| <style name="CustomTheme" parent="android:Theme.Light"> |
| <item name="android:windowBackground">@color/custom_theme_color</item> |
| <item name="android:colorBackground">@color/custom_theme_color</item> |
| </style> |
| </pre> |
| |
| <p>(Note that the color needs to supplied as a separate resource here because |
| the <code>android:windowBackground</code> attribute only supports a reference to |
| another resource; unlike <code>android:colorBackground</code>, it can not be given |
| a color literal.)</p> |
| |
| <p>Now use {@code CustomTheme} instead of {@code Theme.Light} inside the Android |
| Manifest:</p> |
| |
| <pre> |
| <activity android:theme="@style/CustomTheme"> |
| </pre> |
| |
| |
| <h3 id="SelectATheme">Select a theme based on platform version</h3> |
| |
| <p>Newer versions of Android have additional themes available to applications, |
| and you might want to use these while running on those platforms while still being |
| compatible with older versions. You can accomplish this through a custom theme |
| that uses resource selection to switch between different parent themes, based on the platform |
| version.</p> |
| |
| <p>For example, here is the declaration for a custom theme which is simply |
| the standard platforms default light theme. It would go in an XML file under |
| <code>res/values</code> (typically <code>res/values/styles.xml</code>): |
| <pre> |
| <style name="LightThemeSelector" parent="android:Theme.Light"> |
| ... |
| </style> |
| </pre> |
| |
| <p>To have this theme use the newer holographic theme when the application is running |
| on Android 3.0 (API Level 11) or higher, you can place an alternative |
| declaration for the theme in an XML file in <code>res/values-v11</code>, but make the parent theme |
| the holographic theme:</p> |
| <pre> |
| <style name="LightThemeSelector" parent="android:Theme.Holo.Light"> |
| ... |
| </style> |
| </pre> |
| |
| <p>Now use this theme like you would any other, and your application will |
| automatically switch to the holographic theme if running on Android 3.0 or higher.</p> |
| |
| <p>A list of the standard attributes that you can use in themes can be |
| found at {@link android.R.styleable#Theme R.styleable.Theme}.</p> |
| |
| <p>For more information about providing alternative resources, such as themes and layouts, based |
| on the platform version or other device configurations, see the <a |
| href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a> |
| document.</p> |
| |
| <!-- This currently has some bugs |
| |
| <h3 id="setThemeFromTheApp">Set the theme from the application</h3> |
| |
| <p>We recommend that you set your themes in you Android manifest, as described above, because it's simple and |
| keeps your program code focused on application functionality, rather than style. But if it's necessary |
| for you to change your theme programatically (perhaps based on a user preference), you can.</p> |
| |
| <p>To set the theme in your program code, use the {@link android.content.ContextWrapper#setTheme(int)} |
| method and pass it the theme resource ID. Note that, when doing so, you must be sure to set the theme <em>before</em> |
| instantiating any Views in the context, for example, before calling |
| <code>setContentView(View)</code> or <code>inflate(int, ViewGroup)</code>. This ensures that |
| the system applies the same theme for all of your UI screens. Here's an example:</p> |
| |
| <pre> |
| protected void onCreate(Bundle savedInstanceState) { |
| super.onCreate(savedInstanceState); |
| ... |
| setTheme(android.R.style.Theme_Light); |
| setContentView(R.layout.linear_layout_3); |
| } |
| </pre> |
| |
| <p>If you are considering loading a theme programmatically for the main |
| screen of your application, note that the theme would not be applied |
| in any animations the system would use to start the activity, which |
| would take place before your application opens. In most cases, if |
| you want to apply a theme to your main screen, doing so in XML |
| is a better approach. </p> |
| |
| --> |
| |
| |
| |
| <h2 id="PlatformStyles">Using Platform Styles and Themes</h2> |
| |
| <p>The Android platform provides a large collection of styles and themes that you can |
| use in your applications. You can find a reference of all available styles in the |
| {@link android.R.style} class. To use the styles listed here, replace all underscores in |
| the style name with a period. For example, you can apply the |
| {@link android.R.style#Theme_NoTitleBar} theme with |
| {@code "@android:style/Theme.NoTitleBar"}.</p> |
| |
| <p>The {@link android.R.style} reference, however, is not well documented and does not |
| thoroughly describe the styles, so viewing the actual source code for these styles and |
| themes will give you a better understanding of what style properties each one provides. |
| For a better reference to the Android styles and themes, see the following source code:</p> |
| <ul> |
| <li><a href="https://android.googlesource.com/platform/frameworks/base/+/refs/heads/master/core/res/res/values/styles.xml">Android Styles (styles.xml)</a></li> |
| <li><a href="https://android.googlesource.com/platform/frameworks/base/+/refs/heads/master/core/res/res/values/themes.xml">Android Themes (themes.xml)</a></li> |
| </ul> |
| |
| <p>These files will help you learn through example. For instance, in the Android themes source code, |
| you'll find a declaration for <code><style name="Theme.Dialog"></code>. In this definition, |
| you'll see all of the properties that are used to style dialogs that are used by the Android |
| framework.</p> |
| |
| <p>For more information about the syntax for styles and themes in XML, see the |
| <a href="{@docRoot}guide/topics/resources/style-resource.html">Style Resource</a> document.</p> |
| |
| <p>For a reference of available style attributes that you can use to define a style or theme |
| (e.g., "windowBackground" or "textAppearance"), see {@link android.R.attr} or the respective |
| View class for which you are creating a style.</p> |
| |
| |
| |
| |
| |