1 page.title=Applying Styles and Themes 2 parent.title=User Interface 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#DefiningStyles">Defining Styles</a> 11 <ol> 12 <li><a href="#Inheritance">Inheritance</a></li> 13 <li><a href="#Properties">Style Properties</a></li> 14 </ol> 15 </li> 16 <li><a href="#ApplyingStyles">Applying Styles and Themes to the UI</a> 17 <ol> 18 <li><a href="#ApplyAStyle">Apply a style to a View</a></li> 19 <li><a href="#ApplyATheme">Apply a theme to an Activity or application</a></li> 20 </ol> 21 </li> 22 <li><a href="#PlatformStyles">Using Platform Styles and Themes</a></li> 23 </ol> 24 <h2>See also</h2> 25 <ol> 26 <li><a href="{@docRoot}guide/topics/resources/available-resources.html#stylesandthemes">Style 27 and Theme Resources</a></li> 28 <li>{@link android.R.style} for Android styles and themes</li> 29 <li>{@link android.R.attr} for all style attributes</li> 30 </ol> 31 </div> 32 </div> 33 34 35 <p>A <strong>style</strong> is a collection of properties that 36 specify the look and format for a {@link android.view.View} or window. 37 A style can specify properties such as height, padding, font color, font size, 38 background color, and much more. A style is defined in an XML resource that is 39 separate from the XML that specifies the layout.</p> 40 41 <p>Styles in Android share a similar philosophy to cascading stylesheets in web 42 design—they allow you to separate the design from the 43 content.</p> 44 45 <p>For example, by using a style, you can take this layout XML:</p> 46 <pre> 47 <TextView 48 android:layout_width="fill_parent" 49 android:layout_height="wrap_content" 50 android:textColor="#00FF00" 51 android:typeface="monospace" 52 android:text="@string/hello" /> 53 </pre> 54 <p>And turn it into this:</p> 55 <pre> 56 <TextView 57 style="@style/CodeFont" 58 android:text="@string/hello" /> 59 </pre> 60 61 <p>All of the attributes related to style have been removed from the layout XML and put into a 62 style definition called {@code CodeFont}, which is then applied with the <code>style</code> 63 attribute. You'll see the definition for this style in the following section.</p> 64 65 <p>A <strong>theme</strong> is a style applied to an entire {@link android.app.Activity} or 66 application, rather than an individual {@link android.view.View} (as in the example above). When a 67 style is applied as a theme, every View in the Activity or application will apply each style 68 property that it supports. For example, you can apply the same {@code CodeFont} style 69 as a theme for an Activity and then all text inside that Activity will have green monospace 70 font.</p> 71 72 73 <h2 id="DefiningStyles">Defining Styles</h2> 74 75 <p>To create a set of styles, save an XML file in the {@code res/values/} 76 directory of your project. The name of the XML file is arbitrary, but it must use the 77 {@code .xml} extension and be saved in the {@code res/values/} folder.</p> 78 79 <p>The root node of the XML file must be {@code <resources>}.</p> 80 81 <p>For each style you want to create, add a {@code <style>} element to the file 82 with a {@code name} that uniquely identifies the style (this attribute is required). 83 Then add an {@code <item>} element for each property of that style, with a 84 {@code name} that declares the style property and a value to go with it (this attribute 85 is required). The value for the {@code <item>} can 86 be a keyword string, a hex color, a reference to another resource type, or other value 87 depending on the style property. 88 Here's an example file with a single style:</p> 89 90 <pre> 91 <?xml version="1.0" encoding="utf-8"?> 92 <resources> 93 <style name="CodeFont" parent="@android:style/TextAppearance.Medium"> 94 <item name="android:layout_width">fill_parent</item> 95 <item name="android:layout_height">wrap_content</item> 96 <item name="android:textColor">#00FF00</item> 97 <item name="android:typeface">monospace</item> 98 </style> 99 </resources> 100 </pre> 101 102 <p>Each child of the {@code <resources>} element is converted into an application resource 103 object at compile-time, which can be referenced by the value in the {@code <style>} element's 104 {@code name} attribute. This example style can be referenced from an XML layout as 105 {@code @style/CodeFont} (as demonstrated in the introduction above).</p> 106 107 <p>The <code>parent</code> attribute in the {@code <style>} element is optional and 108 specifies the resource ID of another style from which this style should inherit 109 properties. You can then override the inherited style properties if you want to.</p> 110 111 <p>Remember, a style that you want to use as an Activity or application theme is defined in XML 112 exactly the same as a style for a View. A style such as the one defined above can be applied as a 113 style for a single View or as a theme for an entire Activity or application. How to apply a style 114 for a single View or as an application theme is discussed later.</p> 115 116 117 <h3 id="Inheritance">Inheritance</h3> 118 119 <p>The {@code parent} attribute in the {@code <style>} element lets you specify a style 120 from which your style should inherit properties. 121 You can use this to inherit properties from an existing style and 122 then define only the properties that you want to change or add. You can 123 inherit from styles that you've created yourself or from styles that are built into the 124 platform. (See <a href="#PlatformStyles">Using Platform Styles and Themes</a>, below, for 125 information about inheriting from styles defined by the Android platform.) For example, you can 126 inherit the Android platform's default text appearance and then modify it:</p> 127 128 <pre> 129 <style name="GreenText" parent="@android:style/TextAppearance"> 130 <item name="android:textColor">#00FF00</item> 131 </style> 132 </pre> 133 134 <p>If you want to inherit from styles that you've defined yourself, you <em>do not</em> have to use 135 the <code>parent</code> attribute. Instead, just prefix the name of the style you want to 136 inherit to the name of your new style, separated by a period. For example, to create a new style 137 that inherits the <code>CodeFont</code> style defined above, but make the color red, 138 you can author the new style like this:</p> 139 140 <pre> 141 <style name="CodeFont.Red"> 142 <item name="android:textColor">#FF0000</item> 143 </style> 144 </pre> 145 146 <p>Notice that there is no {@code parent} attribute in the {@code <style>} tag, but because 147 the {@code name} attribute begins with the {@code CodeFont} style name (which 148 is a style that you have created), this style inherits all style properties from that style. This 149 style then overrides the {@code android:textColor} property to make the text red. You can 150 reference this new style as {@code @style/CodeFont.Red}.</p> 151 152 <p>You can continue inheriting like 153 this as many times as you'd like, by chaining names with periods. For example, you can 154 extend {@code CodeFont.Red} to be bigger, with:</p> 155 <pre> 156 <style name="CodeFont.Red.Big"> 157 <item name="android:textSize">30sp</item> 158 </style> 159 </pre> 160 <p>This inherits from both {@code CodeFont} and {@code CodeFont.Red} styles, then adds the 161 {@code android:textSize} property.</p> 162 163 <p class="note"><strong>Note:</strong> This technique for inheritance by chaining together 164 names only works for styles defined by your own resources. You can't inherit Android built-in styles 165 this way. To reference a built-in style, such as {@link android.R.style#TextAppearance}, you must 166 use the {@code parent} attribute.</p> 167 168 169 <h3 id="Properties">Style Properties</h3> 170 171 <p>Now that you understand how a style is defined, you need to learn what kind 172 of style properties—defined by the {@code <item>} element—are available. 173 You're probably familiar with some already, such as {@link android.R.attr#layout_width} and 174 {@link android.R.attr#textColor}. Of course, there are many more style properties you can use.</p> 175 176 <p>The best place to find properties that apply to a specific {@link android.view.View} is the 177 corresponding class reference, which lists all of the supported XML attributes. For example, all of the 178 attributes listed in the table of 179 <a href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML 180 attributes</a> can be used in a style definition for a {@link android.widget.TextView} element (or one of 181 its subclasses). One of the attributes listed in the reference is <a 182 href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code 183 android:inputType}</a>, so where you might normally place the <a 184 href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code 185 android:inputType}</a> 186 attribute in an {@code <EditText>} element, like this:</p> 187 <pre> 188 <EditText 189 android:inputType="number" 190 ... /> 191 </pre> 192 193 <p>You can instead create a style for the {@link android.widget.EditText} element that includes this property:</p> 194 <pre> 195 <style name="Numbers"> 196 <item name="android:inputType">number</item> 197 ... 198 </style> 199 </pre> 200 <p>So your XML for the layout can now implement this style:</p> 201 <pre> 202 <EditText 203 style="@style/Numbers" 204 ... /> 205 </pre> 206 207 <p>This simple example may look like more work, but when you add more style properties and 208 factor-in the ability to re-use the style in various places, the pay-off can be huge.</p> 209 210 <p>For a reference of all available style properties, see the {@link android.R.attr} 211 reference. Keep in mind that all View objects don't accept all the same style attributes, so you 212 should normally refer to the specific {@link android.view.View} class for supported style 213 properties. However, if you 214 apply a style to a View that does not support all of the style properties, the View will 215 apply only those properties that are supported and simply ignore the others.</p> 216 217 <p>Some style properties, however, are not supported by any View element and can only be applied 218 as a theme. These style properties apply to the entire window and not to any type of View. 219 For example, style properties for a theme can hide the application title, hide the status bar, 220 or change the window's background. These kind of style properties do not belong to any View object. 221 To discover these theme-only style properties, look at the {@link android.R.attr} reference for 222 attributes that begin with {@code window}. For instance, {@code windowNoTitle} and {@code 223 windowBackground} are style properties that are effective only when the style is applied as 224 a theme to an Activity or application. See the next section for information about applying a 225 style as a theme.</p> 226 227 <p class="note"><strong>Note:</strong> Don't forget to prefix the property names in each 228 {@code <item>} element with the <code>android:</code> namespace. For example: 229 {@code <item name="android:inputType">}.</p> 230 231 232 233 <h2 id="ApplyingStyles">Applying Styles and Themes to the UI</h2> 234 235 <p>There are two ways to set a style:</p> 236 <ul> 237 <li>To an individual View, by adding the <code>style</code> attribute to a View 238 element in the XML for your layout.</li> 239 <li>Or, to an entire Activity or application, by adding the <code>android:theme</code> 240 attribute to the <code><activity></code> or <code><application></code> element 241 in the Android manifest.</li> 242 </ul> 243 244 <p>When you apply a style to a single {@link android.view.View} in the layout, the properties 245 defined by the style are applied only to that {@link android.view.View}. If a style is applied to a 246 {@link android.view.ViewGroup}, the child {@link android.view.View} elements will 247 <strong>not</strong> inherit the style properties—only the element to which you directly apply 248 the style will apply its properties. However, you <em>can</em> apply a style so that it 249 applies to all {@link android.view.View} elements—by applying the style as a theme.</p> 250 251 <p>To apply a style definition as a theme, you must apply the style to an 252 {@link android.app.Activity} or application in the Android manifest. When you do so, 253 every {@link android.view.View} within the Activity or 254 application will apply each property that it supports. For example, if you apply the {@code 255 CodeFont} style from the previous examples to an Activity, then all View elements 256 that support the text style properties will apply them. Any View that does not support 257 the properties will ignore them. If a View supports only some of the properties, then 258 it will apply only those properties.</p> 259 260 261 <h3 id="ApplyAStyle">Apply a style to a View</h3> 262 263 <p>Here's how to set a style for a View in the XML layout:</p> 264 265 <pre> 266 <TextView 267 style="@style/CodeFont" 268 android:text="@string/hello" /> 269 </pre> 270 271 <p>Now this TextView will be styled as defined by the style named {@code CodeFont}. 272 (See the sample above, in <a href="#DefiningStyles">Defining Styles</a>.)</p> 273 274 <p class="note"><strong>Note:</strong> The <code>style</code> attribute 275 does <em>not</em> use the <code>android:</code> namespace prefix.</p> 276 277 278 <h3 id="ApplyATheme">Apply a theme to an Activity or application</h3> 279 280 <p>To set a theme for all the activities of your application, open the {@code AndroidManifest.xml} file and 281 edit the <code><application></code> tag to include the <code>android:theme</code> attribute with the 282 style name. For example:</p> 283 284 <pre> 285 <application android:theme="@style/CustomTheme"> 286 </pre> 287 288 <p>If you want a theme applied to just one Activity in your application, then add the 289 <code>android:theme</code> attribute to the <code><activity></code> tag instead.</p> 290 291 <p>Just as Android provides other built-in resources, there are many pre-defined themes that you can use, to avoid 292 writing them yourself. For example, you can use the {@code Dialog} theme and make your Activity 293 appear like a dialog box:</p> 294 295 <pre> 296 <activity android:theme="@android:style/Theme.Dialog"> 297 </pre> 298 299 <p>Or if you want the background to be transparent, use the Translucent theme:</p> 300 301 <pre> 302 <activity android:theme="@android:style/Theme.Translucent"> 303 </pre> 304 305 <p>If you like a theme, but want to tweak it, just add the theme as the <code>parent</code> 306 of your custom theme. For example, you can modify the traditional dialog theme to use your own 307 background image like this:</p> 308 <pre> 309 <style name="CustomDialogTheme" parent="@android:style/Theme.Dialog"> 310 <item name="android:windowBackground">@drawable/custom_dialog_background</item> 311 </style> 312 </pre> 313 314 <p>Now use {@code CustomDialogTheme} instead of {@code Theme.Dialog} inside the Android 315 Manifest:</p> 316 317 <pre> 318 <activity android:theme="@style/CustomDialogTheme"> 319 </pre> 320 321 322 <!-- This currently has some bugs 323 324 <h3 id="setThemeFromTheApp">Set the theme from the application</h3> 325 326 <p>We recommend that you set your themes in you Android manifest, as described above, because it's simple and 327 keeps your program code focused on application functionality, rather than style. But if it's necessary 328 for you to change your theme programatically (perhaps based on a user preference), you can.</p> 329 330 <p>To set the theme in your program code, use the {@link android.content.ContextWrapper#setTheme(int)} 331 method and pass it the theme resource ID. Note that, when doing so, you must be sure to set the theme <em>before</em> 332 instantiating any Views in the context, for example, before calling 333 <code>setContentView(View)</code> or <code>inflate(int, ViewGroup)</code>. This ensures that 334 the system applies the same theme for all of your UI screens. Here's an example:</p> 335 336 <pre> 337 protected void onCreate(Bundle savedInstanceState) { 338 super.onCreate(savedInstanceState); 339 ... 340 setTheme(android.R.style.Theme_Light); 341 setContentView(R.layout.linear_layout_3); 342 } 343 </pre> 344 345 <p>If you are considering loading a theme programmatically for the main 346 screen of your application, note that the theme would not be applied 347 in any animations the system would use to start the activity, which 348 would take place before your application opens. In most cases, if 349 you want to apply a theme to your main screen, doing so in XML 350 is a better approach. </p> 351 352 --> 353 354 355 356 <h2 id="PlatformStyles">Using Platform Styles and Themes</h2> 357 358 <p>The Android platform provides a large collection of styles and themes that you can 359 use in your applications. You can find a reference of all available styles in the 360 {@link android.R.style} class. To use the styles listed here, replace all underscores in 361 the style name with a period. For example, you can apply the 362 {@link android.R.style#Theme_NoTitleBar} theme with 363 {@code "@android:style/Theme.NoTitleBar"}.</p> 364 365 <p>The {@link android.R.style} reference, however, is not well documented and does not 366 thoroughly describe the styles, so viewing the actual source code for these styles and 367 themes will give you a better understanding of what style properties each one provides. 368 For a better reference to the Android styles and themes, see the following source code:</p> 369 <ul> 370 <li><a href="http://android.git.kernel.org/?p=platform/frameworks/base.git;a=blob;f=core/res/res/values/styles.xml;h=d7b654e49809cb97a35682754b1394af5c8bc88b;hb=HEAD">Android Styles (styles.xml)</a></li> 371 <li><a href="http://android.git.kernel.org/?p=platform/frameworks/base.git;a=blob;f=core/res/res/values/themes.xml;h=6b3d7407d1c895a3c297e60d5beac98e2d34c271;hb=HEAD">Android Themes (themes.xml)</a></li> 372 </ul> 373 374 <p>These files will help you learn through example. For instance, in the Android themes source code, 375 you'll find a declaration for <code><style name="Theme.Dialog"></code>. In this definition, 376 you'll see all of the properties that are used to style dialogs that are used by the Android 377 framework.</p> 378 379 <p>For more information about the syntax used to create styles in XML, see 380 <a href="{@docRoot}guide/topics/resources/available-resources.html#stylesandthemes">Available Resource Types: 381 Style and Themes</a>.</p> 382 383 <p>For a reference of available style attributes that you can use to define a style or theme 384 (e.g., "windowBackground" or "textAppearance"), see {@link android.R.attr} or the respective 385 View class for which you are creating a style.</p> 386 387 388 389 390 391