Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1 | page.title=Data Binding Guide |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 2 | page.tags="databinding", "layouts" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 3 | @jd:body |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 4 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
| 7 | <h2> |
| 8 | In this document: |
| 9 | </h2> |
| 10 | |
| 11 | <ol> |
| 12 | <li> |
| 13 | <a href="#build_environment">Build Environment</a> |
| 14 | </li> |
| 15 | |
| 16 | <li> |
| 17 | <a href="#data_binding_layout_files">Data Binding Layout Files</a> |
| 18 | <ol> |
| 19 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 20 | <a href="#writing_expressions">Writing your first data binding |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 21 | expressions</a> |
| 22 | </li> |
| 23 | |
| 24 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 25 | <a href="#data_object">Data Object</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 26 | </li> |
| 27 | |
| 28 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 29 | <a href="#binding_data">Binding Data</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 30 | </li> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 31 | |
| 32 | <li> |
| 33 | <a href="#binding_events">Binding Events</a> |
| 34 | </li> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 35 | </ol> |
| 36 | </li> |
| 37 | |
| 38 | <li> |
| 39 | <a href="#layout_details">Layout Details</a> |
| 40 | <ol> |
| 41 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 42 | <a href="#imports">Imports</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 43 | </li> |
| 44 | |
| 45 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 46 | <a href="#variables">Variables</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 47 | </li> |
| 48 | |
| 49 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 50 | <a href="#custom_binding_class_names">Custom Binding Class Names</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 51 | </li> |
| 52 | |
| 53 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 54 | <a href="#includes">Includes</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 55 | </li> |
| 56 | |
| 57 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 58 | <a href="#expression_language">Expression Language</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 59 | </li> |
| 60 | </ol> |
| 61 | </li> |
| 62 | |
| 63 | <li> |
| 64 | <a href="#data_objects">Data Objects</a> |
| 65 | <ol> |
| 66 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 67 | <a href="#observable_objects">Observable Objects</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 68 | </li> |
| 69 | |
| 70 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 71 | <a href="#observablefields">ObservableFields</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 72 | </li> |
| 73 | |
| 74 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 75 | <a href="#observable_collections">Observable Collections</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 76 | </li> |
| 77 | </ol> |
| 78 | </li> |
| 79 | |
| 80 | <li> |
| 81 | <a href="#generated_binding">Generated Binding</a> |
| 82 | <ol> |
| 83 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 84 | <a href="#creating">Creating</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 85 | </li> |
| 86 | |
| 87 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 88 | <a href="#views_with_ids">Views With IDs</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 89 | </li> |
| 90 | |
| 91 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 92 | <a href="#variables">Variables</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 93 | </li> |
| 94 | |
| 95 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 96 | <a href="#viewstubs">ViewStubs</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 97 | </li> |
| 98 | |
| 99 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 100 | <a href="#advanced_binding">Advanced Binding</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 101 | </li> |
| 102 | </ol> |
| 103 | </li> |
| 104 | |
| 105 | <li> |
| 106 | <a href="#attribute_setters">Attribute Setters</a> |
| 107 | <ol> |
| 108 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 109 | <a href="#automatic_setters">Automatic Setters</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 110 | </li> |
| 111 | |
| 112 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 113 | <a href="#renamed_setters">Renamed Setters</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 114 | </li> |
| 115 | |
| 116 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 117 | <a href="#custom_setters">Custom Setters</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 118 | </li> |
| 119 | </ol> |
| 120 | </li> |
| 121 | |
| 122 | <li> |
| 123 | <a href="#converters">Converters</a> |
| 124 | <ol> |
| 125 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 126 | <a href="#object_conversions">Object Conversions</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 127 | </li> |
| 128 | |
| 129 | <li> |
Dirk Dougherty | 518651c | 2015-05-27 20:24:37 -0700 | [diff] [blame] | 130 | <a href="#custom_conversions">Custom Conversions</a> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 131 | </li> |
| 132 | </ol> |
| 133 | </li> |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 134 | |
| 135 | <li> |
| 136 | <a href="#studio_support">Android Studio Support for Data Binding</a> |
| 137 | </li> |
| 138 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 139 | </ol> |
| 140 | </div><!-- qv --> |
| 141 | </div><!-- qv-wrapper --> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 142 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 143 | <p> |
| 144 | This document explains how to use the Data Binding Library to write |
| 145 | declarative layouts and minimize the glue code necessary to bind your |
| 146 | application logic and layouts. |
| 147 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 148 | |
Claudio Cherubino | b6e91df | 2015-08-21 14:49:09 -0700 | [diff] [blame] | 149 | <p>The Data Binding Library offers both flexibility and broad compatibility |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 150 | — it's a support library, so you can use it with all Android platform |
| 151 | versions back to <strong>Android 2.1</strong> (API level 7+).</p> |
| 152 | |
sreevanis | 1a1d5db | 2015-10-30 14:44:51 -0700 | [diff] [blame] | 153 | <p>To use data binding, Android Plugin for Gradle <strong>1.5.0-alpha1</strong> |
Dirk Dougherty | bcab182 | 2015-06-02 14:05:31 -0700 | [diff] [blame] | 154 | or higher is required.</p> |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 155 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 156 | <h2 id="build_environment"> |
| 157 | Build Environment |
| 158 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 159 | |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 160 | <p>To get started with Data Binding, download the library from the Support |
| 161 | repository in the Android SDK manager. </p> |
| 162 | |
sreevanis | 1a1d5db | 2015-10-30 14:44:51 -0700 | [diff] [blame] | 163 | <p> |
| 164 | To configure your app to use data binding, add the <code>dataBinding</code> element to your |
sreevanis | 0cd6203 | 2015-11-03 09:57:57 -0800 | [diff] [blame] | 165 | <code>build.gradle</code> file in the app module. |
| 166 | </p> |
| 167 | |
| 168 | <p>Use the following code snippet to configure data binding: </p> |
sreevanis | 1a1d5db | 2015-10-30 14:44:51 -0700 | [diff] [blame] | 169 | |
| 170 | <pre> |
| 171 | android { |
| 172 | .... |
| 173 | dataBinding { |
| 174 | enabled = true |
| 175 | } |
| 176 | } |
| 177 | </pre> |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 178 | |
sreevanis | 0cd6203 | 2015-11-03 09:57:57 -0800 | [diff] [blame] | 179 | <p>If you have an app module that depends on a library which uses data binding, your app module |
| 180 | must configure data binding in its <code>build.gradle</code> file as well.</p> |
| 181 | |
Dirk Dougherty | bcab182 | 2015-06-02 14:05:31 -0700 | [diff] [blame] | 182 | <p>Also, make sure you are using a compatible version of Android Studio. |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 183 | <strong>Android Studio 1.3</strong> and later provides support for data binding as described in |
| 184 | <a href="#studio_support">Android Studio Support for Data Binding</a>. |
| 185 | </p> |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 186 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 187 | <h2 id="data_binding_layout_files"> |
| 188 | Data Binding Layout Files |
| 189 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 190 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 191 | <h3 id="writing_expressions"> |
| 192 | Writing your first data binding expressions |
| 193 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 194 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 195 | <p> |
| 196 | Data-binding layout files are slightly different and start with a root tag of |
| 197 | <strong>layout</strong> followed by a <strong>data</strong> element and a |
| 198 | <strong>view</strong> root element. This view element is what your root would |
| 199 | be in a non-binding layout file. A sample file looks like this: |
| 200 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 201 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 202 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 203 | <?xml version="1.0" encoding="utf-8"?> |
| 204 | <layout xmlns:android="http://schemas.android.com/apk/res/android"> |
| 205 | <data> |
| 206 | <variable name="user" type="com.example.User"/> |
| 207 | </data> |
| 208 | <LinearLayout |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 209 | android:orientation="vertical" |
| 210 | android:layout_width="match_parent" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 211 | android:layout_height="match_parent"> |
| 212 | <TextView android:layout_width="wrap_content" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 213 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 214 | android:text="@{user.firstName}"/> |
| 215 | <TextView android:layout_width="wrap_content" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 216 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 217 | android:text="@{user.lastName}"/> |
| 218 | </LinearLayout> |
| 219 | </layout> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 220 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 221 | <p> |
| 222 | The user <strong>variable</strong> within <strong>data</strong> describes a |
| 223 | property that may be used within this layout. |
| 224 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 225 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 226 | <pre> |
| 227 | <<strong>variable name="user" type="com.example.User"</strong>/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 228 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 229 | <p> |
| 230 | Expressions within the layout are written in the attribute properties using |
| 231 | the “<code>@{}</code>” syntax. Here, the TextView’s text is set to the |
| 232 | firstName property of user: |
| 233 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 234 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 235 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 236 | <TextView android:layout_width="wrap_content" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 237 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 238 | android:text="@{user.firstName}"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 239 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 240 | <h3 id="data_object"> |
| 241 | Data Object |
| 242 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 243 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 244 | <p> |
| 245 | Let’s assume for now that you have a plain-old Java object (POJO) for User: |
| 246 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 247 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 248 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 249 | public class User { |
| 250 | public final String firstName; |
| 251 | public final String lastName; |
| 252 | public User(String firstName, String lastName) { |
| 253 | this.firstName = firstName; |
| 254 | this.lastName = lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 255 | } |
| 256 | } |
| 257 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 258 | <p> |
| 259 | This type of object has data that never changes. It is common in applications |
| 260 | to have data that is read once and never changes thereafter. It is also |
| 261 | possible to use a JavaBeans objects: |
| 262 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 263 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 264 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 265 | public class User { |
| 266 | private final String firstName; |
| 267 | private final String lastName; |
| 268 | public User(String firstName, String lastName) { |
| 269 | this.firstName = firstName; |
| 270 | this.lastName = lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 271 | } |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 272 | public String getFirstName() { |
| 273 | return this.firstName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 274 | } |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 275 | public String getLastName() { |
| 276 | return this.lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 277 | } |
| 278 | } |
| 279 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 280 | <p> |
| 281 | From the perspective of data binding, these two classes are equivalent. The |
| 282 | expression <strong><code>@{user.firstName}</code></strong> used for |
| 283 | the TextView’s <strong><code>android:text</code></strong> attribute will |
| 284 | access the <strong><code>firstName</code></strong> field in the former class |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 285 | and the <code>getFirstName()</code> method in the latter class. Alternatively, it |
| 286 | will also be resolved to <code>firstName()</code> if that method exists. |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 287 | </p> |
| 288 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 289 | <h3 id="binding_data"> |
| 290 | Binding Data |
| 291 | </h3> |
| 292 | |
| 293 | <p> |
| 294 | By default, a Binding class will be generated based on the name of the layout |
| 295 | file, converting it to Pascal case and suffixing “Binding” to it. The above |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 296 | layout file was <code>main_activity.xml</code> so the generate class was |
| 297 | <code>MainActivityBinding</code>. This class holds all the bindings from the |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 298 | layout properties (e.g. the <code>user</code> variable) to the layout’s Views |
| 299 | and knows how to assign values for the binding expressions.The easiest means |
| 300 | for creating the bindings is to do it while inflating: |
| 301 | </p> |
| 302 | |
| 303 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 304 | @Override |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 305 | protected void onCreate(Bundle savedInstanceState) { |
| 306 | super.onCreate(savedInstanceState); |
| 307 | MainActivityBinding binding = DataBindingUtil.setContentView(this, R.layout.main_activity); |
| 308 | User user = new User("Test", "User"); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 309 | binding.setUser(user); |
| 310 | } |
| 311 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 312 | <p> |
| 313 | You’re done! Run the application and you’ll see Test User in the UI. |
| 314 | Alternatively, you can get the view via: |
| 315 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 316 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 317 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 318 | MainActivityBinding binding = MainActivityBinding.<em>inflate</em>(getLayoutInflater()); |
| 319 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 320 | <p> |
| 321 | If you are using data binding items inside a ListView or RecyclerView |
| 322 | adapter, you may prefer to use: |
| 323 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 324 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 325 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 326 | ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 327 | //or |
| 328 | ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.layout.<em><strong>list_item</strong></em>, viewGroup, <strong>false</strong>); |
| 329 | </pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 330 | |
| 331 | <h3 id="binding_events"> |
| 332 | Binding Events |
| 333 | </h3> |
| 334 | <p> |
| 335 | Events may be bound to handler methods directly, similar to the way |
| 336 | <strong><code>android:onClick</code></strong> can be assigned to a method in the Activity. |
| 337 | Event attribute names are governed by the name of the listener method with a few exceptions. |
| 338 | For example, {@link android.view.View.OnLongClickListener} has a method {@link android.view.View.OnLongClickListener#onLongClick onLongClick()}, |
| 339 | so the attribute for this event is <code>android:onLongClick</code>. |
| 340 | </p> |
| 341 | <p> |
| 342 | To assign an event to its handler, use a normal binding expression, with the value |
| 343 | being the method name to call. For example, if your data object has two methods: |
| 344 | </p> |
| 345 | <pre>public class MyHandlers { |
| 346 | public void onClickFriend(View view) { ... } |
| 347 | public void onClickEnemy(View view) { ... } |
| 348 | } |
| 349 | </pre> |
| 350 | <p> |
| 351 | The binding expression can assign the click listener for a View: |
| 352 | </p> |
| 353 | <pre> |
| 354 | <?xml version="1.0" encoding="utf-8"?> |
| 355 | <layout xmlns:android="http://schemas.android.com/apk/res/android"> |
| 356 | <data> |
| 357 | <variable name="handlers" type="com.example.Handlers"/> |
| 358 | <variable name="user" type="com.example.User"/> |
| 359 | </data> |
| 360 | <LinearLayout |
| 361 | android:orientation="vertical" |
| 362 | android:layout_width="match_parent" |
| 363 | android:layout_height="match_parent"> |
| 364 | <TextView android:layout_width="wrap_content" |
| 365 | android:layout_height="wrap_content" |
| 366 | android:text="@{user.firstName}" |
| 367 | android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> |
| 368 | <TextView android:layout_width="wrap_content" |
| 369 | android:layout_height="wrap_content" |
| 370 | android:text="@{user.lastName}" |
| 371 | android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> |
| 372 | </LinearLayout> |
| 373 | </layout> |
| 374 | </pre> |
George Mount | 9b332f3 | 2016-01-28 14:31:25 -0800 | [diff] [blame] | 375 | |
| 376 | <p> |
| 377 | Some specialized click event handlers exist and they need an attribute other than |
| 378 | <code>android:onClick</code> to avoid a conflict. The following attributes have been created |
| 379 | to avoid such conflicts: |
| 380 | </p> |
| 381 | |
| 382 | <table> |
| 383 | <tr> |
| 384 | <th>Class</th> |
| 385 | <th>Listener Setter</th> |
| 386 | <th>Attribute</th> |
| 387 | </tr> |
| 388 | <tr> |
| 389 | <td>{@link android.widget.SearchView}</td> |
| 390 | <td>{@link android.widget.SearchView#setOnSearchClickListener}</td> |
| 391 | <td><code>android:onSearchClick</code></td> |
| 392 | </tr> |
| 393 | <tr> |
| 394 | <td>{@link android.widget.ZoomControls}</td> |
| 395 | <td>{@link android.widget.ZoomControls#setOnZoomInClickListener}</td> |
| 396 | <td><code>android:onZoomIn</code></td> |
| 397 | </tr> |
| 398 | <tr> |
| 399 | <td>{@link android.widget.ZoomControls}</td> |
| 400 | <td>{@link android.widget.ZoomControls#setOnZoomOutClickListener}</td> |
| 401 | <td><code>android:onZoomOut</code></td> |
| 402 | </tr> |
| 403 | </table> |
| 404 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 405 | <h2 id="layout_details"> |
| 406 | Layout Details |
| 407 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 408 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 409 | <h3 id="imports"> |
| 410 | Imports |
| 411 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 412 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 413 | <p> |
| 414 | Zero or more <strong><code>import</code></strong> elements may be used inside |
| 415 | the <strong><code>data</code></strong> element. These allow easy reference to |
| 416 | classes inside your layout file, just like in Java. |
| 417 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 418 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 419 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 420 | <data> |
| 421 | <import type="android.view.View"/> |
| 422 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 423 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 424 | <p> |
| 425 | Now, View may be used within your binding expression: |
| 426 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 427 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 428 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 429 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 430 | android:text="@{user.lastName}" |
| 431 | android:layout_width="wrap_content" |
| 432 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 433 | android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 434 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 435 | <p> |
| 436 | When there are class name conflicts, one of the classes may be renamed to an |
| 437 | “alias:” |
| 438 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 439 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 440 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 441 | <import type="android.view.View"/> |
| 442 | <import type="com.example.real.estate.View" |
| 443 | alias="Vista"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 444 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 445 | <p> |
| 446 | Now, <strong><code>Vista</code></strong> may be used to reference the |
| 447 | <code>com.example.real.estate.View</code> and |
| 448 | <strong><code>View</code></strong> may be used to reference |
| 449 | <code>android.view.View</code> within the layout file. Imported types may be |
| 450 | used as type references in variables and expressions: |
| 451 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 452 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 453 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 454 | <data> |
| 455 | <import type="com.example.User"/> |
| 456 | <import type="java.util.List"/> |
| 457 | <variable name="user" type="User"/> |
| 458 | <variable name="userList" type="List&lt;User>"/> |
| 459 | </data> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 460 | </pre> |
Dirk Dougherty | 08710f1 | 2015-05-28 22:01:36 -0700 | [diff] [blame] | 461 | <p class="caution"> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 462 | <strong>Note</strong>: Android Studio does not yet handle imports so the |
| 463 | autocomplete for imported variables may not work in your IDE. Your |
| 464 | application will still compile fine and you can work around the IDE issue by |
| 465 | using fully qualified names in your variable definitions. |
| 466 | </p> |
| 467 | |
| 468 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 469 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 470 | android:text="@{((User)(user.connection)).lastName}" |
| 471 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 472 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 473 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 474 | <p> |
| 475 | Imported types may also be used when referencing static fields and methods in |
| 476 | expressions: |
| 477 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 478 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 479 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 480 | <data> |
| 481 | <import type="com.example.MyStringUtils"/> |
| 482 | <variable name="user" type="com.example.User"/> |
| 483 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 484 | … |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 485 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 486 | android:text="@{MyStringUtils.capitalize(user.lastName)}" |
| 487 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 488 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 489 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 490 | <p> |
| 491 | Just as in Java, <code>java.lang.*</code> is imported automatically. |
| 492 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 493 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 494 | <h3 id="variables"> |
| 495 | Variables |
| 496 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 497 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 498 | <p> |
| 499 | Any number of <strong><code>variable</code></strong> elements may be used |
| 500 | inside the <strong><code>data</code></strong> element. Each |
| 501 | <strong><code>variable</code></strong> element describes a property that may |
| 502 | be set on the layout to be used in binding expressions within the layout |
| 503 | file. |
| 504 | </p> |
| 505 | |
| 506 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 507 | <data> |
| 508 | <import type="android.graphics.drawable.Drawable"/> |
| 509 | <variable name="user" type="com.example.User"/> |
| 510 | <variable name="image" type="Drawable"/> |
| 511 | <variable name="note" type="String"/> |
| 512 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 513 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 514 | <p> |
| 515 | The variable types are inspected at compile time, so if a variable implements |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 516 | {@link android.databinding.Observable} or is an <a href= |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 517 | "#observable_collections">observable collection</a>, that should be reflected |
| 518 | in the type. If the variable is a base class or interface that does not |
| 519 | implement the Observable* interface, the variables will <strong>not |
| 520 | be</strong> observed! |
| 521 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 522 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 523 | <p> |
| 524 | When there are different layout files for various configurations (e.g. |
| 525 | landscape or portrait), the variables will be combined. There must not be |
| 526 | conflicting variable definitions between these layout files. |
| 527 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 528 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 529 | <p> |
| 530 | The generated binding class will have a setter and getter for each of the |
| 531 | described variables. The variables will take the default Java values until |
| 532 | the setter is called — <code>null</code> for reference types, |
| 533 | <code>0</code> for <code>int</code>, <code>false</code> for |
| 534 | <code>boolean</code>, etc. |
| 535 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 536 | |
George Mount | 9b332f3 | 2016-01-28 14:31:25 -0800 | [diff] [blame] | 537 | <p> |
| 538 | A special variable named <code>context</code> is generated for use in binding |
| 539 | expressions as needed. The value for <code>context</code> is the |
| 540 | <code>Context</code> from the root View's {@link android.view.View#getContext}. |
| 541 | The <code>context</code> variable will be overridden by an explicit variable |
| 542 | declaration with that name. |
| 543 | </p> |
| 544 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 545 | <h3 id="custom_binding_class_names"> |
| 546 | Custom Binding Class Names |
| 547 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 548 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 549 | <p> |
| 550 | By default, a Binding class is generated based on the name of the layout |
| 551 | file, starting it with upper-case, removing underscores ( _ ) and |
| 552 | capitalizing the following letter and then suffixing “Binding”. This class |
| 553 | will be placed in a databinding package under the module package. For |
| 554 | example, the layout file <code>contact_item.xml</code> will generate |
| 555 | <code>ContactItemBinding</code>. If the module package is |
| 556 | <code>com.example.my.app</code>, then it will be placed in |
| 557 | <code>com.example.my.app.databinding</code>. |
| 558 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 559 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 560 | <p> |
| 561 | Binding classes may be renamed or placed in different packages by adjusting |
| 562 | the <strong><code>class</code></strong> attribute of the |
| 563 | <strong><code>data</code></strong> element. For example: |
| 564 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 565 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 566 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 567 | <data class="ContactItem"> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 568 | ... |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 569 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 570 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 571 | <p> |
| 572 | This generates the binding class as <code>ContactItem</code> in the |
| 573 | databinding package in the module package. If the class should be generated |
| 574 | in a different package within the module package, it may be prefixed with |
| 575 | “.”: |
| 576 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 577 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 578 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 579 | <data class=".ContactItem"> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 580 | ... |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 581 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 582 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 583 | <p> |
| 584 | In this case, <code>ContactItem</code> is generated in the module package |
| 585 | directly. Any package may be used if the full package is provided: |
| 586 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 587 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 588 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 589 | <data class="com.example.ContactItem"> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 590 | ... |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 591 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 592 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 593 | <h3 id="includes"> |
| 594 | Includes |
| 595 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 596 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 597 | <p> |
| 598 | Variables may be passed into an included layout's binding from the |
| 599 | containing layout by using the application namespace and the variable name in |
| 600 | an attribute: |
| 601 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 602 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 603 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 604 | <?xml version="1.0" encoding="utf-8"?> |
| 605 | <layout xmlns:android="http://schemas.android.com/apk/res/android" |
| 606 | xmlns:bind="http://schemas.android.com/apk/res-auto"> |
| 607 | <data> |
| 608 | <variable name="user" type="com.example.User"/> |
| 609 | </data> |
| 610 | <LinearLayout |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 611 | android:orientation="vertical" |
| 612 | android:layout_width="match_parent" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 613 | android:layout_height="match_parent"> |
| 614 | <include layout="@layout/name" |
| 615 | bind:user="@{user}"/> |
| 616 | <include layout="@layout/contact" |
| 617 | bind:user="@{user}"/> |
| 618 | </LinearLayout> |
| 619 | </layout> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 620 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 621 | <p> |
| 622 | Here, there must be a <code>user</code> variable in both the |
| 623 | <code>name.xml</code> and <code>contact.xml</code> layout files. |
| 624 | </p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 625 | <p> |
| 626 | Data binding does not support include as a direct child of a merge element. For example, |
| 627 | <strong>the following layout is not supported:</strong> |
| 628 | </p> |
| 629 | <pre> |
| 630 | <?xml version="1.0" encoding="utf-8"?> |
| 631 | <layout xmlns:android="http://schemas.android.com/apk/res/android" |
| 632 | xmlns:bind="http://schemas.android.com/apk/res-auto"> |
| 633 | <data> |
| 634 | <variable name="user" type="com.example.User"/> |
| 635 | </data> |
| 636 | <merge> |
| 637 | <include layout="@layout/name" |
| 638 | bind:user="@{user}"/> |
| 639 | <include layout="@layout/contact" |
| 640 | bind:user="@{user}"/> |
| 641 | </merge> |
| 642 | </layout> |
| 643 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 644 | <h3 id="expression_language"> |
| 645 | Expression Language |
| 646 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 647 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 648 | <h4 id="common_features"> |
| 649 | Common Features |
| 650 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 651 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 652 | <p> |
| 653 | The expression language looks a lot like a Java expression. These are the |
| 654 | same: |
| 655 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 656 | |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 657 | <ul> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 658 | <li>Mathematical <strong><code>+ - / * %</code></strong> |
| 659 | </li> |
| 660 | |
| 661 | <li>String concatenation <strong><code>+</code></strong> |
| 662 | </li> |
| 663 | |
| 664 | <li> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 665 | Logical <strong><code>&& ||</code></strong> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 666 | </li> |
| 667 | |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 668 | <li>Binary <strong><code>& | ^</code></strong> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 669 | </li> |
| 670 | |
| 671 | <li>Unary <strong><code>+ - ! ~</code></strong> |
| 672 | </li> |
| 673 | |
| 674 | <li>Shift <strong><code>>> >>> <<</code></strong> |
| 675 | </li> |
| 676 | |
| 677 | <li>Comparison <strong><code>== > < >= <=</code></strong> |
| 678 | </li> |
| 679 | |
| 680 | <li> |
| 681 | <strong><code>instanceof</code></strong> |
| 682 | </li> |
| 683 | |
| 684 | <li>Grouping <strong><code>()</code></strong> |
| 685 | </li> |
| 686 | |
| 687 | <li>Literals - character, String, numeric, <strong><code>null</code></strong> |
| 688 | </li> |
| 689 | |
| 690 | <li>Cast |
| 691 | </li> |
| 692 | |
| 693 | <li>Method calls |
| 694 | </li> |
| 695 | |
| 696 | <li>Field access |
| 697 | </li> |
| 698 | |
| 699 | <li>Array access <strong><code>[]</code></strong> |
| 700 | </li> |
| 701 | |
| 702 | <li>Ternary operator <strong><code>?:</code></strong> |
| 703 | </li> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 704 | </ul> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 705 | |
| 706 | <p> |
| 707 | Examples: |
| 708 | </p> |
| 709 | |
| 710 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 711 | android:text="@{String.valueOf(index + 1)}" |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 712 | android:visibility="@{age &lt; 13 ? View.GONE : View.VISIBLE}" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 713 | android:transitionName='@{"image_" + id}' |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 714 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 715 | <h4 id="missing_operations"> |
| 716 | Missing Operations |
| 717 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 718 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 719 | <p> |
| 720 | A few operations are missing from the expression syntax that you can use in |
| 721 | Java. |
| 722 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 723 | |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 724 | <ul> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 725 | <li> |
| 726 | <strong><code>this</code></strong> |
| 727 | </li> |
| 728 | |
| 729 | <li> |
| 730 | <strong><code>super</code></strong> |
| 731 | </li> |
| 732 | |
| 733 | <li> |
| 734 | <strong><code>new</code></strong> |
| 735 | </li> |
| 736 | |
| 737 | <li>Explicit generic invocation |
| 738 | </li> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 739 | </ul> |
| 740 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 741 | <h4 id="null_coalescing_operator"> |
| 742 | Null Coalescing Operator |
| 743 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 744 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 745 | <p> |
| 746 | The null coalescing operator (<strong><code>??</code></strong>) chooses the |
| 747 | left operand if it is not null or the right if it is null. |
| 748 | </p> |
| 749 | |
| 750 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 751 | <strong>android:text="@{user.displayName ?? user.lastName}"</strong> |
| 752 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 753 | <p> |
| 754 | This is functionally equivalent to: |
| 755 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 756 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 757 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 758 | <strong>android:text="@{user.displayName != null ? user.displayName : user.lastName}"</strong> |
| 759 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 760 | <h4 id="property_reference"> |
| 761 | Property Reference |
| 762 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 763 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 764 | <p> |
| 765 | The first was already discussed in the <a href= |
| 766 | "#writing_your_first_data_binding_expressions">Writing your first data |
| 767 | binding expressions</a> above: short form JavaBean references. When an |
| 768 | expression references a property on a class, it uses the same format for |
| 769 | fields, getters, and ObservableFields. |
| 770 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 771 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 772 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 773 | <strong>android:text="@{user.lastName}"</strong> |
| 774 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 775 | <h4> |
| 776 | Avoiding NullPointerException |
| 777 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 778 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 779 | <p> |
| 780 | Generated data binding code automatically checks for nulls and avoid null |
| 781 | pointer exceptions. For example, in the expression |
| 782 | <code>@{user.name}</code>, if <code>user</code> is null, |
| 783 | <code>user.name</code> will be assigned its default value (null). If you were |
| 784 | referencing <code>user.age</code>, where age is an <code>int</code>, then it |
| 785 | would default to 0. |
| 786 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 787 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 788 | <h4 id="collections"> |
| 789 | Collections |
| 790 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 791 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 792 | <p> |
| 793 | Common collections: arrays, lists, sparse lists, and maps, may be accessed |
| 794 | using the <code>[]</code> operator for convenience. |
| 795 | </p> |
| 796 | |
| 797 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 798 | <data> |
| 799 | <import type="android.util.SparseArray"/> |
| 800 | <import type="java.util.Map"/> |
| 801 | <import type="java.util.List"/> |
| 802 | <variable name="list" type="List&lt;String>"/> |
| 803 | <variable name="sparse" type="SparseArray&lt;String>"/> |
| 804 | <variable name="map" type="Map&lt;String, String>"/> |
| 805 | <variable name="index" type="int"/> |
| 806 | <variable name="key" type="String"/> |
| 807 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 808 | … |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 809 | android:text="@{list[index]}" |
| 810 | … |
| 811 | android:text="@{sparse[index]}" |
| 812 | … |
| 813 | android:text="@{map[key]}" |
| 814 | |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 815 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 816 | <h4 id="string_literals"> |
| 817 | String Literals |
| 818 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 819 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 820 | <p> |
| 821 | When using single quotes around the attribute value, it is easy to use double |
| 822 | quotes in the expression: |
| 823 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 824 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 825 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 826 | android:text='@{map["firstName"]}' |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 827 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 828 | <p> |
| 829 | It is also possible to use double quotes to surround the attribute value. |
| 830 | When doing so, String literals should either use the &quot; or back quote |
| 831 | (`). |
| 832 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 833 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 834 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 835 | android:text="@{map[`firstName`}" |
| 836 | android:text="@{map[&quot;firstName&quot;]}" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 837 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 838 | <h4 id="resources"> |
| 839 | Resources |
| 840 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 841 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 842 | <p> |
| 843 | It is possible to access resources as part of expressions using the normal |
| 844 | syntax: |
| 845 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 846 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 847 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 848 | android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 849 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 850 | <p> |
| 851 | Format strings and plurals may be evaluated by providing parameters: |
| 852 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 853 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 854 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 855 | android:text="@{@string/nameFormat(firstName, lastName)}" |
| 856 | android:text="@{@plurals/banana(bananaCount)}" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 857 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 858 | <p> |
| 859 | When a plural takes multiple parameters, all parameters should be passed: |
| 860 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 861 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 862 | <pre> |
| 863 | |
| 864 | Have an orange |
| 865 | Have %d oranges |
| 866 | |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 867 | android:text="@{@plurals/orange(orangeCount, orangeCount)}" |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 868 | </pre> |
| 869 | <p> |
| 870 | Some resources require explicit type evaluation. |
| 871 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 872 | |
| 873 | <table> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 874 | <tr> |
| 875 | <th> |
| 876 | Type |
| 877 | </th> |
| 878 | <th> |
| 879 | Normal Reference |
| 880 | </th> |
| 881 | <th> |
| 882 | Expression Reference |
| 883 | </th> |
| 884 | </tr> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 885 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 886 | <tr> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 887 | <td> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 888 | String[] |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 889 | </td> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 890 | <td> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 891 | @array |
| 892 | </td> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 893 | <td> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 894 | @stringArray |
| 895 | </td> |
| 896 | </tr> |
| 897 | |
| 898 | <tr> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 899 | <td> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 900 | int[] |
| 901 | </td> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 902 | <td> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 903 | @array |
| 904 | </td> |
| 905 | <td> |
| 906 | @intArray |
| 907 | </td> |
| 908 | </tr> |
| 909 | |
| 910 | <tr> |
| 911 | <td> |
| 912 | TypedArray |
| 913 | </td> |
| 914 | <td> |
| 915 | @array |
| 916 | </td> |
| 917 | <td> |
| 918 | @typedArray |
| 919 | </td> |
| 920 | </tr> |
| 921 | |
| 922 | <tr> |
| 923 | <td> |
| 924 | Animator |
| 925 | </td> |
| 926 | <td> |
| 927 | @animator |
| 928 | </td> |
| 929 | <td> |
| 930 | @animator |
| 931 | </td> |
| 932 | </tr> |
| 933 | |
| 934 | <tr> |
| 935 | <td> |
| 936 | StateListAnimator |
| 937 | </td> |
| 938 | <td> |
| 939 | @animator |
| 940 | </td> |
| 941 | <td> |
| 942 | @stateListAnimator |
| 943 | </td> |
| 944 | </tr> |
| 945 | |
| 946 | <tr> |
| 947 | <td> |
| 948 | color <code>int</code> |
| 949 | </td> |
| 950 | <td> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 951 | @color |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 952 | </td> |
| 953 | <td> |
| 954 | @color |
| 955 | </td> |
| 956 | </tr> |
| 957 | |
| 958 | <tr> |
| 959 | <td> |
| 960 | ColorStateList |
| 961 | </td> |
| 962 | <td> |
| 963 | @color |
| 964 | </td> |
| 965 | <td> |
| 966 | @colorStateList |
| 967 | </td> |
| 968 | </tr> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 969 | </table> |
| 970 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 971 | <h2 id="data_objects"> |
| 972 | Data Objects |
| 973 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 974 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 975 | <p> |
| 976 | Any plain old Java object (POJO) may be used for data binding, but modifying |
| 977 | a POJO will not cause the UI to update. The real power of data binding can be |
| 978 | used by giving your data objects the ability to notify when data changes. |
| 979 | There are three different data change notification mechanisms, |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 980 | <a href="#observable_objects">Observable objects</a>, |
| 981 | <a href="#observablefields">observable fields</a>, and |
| 982 | <a href="#observable_collections">observable collection</a>s. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 983 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 984 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 985 | <p> |
| 986 | When one of these observable data object is bound to the UI and a property of |
| 987 | the data object changes, the UI will be updated automatically. |
| 988 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 989 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 990 | <h3 id="observable_objects"> |
| 991 | Observable Objects |
| 992 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 993 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 994 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 995 | A class implementing the {@link android.databinding.Observable} interface |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 996 | will allow the binding to attach a single listener to a bound object to |
| 997 | listen for changes of all properties on that object. |
| 998 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 999 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1000 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1001 | The {@link android.databinding.Observable} interface has a mechanism to add and remove |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1002 | listeners, but notifying is up to the developer. To make development easier, |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1003 | a base class, {@link android.databinding.BaseObservable}, was created to implement the |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1004 | listener registration mechanism. The data class implementer is still |
| 1005 | responsible for notifying when the properties change. This is done by |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1006 | assigning a {@link android.databinding.Bindable} annotation to the getter and notifying in |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1007 | the setter. |
| 1008 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1009 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1010 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1011 | private static class User extends BaseObservable { |
| 1012 | private String firstName; |
| 1013 | private String lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1014 | @Bindable |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1015 | public String getFirstName() { |
| 1016 | return this.firstName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1017 | } |
| 1018 | @Bindable |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1019 | public String getLastName() { |
| 1020 | return this.lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1021 | } |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1022 | public void setFirstName(String firstName) { |
| 1023 | this.firstName = firstName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1024 | notifyPropertyChanged(BR.firstName); |
| 1025 | } |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1026 | public void setLastName(String lastName) { |
| 1027 | this.lastName = lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1028 | notifyPropertyChanged(BR.lastName); |
| 1029 | } |
| 1030 | } |
| 1031 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1032 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1033 | The {@link android.databinding.Bindable} annotation generates an entry in the BR class file |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1034 | during compilation. The BR class file will be generated in the module |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1035 | package. If the base class for data classes cannot be changed, the |
| 1036 | {@link android.databinding.Observable} interface may be implemented using the convenient |
| 1037 | {@link android.databinding.PropertyChangeRegistry} to store and notify listeners |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1038 | efficiently. |
| 1039 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1040 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1041 | <h3 id="observablefields"> |
| 1042 | ObservableFields |
| 1043 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1044 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1045 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1046 | A little work is involved in creating {@link android.databinding.Observable} classes, so |
| 1047 | developers who want to save time or have few properties may use |
| 1048 | {@link android.databinding.ObservableField} and its siblings |
| 1049 | {@link android.databinding.ObservableBoolean}, |
| 1050 | {@link android.databinding.ObservableByte}, |
| 1051 | {@link android.databinding.ObservableChar}, |
| 1052 | {@link android.databinding.ObservableShort}, |
| 1053 | {@link android.databinding.ObservableInt}, |
| 1054 | {@link android.databinding.ObservableLong}, |
| 1055 | {@link android.databinding.ObservableFloat}, |
| 1056 | {@link android.databinding.ObservableDouble}, and |
| 1057 | {@link android.databinding.ObservableParcelable}. |
| 1058 | <code>ObservableFields</code> are self-contained observable objects that have a single |
| 1059 | field. The primitive versions avoid boxing and unboxing during access operations. |
| 1060 | To use, create a public final field in the data class: |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1061 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1062 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1063 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1064 | private static class User { |
| 1065 | public final ObservableField<String> firstName = |
| 1066 | new ObservableField<>(); |
| 1067 | public final ObservableField<String> lastName = |
| 1068 | new ObservableField<>(); |
| 1069 | public final ObservableInt age = new ObservableInt(); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1070 | } |
| 1071 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1072 | <p> |
| 1073 | That's it! To access the value, use the set and get accessor methods: |
| 1074 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1075 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1076 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1077 | user.firstName.set("Google"); |
| 1078 | int age = user.age.get(); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1079 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1080 | <h3 id="observable_collections"> |
| 1081 | Observable Collections |
| 1082 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1083 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1084 | <p> |
| 1085 | Some applications use more dynamic structures to hold data. Observable |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1086 | collections allow keyed access to these data objects. |
| 1087 | {@link android.databinding.ObservableArrayMap} is |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1088 | useful when the key is a reference type, such as String. |
| 1089 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1090 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1091 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1092 | ObservableArrayMap<String, Object> user = new ObservableArrayMap<>(); |
| 1093 | user.put("firstName", "Google"); |
| 1094 | user.put("lastName", "Inc."); |
| 1095 | user.put("age", 17); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1096 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1097 | <p> |
| 1098 | In the layout, the map may be accessed through the String keys: |
| 1099 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1100 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1101 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1102 | <data> |
| 1103 | <import type="android.databinding.ObservableMap"/> |
| 1104 | <variable name="user" type="ObservableMap&lt;String, Object>"/> |
| 1105 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1106 | … |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1107 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1108 | android:text='@{user["lastName"]}' |
| 1109 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1110 | android:layout_height="wrap_content"/> |
| 1111 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1112 | android:text='@{String.valueOf(1 + (Integer)user["age"])}' |
| 1113 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1114 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1115 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1116 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1117 | {@link android.databinding.ObservableArrayList} is useful when the key is an integer: |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1118 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1119 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1120 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1121 | ObservableArrayList<Object> user = new ObservableArrayList<>(); |
| 1122 | user.add("Google"); |
| 1123 | user.add("Inc."); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1124 | user.add(17); |
| 1125 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1126 | <p> |
| 1127 | In the layout, the list may be accessed through the indices: |
| 1128 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1129 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1130 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1131 | <data> |
| 1132 | <import type="android.databinding.ObservableList"/> |
| 1133 | <import type="com.example.my.app.Fields"/> |
| 1134 | <variable name="user" type="ObservableList&lt;Object>"/> |
| 1135 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1136 | … |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1137 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1138 | android:text='@{user[Fields.LAST_NAME]}' |
| 1139 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1140 | android:layout_height="wrap_content"/> |
| 1141 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1142 | android:text='@{String.valueOf(1 + (Integer)user[Fields.AGE])}' |
| 1143 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1144 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1145 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1146 | <h2 id="generated_binding"> |
| 1147 | Generated Binding |
| 1148 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1149 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1150 | <p> |
| 1151 | The generated binding class links the layout variables with the Views within |
| 1152 | the layout. As discussed earlier, the name and package of the Binding may be |
| 1153 | <a href="#custom_binding_class_names">customized</a>. The Generated binding |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1154 | classes all extend {@link android.databinding.ViewDataBinding}. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1155 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1156 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1157 | <h3 id="creating"> |
| 1158 | Creating |
| 1159 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1160 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1161 | <p> |
| 1162 | The binding should be created soon after inflation to ensure that the View |
| 1163 | hierarchy is not disturbed prior to binding to the Views with expressions |
| 1164 | within the layout. There are a few ways to bind to a layout. The most common |
| 1165 | is to use the static methods on the Binding class.The inflate method inflates |
| 1166 | the View hierarchy and binds to it all it one step. There is a simpler |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1167 | version that only takes a {@link android.view.LayoutInflater} and one that takes a |
| 1168 | {@link android.view.ViewGroup} as well: |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1169 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1170 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1171 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1172 | MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater); |
| 1173 | MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater, viewGroup, false); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1174 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1175 | <p> |
| 1176 | If the layout was inflated using a different mechanism, it may be bound |
| 1177 | separately: |
| 1178 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1179 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1180 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1181 | MyLayoutBinding binding = MyLayoutBinding.bind(viewRoot); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1182 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1183 | <p> |
| 1184 | Sometimes the binding cannot be known in advance. In such cases, the binding |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1185 | can be created using the {@link android.databinding.DataBindingUtil} class: |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1186 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1187 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1188 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1189 | ViewDataBinding binding = DataBindingUtil.inflate(LayoutInflater, layoutId, |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1190 | parent, attachToParent); |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1191 | ViewDataBinding binding = DataBindingUtil.bindTo(viewRoot, layoutId); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1192 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1193 | <h3 id="views_with_ids"> |
| 1194 | Views With IDs |
| 1195 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1196 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1197 | <p> |
| 1198 | A public final field will be generated for each View with an ID in the |
| 1199 | layout. The binding does a single pass on the View hierarchy, extracting the |
| 1200 | Views with IDs. This mechanism can be faster than calling findViewById for |
| 1201 | several Views. For example: |
| 1202 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1203 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1204 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1205 | <layout xmlns:android="http://schemas.android.com/apk/res/android"> |
| 1206 | <data> |
| 1207 | <variable name="user" type="com.example.User"/> |
| 1208 | </data> |
| 1209 | <LinearLayout |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1210 | android:orientation="vertical" |
| 1211 | android:layout_width="match_parent" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1212 | android:layout_height="match_parent"> |
| 1213 | <TextView android:layout_width="wrap_content" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1214 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1215 | android:text="@{user.firstName}" |
| 1216 | android:id="@+id/firstName"/> |
| 1217 | <TextView android:layout_width="wrap_content" |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1218 | android:layout_height="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1219 | android:text="@{user.lastName}" |
| 1220 | android:id="@+id/lastName"/> |
| 1221 | </LinearLayout> |
| 1222 | </layout> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1223 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1224 | <p> |
| 1225 | Will generate a binding class with: |
| 1226 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1227 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1228 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1229 | public final TextView firstName; |
| 1230 | public final TextView lastName; |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1231 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1232 | <p> |
| 1233 | IDs are not nearly as necessary as without data binding, but there are still |
| 1234 | some instances where access to Views are still necessary from code. |
| 1235 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1236 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1237 | <h3 id="variables2"> |
| 1238 | Variables |
| 1239 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1240 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1241 | <p> |
| 1242 | Each variable will be given accessor methods. |
| 1243 | </p> |
| 1244 | |
| 1245 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1246 | <data> |
| 1247 | <import type="android.graphics.drawable.Drawable"/> |
| 1248 | <variable name="user" type="com.example.User"/> |
| 1249 | <variable name="image" type="Drawable"/> |
| 1250 | <variable name="note" type="String"/> |
| 1251 | </data> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1252 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1253 | <p> |
| 1254 | will generate setters and getters in the binding: |
| 1255 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1256 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1257 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1258 | public abstract com.example.User getUser(); |
| 1259 | public abstract void setUser(com.example.User user); |
| 1260 | public abstract Drawable getImage(); |
| 1261 | public abstract void setImage(Drawable image); |
| 1262 | public abstract String getNote(); |
| 1263 | public abstract void setNote(String note); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1264 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1265 | <h3 id="viewstubs"> |
| 1266 | ViewStubs |
| 1267 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1268 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1269 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1270 | {@link android.view.ViewStub}s are a little different from normal Views. They start off invisible |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1271 | and when they either are made visible or are explicitly told to inflate, they |
| 1272 | replace themselves in the layout by inflating another layout. |
| 1273 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1274 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1275 | <p> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1276 | Because the <code>ViewStub</code> essentially disappears from the View hierarchy, the View |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1277 | in the binding object must also disappear to allow collection. Because the |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1278 | Views are final, a {@link android.databinding.ViewStubProxy} object takes the place of the |
| 1279 | <code>ViewStub</code>, giving the developer access to the ViewStub when it exists and also |
| 1280 | access to the inflated View hierarchy when the <code>ViewStub</code> has been inflated. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1281 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1282 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1283 | <p> |
| 1284 | When inflating another layout, a binding must be established for the new |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1285 | layout. Therefore, the <code>ViewStubProxy</code> must listen to the <code>ViewStub</code>'s |
| 1286 | {@link android.view.ViewStub.OnInflateListener} and establish the binding at that time. Since |
| 1287 | only one can exist, the <code>ViewStubProxy</code> allows the developer to set an |
| 1288 | <code>OnInflateListener</code> on it that it will call after establishing the binding. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1289 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1290 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1291 | <h3 id="advanced_binding"> |
| 1292 | Advanced Binding |
| 1293 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1294 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1295 | <h4 id="dynamic_variables"> |
| 1296 | Dynamic Variables |
| 1297 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1298 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1299 | <p> |
| 1300 | At times, the specific binding class won't be known. For example, a |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1301 | {@link android.support.v7.widget.RecyclerView.Adapter} operating against arbitrary layouts |
| 1302 | won't know the specific binding class. It still must assign the binding value during the |
| 1303 | {@link android.support.v7.widget.RecyclerView.Adapter#onBindViewHolder}. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1304 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1305 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1306 | <p> |
| 1307 | In this example, all layouts that the RecyclerView binds to have an "item" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1308 | variable. The <code>BindingHolder</code> has a <code>getBinding</code> method returning the |
| 1309 | {@link android.databinding.ViewDataBinding} base. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1310 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1311 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1312 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1313 | public void onBindViewHolder(BindingHolder holder, int position) { |
| 1314 | final T item = mItems.get(position); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1315 | holder.getBinding().setVariable(BR.item, item); |
| 1316 | holder.getBinding().executePendingBindings(); |
| 1317 | } |
| 1318 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1319 | <h4 id="immediate_binding"> |
| 1320 | Immediate Binding |
| 1321 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1322 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1323 | <p> |
| 1324 | When a variable or observable changes, the binding will be scheduled to |
| 1325 | change before the next frame. There are times, however, when binding must be |
| 1326 | executed immediately. To force execution, use the |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1327 | {@link android.databinding.ViewDataBinding#executePendingBindings()} method. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1328 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1329 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1330 | <h4> |
| 1331 | Background Thread |
| 1332 | </h4> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1333 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1334 | <p> |
| 1335 | You can change your data model in a background thread as long as it is not a |
| 1336 | collection. Data binding will localize each variable / field while evaluating |
| 1337 | to avoid any concurrency issues. |
| 1338 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1339 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1340 | <h2 id="attribute_setters"> |
| 1341 | Attribute Setters |
| 1342 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1343 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1344 | <p> |
| 1345 | Whenever a bound value changes, the generated binding class must call a |
| 1346 | setter method on the View with the binding expression. The data binding |
| 1347 | framework has ways to customize which method to call to set the value. |
| 1348 | </p> |
| 1349 | |
| 1350 | <h3 id="automatic_setters"> |
| 1351 | Automatic Setters |
| 1352 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1353 | For an attribute, data binding tries to find the method setAttribute. The |
| 1354 | namespace for the attribute does not matter, only the attribute name itself. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1355 | <p> |
| 1356 | For example, an expression associated with TextView's attribute |
| 1357 | <strong><code>android:text</code></strong> will look for a setText(String). |
| 1358 | If the expression returns an int, data binding will search for a setText(int) |
| 1359 | method. Be careful to have the expression return the correct type, casting if |
| 1360 | necessary. Note that data binding will work even if no attribute exists with |
| 1361 | the given name. You can then easily "create" attributes for any setter by |
| 1362 | using data binding. For example, support DrawerLayout doesn't have any |
| 1363 | attributes, but plenty of setters. You can use the automatic setters to use |
| 1364 | one of these. |
| 1365 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1366 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1367 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1368 | <android.support.v4.widget.<strong>DrawerLayout |
| 1369 | android:layout_width="wrap_content" |
| 1370 | android:layout_height="wrap_content" |
| 1371 | app:scrimColor="@{@color/scrim}" |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1372 | app:drawerListener="@{fragment.drawerListener}"/></strong> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1373 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1374 | <h3 id="renamed_setters"> |
| 1375 | Renamed Setters |
| 1376 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1377 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1378 | <p> |
| 1379 | Some attributes have setters that don't match by name. For these |
| 1380 | methods, an attribute may be associated with the setter through |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1381 | {@link android.databinding.BindingMethods} annotation. This must be associated with |
| 1382 | a class and contains {@link android.databinding.BindingMethod} annotations, one for |
| 1383 | each renamed method. For example, the <strong><code>android:tint</code></strong> attribute |
| 1384 | is really associated with {@link android.widget.ImageView#setImageTintList}, not |
| 1385 | <code>setTint</code>. |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1386 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1387 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1388 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1389 | @BindingMethods({ |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1390 | @BindingMethod(type = "android.widget.ImageView", |
| 1391 | attribute = "android:tint", |
| 1392 | method = "setImageTintList"), |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1393 | }) |
| 1394 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1395 | <p> |
| 1396 | It is unlikely that developers will need to rename setters; the android |
| 1397 | framework attributes have already been implemented. |
| 1398 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1399 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1400 | <h3 id="custom_setters"> |
| 1401 | Custom Setters |
| 1402 | </h3> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1403 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1404 | <p> |
| 1405 | Some attributes need custom binding logic. For example, there is no |
| 1406 | associated setter for the <strong><code>android:paddingLeft</code></strong> |
| 1407 | attribute. Instead, <code>setPadding(left, top, right, bottom)</code> exists. |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1408 | A static binding adapter method with the {@link android.databinding.BindingAdapter} |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1409 | annotation allows the developer to customize how a setter for an attribute is |
| 1410 | called. |
| 1411 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1412 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1413 | <p> |
| 1414 | The android attributes have already had <code>BindingAdapter</code>s created. |
| 1415 | For example, here is the one for <code>paddingLeft</code>: |
| 1416 | </p> |
| 1417 | |
| 1418 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1419 | @BindingAdapter("android:paddingLeft") |
| 1420 | public static void setPaddingLeft(View view, int padding) { |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1421 | view.setPadding(padding, |
| 1422 | view.getPaddingTop(), |
| 1423 | view.getPaddingRight(), |
| 1424 | view.getPaddingBottom()); |
| 1425 | } |
| 1426 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1427 | <p> |
| 1428 | Binding adapters are useful for other types of customization. For example, a |
| 1429 | custom loader can be called off-thread to load an image. |
| 1430 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1431 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1432 | <p> |
| 1433 | Developer-created binding adapters will override the data binding default |
| 1434 | adapters when there is a conflict. |
| 1435 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1436 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1437 | <p> |
| 1438 | You can also have adapters that receive multiple parameters. |
| 1439 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1440 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1441 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1442 | @BindingAdapter({"bind:imageUrl", "bind:error"}) |
| 1443 | public static void loadImage(ImageView view, String url, Drawable error) { |
| 1444 | Picasso.with(view.getContext()).load(url).error(error).into(view); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1445 | } |
| 1446 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1447 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1448 | <ImageView app:imageUrl=“@{venue.imageUrl}” |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1449 | app:error=“@{@drawable/venueError}”/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1450 | </pre> |
| 1451 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1452 | <p> |
| 1453 | This adapter will be called if both <strong>imageUrl</strong> and |
| 1454 | <strong>error</strong> are used for an ImageView and <em>imageUrl</em> is a |
| 1455 | string and <em>error</em> is a drawable. |
| 1456 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1457 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1458 | <ul> |
| 1459 | <li>Custom namespaces are ignored during matching. |
| 1460 | </li> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1461 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1462 | <li>You can also write adapters for android namespace. |
| 1463 | </li> |
| 1464 | </ul> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1465 | |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1466 | <p> |
| 1467 | Binding adapter methods may optionally take the old values in their handlers. A method |
| 1468 | taking old and new values should have all old values for the attributes come first, followed |
| 1469 | by the new values: |
| 1470 | </p> |
| 1471 | <pre> |
| 1472 | @BindingAdapter("android:paddingLeft") |
| 1473 | public static void setPaddingLeft(View view, int oldPadding, int newPadding) { |
| 1474 | if (oldPadding != newPadding) { |
| 1475 | view.setPadding(newPadding, |
| 1476 | view.getPaddingTop(), |
| 1477 | view.getPaddingRight(), |
| 1478 | view.getPaddingBottom()); |
| 1479 | } |
| 1480 | } |
| 1481 | </pre> |
| 1482 | <p> |
| 1483 | Event handlers may only be used with interfaces or abstract classes with one abstract method. |
| 1484 | For example: |
| 1485 | </p> |
| 1486 | <pre> |
| 1487 | @BindingAdapter("android:onLayoutChange") |
| 1488 | public static void setOnLayoutChangeListener(View view, View.OnLayoutChangeListener oldValue, |
| 1489 | View.OnLayoutChangeListener newValue) { |
| 1490 | if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { |
| 1491 | if (oldValue != null) { |
| 1492 | view.removeOnLayoutChangeListener(oldValue); |
| 1493 | } |
| 1494 | if (newValue != null) { |
| 1495 | view.addOnLayoutChangeListener(newValue); |
| 1496 | } |
| 1497 | } |
| 1498 | } |
| 1499 | </pre> |
| 1500 | <p> |
| 1501 | When a listener has multiple methods, it must be split into multiple listeners. For example, |
| 1502 | {@link android.view.View.OnAttachStateChangeListener} has two methods: |
| 1503 | {@link android.view.View.OnAttachStateChangeListener#onViewAttachedToWindow onViewAttachedToWindow()} and |
| 1504 | {@link android.view.View.OnAttachStateChangeListener#onViewDetachedFromWindow onViewDetachedFromWindow()}. |
| 1505 | We must then create two interfaces to differentiate the attributes and handlers for them. |
| 1506 | </p> |
| 1507 | |
| 1508 | <pre> |
| 1509 | @TargetApi(VERSION_CODES.HONEYCOMB_MR1) |
| 1510 | public interface OnViewDetachedFromWindow { |
| 1511 | void onViewDetachedFromWindow(View v); |
| 1512 | } |
| 1513 | |
| 1514 | @TargetApi(VERSION_CODES.HONEYCOMB_MR1) |
| 1515 | public interface OnViewAttachedToWindow { |
| 1516 | void onViewAttachedToWindow(View v); |
| 1517 | } |
| 1518 | </pre> |
| 1519 | <p> |
| 1520 | Because changing one listener will also affect the other, we must have three different |
| 1521 | binding adapters, one for each attribute and one for both, should they both be set. |
| 1522 | </p> |
| 1523 | <pre> |
| 1524 | @BindingAdapter("android:onViewAttachedToWindow") |
| 1525 | public static void setListener(View view, OnViewAttachedToWindow attached) { |
| 1526 | setListener(view, null, attached); |
| 1527 | } |
| 1528 | |
| 1529 | @BindingAdapter("android:onViewDetachedFromWindow") |
| 1530 | public static void setListener(View view, OnViewDetachedFromWindow detached) { |
| 1531 | setListener(view, detached, null); |
| 1532 | } |
| 1533 | |
| 1534 | @BindingAdapter({"android:onViewDetachedFromWindow", "android:onViewAttachedToWindow"}) |
| 1535 | public static void setListener(View view, final OnViewDetachedFromWindow detach, |
| 1536 | final OnViewAttachedToWindow attach) { |
| 1537 | if (VERSION.SDK_INT >= VERSION_CODES.HONEYCOMB_MR1) { |
| 1538 | final OnAttachStateChangeListener newListener; |
| 1539 | if (detach == null && attach == null) { |
| 1540 | newListener = null; |
| 1541 | } else { |
| 1542 | newListener = new OnAttachStateChangeListener() { |
| 1543 | @Override |
| 1544 | public void onViewAttachedToWindow(View v) { |
| 1545 | if (attach != null) { |
| 1546 | attach.onViewAttachedToWindow(v); |
| 1547 | } |
| 1548 | } |
| 1549 | |
| 1550 | @Override |
| 1551 | public void onViewDetachedFromWindow(View v) { |
| 1552 | if (detach != null) { |
| 1553 | detach.onViewDetachedFromWindow(v); |
| 1554 | } |
| 1555 | } |
| 1556 | }; |
| 1557 | } |
| 1558 | final OnAttachStateChangeListener oldListener = ListenerUtil.trackListener(view, |
| 1559 | newListener, R.id.onAttachStateChangeListener); |
| 1560 | if (oldListener != null) { |
| 1561 | view.removeOnAttachStateChangeListener(oldListener); |
| 1562 | } |
| 1563 | if (newListener != null) { |
| 1564 | view.addOnAttachStateChangeListener(newListener); |
| 1565 | } |
| 1566 | } |
| 1567 | } |
| 1568 | </pre> |
| 1569 | <p> |
| 1570 | The above example is slightly more complicated than normal because View uses add and remove |
| 1571 | for the listener instead of a set method for {@link android.view.View.OnAttachStateChangeListener}. |
| 1572 | The <code>android.databinding.adapters.ListenerUtil</code> class helps keep track of the previous |
| 1573 | listeners so that they may be removed in the Binding Adaper. |
| 1574 | </p> |
| 1575 | <p> |
| 1576 | By annotating the interfaces <code>OnViewDetachedFromWindow</code> and |
| 1577 | <code>OnViewAttachedToWindow</code> with |
| 1578 | <code>@TargetApi(VERSION_CODES.HONEYCOMB_MR1)</code>, the data binding code |
| 1579 | generator knows that the listener should only be generated when running on Honeycomb MR1 |
| 1580 | and new devices, the same version supported by |
| 1581 | {@link android.view.View#addOnAttachStateChangeListener}. |
| 1582 | </p> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1583 | <h2 id="converters"> |
| 1584 | Converters |
| 1585 | </h2> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1586 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1587 | <h3 id="object_conversions"> |
| 1588 | Object Conversions |
| 1589 | </h3> |
| 1590 | |
| 1591 | <p> |
| 1592 | When an Object is returned from a binding expression, a setter will be chosen |
| 1593 | from the automatic, renamed, and custom setters. The Object will be cast to a |
| 1594 | parameter type of the chosen setter. |
| 1595 | </p> |
| 1596 | |
| 1597 | <p> |
| 1598 | This is a convenience for those using ObservableMaps to hold data. for |
| 1599 | example: |
| 1600 | </p> |
| 1601 | |
| 1602 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1603 | <TextView |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1604 | android:text='@{userMap["lastName"]}' |
| 1605 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1606 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1607 | </pre> |
| 1608 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1609 | <p> |
| 1610 | The <code>userMap</code> returns an Object and that Object will be automatically cast to |
| 1611 | parameter type found in the setter <code>setText(CharSequence)</code>. When there |
| 1612 | may be confusion about the parameter type, the developer will need |
| 1613 | to cast in the expression. |
| 1614 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1615 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1616 | <h3 id="custom_conversions">Custom Conversions</h3> |
| 1617 | |
| 1618 | <p> |
| 1619 | Sometimes conversions should be automatic between specific types. For |
| 1620 | example, when setting the background: |
| 1621 | </p> |
| 1622 | |
| 1623 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1624 | <View |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1625 | android:background="@{isError ? @color/red : @color/white}" |
| 1626 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1627 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1628 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1629 | <p> |
| 1630 | Here, the background takes a <code>Drawable</code>, but the color is an |
| 1631 | integer. Whenever a <code>Drawable</code> is expected and an integer is |
| 1632 | returned, the <code>int</code> should be converted to a |
| 1633 | <code>ColorDrawable</code>. This conversion is done using a static method |
| 1634 | with a BindingConversion annotation: |
| 1635 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1636 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1637 | <pre> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1638 | @BindingConversion |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1639 | public static ColorDrawable convertColorToDrawable(int color) { |
| 1640 | return new ColorDrawable(color); |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1641 | } |
| 1642 | </pre> |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1643 | <p> |
| 1644 | Note that conversions only happen at the setter level, so it is <strong>not |
| 1645 | allowed</strong> to mix types like this: |
| 1646 | </p> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1647 | |
Dirk Dougherty | ea1f6fb | 2015-05-26 20:31:12 -0700 | [diff] [blame] | 1648 | <pre> |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1649 | <View |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1650 | android:background="@{isError ? @drawable/error : @color/white}" |
| 1651 | android:layout_width="wrap_content" |
George Mount | 4ba1820 | 2015-07-27 12:39:28 -0700 | [diff] [blame] | 1652 | android:layout_height="wrap_content"/> |
Dirk Dougherty | 493ff3c | 2015-05-26 16:52:23 -0700 | [diff] [blame] | 1653 | </pre> |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 1654 | |
| 1655 | <h3 id="studio_support">Android Studio Support for Data Binding</h3> |
| 1656 | |
| 1657 | <p> |
Cheryl Potter | 8dd7eea | 2016-04-04 17:10:06 -0700 | [diff] [blame] | 1658 | Android Studio supports many of the code editing features for data binding code. |
| 1659 | For example, it supports the following features for data binding expressions:</p> |
| 1660 | <ul> |
| 1661 | <li>Syntax highlighting</li> |
| 1662 | <li>Flagging of expression language syntax errors</li> |
| 1663 | <li>XML code completion</li> |
| 1664 | <li>References, including <a class="external-link" |
| 1665 | href="https://www.jetbrains.com/help/idea/2016.1/navigation-in-source-code.html?origin=old_help"> |
| 1666 | navigation</a> (such as navigate to a declaration) and |
| 1667 | <a class="external-link" |
| 1668 | href="https://www.jetbrains.com/help/idea/2016.1/viewing-inline-documentation.html?origin=old_help"> |
| 1669 | quick documentation</a></li> |
| 1670 | </ul> |
| 1671 | |
| 1672 | <p class="note"><strong>Note:</strong> Arrays and a |
| 1673 | <a href="https://docs.oracle.com/javase/tutorial/java/generics/types.html" |
| 1674 | class="external-link">generic type</a>, such as the {@link |
| 1675 | android.databinding.Observable} class, might display |
| 1676 | errors when there are no errors.</p> |
| 1677 | |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 1678 | <p> |
Cheryl Potter | 8dd7eea | 2016-04-04 17:10:06 -0700 | [diff] [blame] | 1679 | The Preview pane displays default values for data binding expressions if |
| 1680 | provided. In the following |
| 1681 | example excerpt of an element from a layout XML file, the Preview pane displays |
| 1682 | the {@code PLACEHOLDER} default text value in the <code>TextView</code>. |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 1683 | </p> |
| 1684 | |
| 1685 | <pre> |
| 1686 | <TextView android:layout_width="wrap_content" |
| 1687 | android:layout_height="wrap_content" |
| 1688 | android:text="@{user.firstName, default=PLACEHOLDER}"/> |
| 1689 | </pre> |
| 1690 | |
| 1691 | <p> |
Cheryl Potter | 8dd7eea | 2016-04-04 17:10:06 -0700 | [diff] [blame] | 1692 | If you need to display a default value during the design phase of your project, |
| 1693 | you can also use tools attributes instead of default expression values, as |
| 1694 | described in |
| 1695 | <a class="external-link" |
| 1696 | href="http://tools.android.com/tips/layout-designtime-attributes"> |
Daniel Yu | daa41bb | 2015-12-08 10:58:07 -0800 | [diff] [blame] | 1697 | Designtime Layout Attributes</a>. |
Cheryl Potter | 8dd7eea | 2016-04-04 17:10:06 -0700 | [diff] [blame] | 1698 | </p> |
| 1699 | |