diff options
| author | George Mount <mount@google.com> | 2015-07-27 14:24:34 +0000 |
|---|---|---|
| committer | Android (Google) Code Review <android-gerrit@google.com> | 2015-07-27 14:24:34 +0000 |
| commit | 6397ae6a0aedb8c7d085bb8907fc46a0e5bd7065 (patch) | |
| tree | 5e4a430b6f1ce68625be38781d3461789e94a0d1 /docs/html | |
| parent | 95e6ae3ad1ba8647494f0b5007b7beee76493e03 (diff) | |
| parent | 8b33fd9a00d598924d0dc9d1280c0e1854d5288e (diff) | |
| download | frameworks_base-6397ae6a0aedb8c7d085bb8907fc46a0e5bd7065.zip frameworks_base-6397ae6a0aedb8c7d085bb8907fc46a0e5bd7065.tar.gz frameworks_base-6397ae6a0aedb8c7d085bb8907fc46a0e5bd7065.tar.bz2 | |
Merge "Update data binding for RC1." into mnc-preview-docs
Diffstat (limited to 'docs/html')
| -rw-r--r-- | docs/html/tools/data-binding/guide.jd | 732 |
1 files changed, 462 insertions, 270 deletions
diff --git a/docs/html/tools/data-binding/guide.jd b/docs/html/tools/data-binding/guide.jd index 7c4c15a..2de5bc2 100644 --- a/docs/html/tools/data-binding/guide.jd +++ b/docs/html/tools/data-binding/guide.jd @@ -28,6 +28,10 @@ page.tags="databinding", "layouts" <li> <a href="#binding_data">Binding Data</a> </li> + + <li> + <a href="#binding_events">Binding Events</a> + </li> </ol> </li> @@ -141,7 +145,7 @@ page.tags="databinding", "layouts" — it's a support library, so you can use it with all Android platform versions back to <strong>Android 2.1</strong> (API level 7+).</p> -<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta1</strong> +<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta4</strong> or higher is required.</p> <h4>Beta release</h4> @@ -187,9 +191,9 @@ or higher is required.</p> <p>To get started with Data Binding, download the library from the Support repository in the Android SDK manager. </p> -<p>The Data Binding plugin requires Android Plugin for Gradle <strong>1.3.0-beta1 -or higher</strong>, so update your build dependencies (in -<code>build.gradle</code>) as needed.</p> +<p>The Data Binding plugin requires Android Plugin for Gradle <strong>1.3.0-beta4 +or higher</strong>, so update your build dependencies (in the top-level +<code>build.gradle</code> file) as needed.</p> <p>Also, make sure you are using a compatible version of Android Studio. <strong>Android Studio 1.3</strong> adds the code-completion and layout-preview @@ -201,18 +205,18 @@ support for data binding.</p> <p> To set up your application to use data binding, add data binding to the class - path of your <code>build.gradle</code> file, right below "android". + path of your top-level <code>build.gradle</code> file, right below "android". </p> <pre> dependencies { - classpath <strong>"com.android.tools.build:gradle:1.3.0-beta1" - </strong>classpath <strong>"com.android.databinding:dataBinder:</strong>1.0-rc0" + classpath <strong>"com.android.tools.build:gradle:1.3.0-beta4"</strong> + classpath <strong>"com.android.databinding:dataBinder:1.0-rc1"</strong> } -} </pre> <p> - Then make sure jcenter is in the repositories list for your sub projects. + Then make sure jcenter is in the repositories list for your projects in the top-level + <code>build.gradle</code> file. </p> <pre> @@ -228,8 +232,8 @@ allprojects { </p> <pre> -apply plugin: ‘com.android.application' -apply plugin: '<strong>com.android.databinding</strong>' +apply plugin: 'com.android.application' +apply plugin: 'com.android.databinding' </pre> <p> The data binding plugin is going to add necessary <strong>provided</strong> @@ -252,23 +256,23 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<em><?</em><strong>xml version="1.0" encoding="utf-8"</strong><em>?> -</em><<strong>layout xmlns:android="http://schemas.android.com/apk/res/android"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>TextView android:layout_width="wrap_content" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong>/> - <<strong>TextView android:layout_width="wrap_content" + android:text="@{user.firstName}"/> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:text="@{user.lastName}"/> + </LinearLayout> +</layout> </pre> <p> The user <strong>variable</strong> within <strong>data</strong> describes a @@ -285,9 +289,9 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<<strong>TextView android:layout_width="wrap_content" +<TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong>/> + android:text="@{user.firstName}"/> </pre> <h3 id="data_object"> Data Object @@ -298,12 +302,12 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<strong>public class </strong>User { - <strong>public final </strong>String <strong>firstName</strong>; - <strong>public final </strong>String <strong>lastName</strong>; - <strong>public </strong>User(String firstName, String lastName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; - <strong>this</strong>.<strong>lastName </strong>= lastName; +public class User { + public final String firstName; + public final String lastName; + public User(String firstName, String lastName) { + this.firstName = firstName; + this.lastName = lastName; } } </pre> @@ -314,18 +318,18 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<strong>public class </strong>User { - <strong>private final </strong>String <strong>firstName</strong>; - <strong>private final </strong>String <strong>lastName</strong>; - <strong>public </strong>User(String firstName, String lastName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; - <strong>this</strong>.<strong>lastName </strong>= lastName; +public class User { + private final String firstName; + private final String lastName; + public User(String firstName, String lastName) { + this.firstName = firstName; + this.lastName = lastName; } - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>firstName</strong>; + public String getFirstName() { + return this.firstName; } - <strong>public </strong>String getLastName() { - <strong>return this</strong>.<strong>lastName</strong>; + public String getLastName() { + return this.lastName; } } </pre> @@ -334,7 +338,8 @@ apply plugin: '<strong>com.android.databinding</strong>' expression <strong><code>@{user.firstName}</code></strong> used for the TextView’s <strong><code>android:text</code></strong> attribute will access the <strong><code>firstName</code></strong> field in the former class - and the <code>getFirstName()</code> method in the latter class. + and the <code>getFirstName()</code> method in the latter class. Alternatively, it + will also be resolved to <code>firstName()</code> if that method exists. </p> <h3 id="binding_data"> @@ -344,8 +349,8 @@ apply plugin: '<strong>com.android.databinding</strong>' <p> By default, a Binding class will be generated based on the name of the layout file, converting it to Pascal case and suffixing “Binding” to it. The above - layout file was <code>activity_main.xml</code> so the generate class was - <code>ActivityMainBinding</code>. This class holds all the bindings from the + layout file was <code>main_activity.xml</code> so the generate class was + <code>MainActivityBinding</code>. This class holds all the bindings from the layout properties (e.g. the <code>user</code> variable) to the layout’s Views and knows how to assign values for the binding expressions.The easiest means for creating the bindings is to do it while inflating: @@ -353,10 +358,10 @@ apply plugin: '<strong>com.android.databinding</strong>' <pre> @Override -<strong>protected void </strong>onCreate(Bundle savedInstanceState) { - <strong>super</strong>.onCreate(savedInstanceState); - ActivityMainBinding binding = DataBindingUtil.<em>setContentView</em>(<strong>this</strong>, R.layout.<em><strong>main_activity</strong></em>); - User user = <strong>new </strong>User(<strong>"Test"</strong>, <strong>"User"</strong>); +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + MainActivityBinding binding = DataBindingUtil.setContentView(this, R.layout.main_activity); + User user = new User("Test", "User"); binding.setUser(user); } </pre> @@ -374,11 +379,55 @@ MainActivityBinding binding = MainActivityBinding.<em>inflate</em>(getLayoutInfl </p> <pre> -ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, -false); +ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false); //or ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.layout.<em><strong>list_item</strong></em>, viewGroup, <strong>false</strong>); </pre> + +<h3 id="binding_events"> + Binding Events +</h3> +<p> + Events may be bound to handler methods directly, similar to the way + <strong><code>android:onClick</code></strong> can be assigned to a method in the Activity. + Event attribute names are governed by the name of the listener method with a few exceptions. + For example, {@link android.view.View.OnLongClickListener} has a method {@link android.view.View.OnLongClickListener#onLongClick onLongClick()}, + so the attribute for this event is <code>android:onLongClick</code>. +</p> +<p> + To assign an event to its handler, use a normal binding expression, with the value + being the method name to call. For example, if your data object has two methods: +</p> +<pre>public class MyHandlers { + public void onClickFriend(View view) { ... } + public void onClickEnemy(View view) { ... } +} +</pre> +<p> + The binding expression can assign the click listener for a View: +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="handlers" type="com.example.Handlers"/> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout + android:orientation="vertical" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@{user.firstName}" + android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> + <TextView android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@{user.lastName}" + android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> + </LinearLayout> +</layout> +</pre> <h2 id="layout_details"> Layout Details </h2> @@ -394,20 +443,20 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.view.View"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.view.View"/> +</data> </pre> <p> Now, View may be used within your binding expression: </p> <pre> -<<strong>TextView +<TextView android:text="@{user.lastName}" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"</strong>/> + android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/> </pre> <p> When there are class name conflicts, one of the classes may be renamed to an @@ -415,9 +464,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>import type="android.view.View"</strong>/> -<<strong>import type="com.example.real.estate.View" - alias="Vista"</strong>/> +<import type="android.view.View"/> +<import type="com.example.real.estate.View" + alias="Vista"/> </pre> <p> Now, <strong><code>Vista</code></strong> may be used to reference the @@ -428,12 +477,12 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="com.example.User"</strong>/> - <<strong>import type="java.util.List"</strong>/> - <<strong>variable name="user" type="User"</strong>/> - <<strong>variable name="userList" type="List&lt;User>"</strong>/> - </<strong>data</strong>> +<data> + <import type="com.example.User"/> + <import type="java.util.List"/> + <variable name="user" type="User"/> + <variable name="userList" type="List&lt;User>"/> +</data> </pre> <p class="caution"> <strong>Note</strong>: Android Studio does not yet handle imports so the @@ -443,10 +492,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>TextView +<TextView android:text="@{((User)(user.connection)).lastName}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Imported types may also be used when referencing static fields and methods in @@ -454,15 +503,15 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="com.example.MyStringUtils"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> -</<strong>data</strong>> +<data> + <import type="com.example.MyStringUtils"/> + <variable name="user" type="com.example.User"/> +</data> … -<<strong>TextView +<TextView android:text="@{MyStringUtils.capitalize(user.lastName)}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Just as in Java, <code>java.lang.*</code> is imported automatically. @@ -481,16 +530,16 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.graphics.drawable.Drawable"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> - <<strong>variable name="image" type="Drawable"</strong>/> - <<strong>variable name="note" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.graphics.drawable.Drawable"/> + <variable name="user" type="com.example.User"/> + <variable name="image" type="Drawable"/> + <variable name="note" type="String"/> +</data> </pre> <p> The variable types are inspected at compile time, so if a variable implements - <a href="#observable_objects">Observable</a> or is an <a href= + {@link android.databinding.Observable} or is an <a href= "#observable_collections">observable collection</a>, that should be reflected in the type. If the variable is a base class or interface that does not implement the Observable* interface, the variables will <strong>not @@ -533,9 +582,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class="ContactItem"</strong>> +<data class="ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <p> This generates the binding class as <code>ContactItem</code> in the @@ -545,9 +594,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class=".ContactItem"</strong>> +<data class=".ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <p> In this case, <code>ContactItem</code> is generated in the module package @@ -555,9 +604,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class="com.example.ContactItem"</strong>> +<data class="com.example.ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <h3 id="includes"> Includes @@ -570,28 +619,46 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<em><?</em><strong>xml version="1.0" encoding="utf-8"</strong><em>?> -</em><<strong>layout xmlns:android="http://schemas.android.com/apk/res/android" -</strong> <strong> xmlns:bind="http://schemas.android.com/apk/res-auto"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:bind="http://schemas.android.com/apk/res-auto"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>include layout="@layout/name" - bind:user="@{user}"</strong>/> - <<strong>include layout="@layout/contact" - bind:user="@{user}"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:layout_height="match_parent"> + <include layout="@layout/name" + bind:user="@{user}"/> + <include layout="@layout/contact" + bind:user="@{user}"/> + </LinearLayout> +</layout> </pre> <p> Here, there must be a <code>user</code> variable in both the <code>name.xml</code> and <code>contact.xml</code> layout files. </p> - +<p> + Data binding does not support include as a direct child of a merge element. For example, + <strong>the following layout is not supported:</strong> +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:bind="http://schemas.android.com/apk/res-auto"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <merge> + <include layout="@layout/name" + bind:user="@{user}"/> + <include layout="@layout/contact" + bind:user="@{user}"/> + </merge> +</layout> +</pre> <h3 id="expression_language"> Expression Language </h3> @@ -613,10 +680,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </li> <li> - <code>L</code>ogical <strong><code>&& ||</code></strong> + Logical <strong><code>&& ||</code></strong> </li> - <li>Binary <strong><code>&</code> <code>|</code> <code>^</code></strong> + <li>Binary <strong><code>& | ^</code></strong> </li> <li>Unary <strong><code>+ - ! ~</code></strong> @@ -659,9 +726,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<strong>android:text="@{String.valueOf(index + 1)}" +android:text="@{String.valueOf(index + 1)}" android:visibility="@{age &lt; 13 ? View.GONE : View.VISIBLE}" -android:transitionName='@{"image_" + id}'</strong> +android:transitionName='@{"image_" + id}' </pre> <h4 id="missing_operations"> Missing Operations @@ -746,23 +813,23 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.util.SparseArray"</strong>/> - <<strong>import type="java.util.Map"</strong>/> - <<strong>import type="java.util.List"</strong>/> - <<strong>variable name="list" type="List<String>"</strong>/> - <<strong>variable name="sparse" type="SparseArray&lt;String>"</strong>/> - <<strong>variable name="map" type="Map&lt;String, String>"</strong>/> - <<strong>variable name="index" type="int"</strong>/> - <<strong>variable name="key" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.util.SparseArray"/> + <import type="java.util.Map"/> + <import type="java.util.List"/> + <variable name="list" type="List&lt;String>"/> + <variable name="sparse" type="SparseArray&lt;String>"/> + <variable name="map" type="Map&lt;String, String>"/> + <variable name="index" type="int"/> + <variable name="key" type="String"/> +</data> +… +android:text="@{list[index]}" … -<strong>android:text="@{list[index]}" -</strong>… -<strong>android:text="@{sparse[index]}" -</strong>… -<strong>android:text="@{map[key]}" -</strong> +android:text="@{sparse[index]}" +… +android:text="@{map[key]}" + </pre> <h4 id="string_literals"> String Literals @@ -774,7 +841,7 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<strong>android:text='@{map["firstName"]}'</strong> +android:text='@{map["firstName"]}' </pre> <p> It is also possible to use double quotes to surround the attribute value. @@ -783,8 +850,8 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<strong>android:text="@{map[`firstName`}" -android:text="@{map[&quot;firstName&quot;]}"</strong> +android:text="@{map[`firstName`}" +android:text="@{map[&quot;firstName&quot;]}" </pre> <h4 id="resources"> Resources @@ -796,15 +863,15 @@ android:text="@{map[&quot;firstName&quot;]}"</strong> </p> <pre> -<strong>android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"</strong> +android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}" </pre> <p> Format strings and plurals may be evaluated by providing parameters: </p> <pre> -<strong>android:text="@{@string/nameFormat(firstName, lastName)}" -android:text="@{@plurals/banana(bananaCount)}"</strong> +android:text="@{@string/nameFormat(firstName, lastName)}" +android:text="@{@plurals/banana(bananaCount)}" </pre> <p> When a plural takes multiple parameters, all parameters should be passed: @@ -815,7 +882,7 @@ android:text="@{@plurals/banana(bananaCount)}"</strong> Have an orange Have %d oranges -android:text="<strong>@{@plurals/orange(orangeCount, orangeCount)}</strong>" +android:text="@{@plurals/orange(orangeCount, orangeCount)}" </pre> <p> Some resources require explicit type evaluation. @@ -836,9 +903,7 @@ android:text="<strong>@{@plurals/orange(orangeCount, orangeCount)} <tr> <td> - <pre> -String[] -</pre> + String[] </td> <td> @array @@ -901,9 +966,7 @@ String[] color <code>int</code> </td> <td> - <pre> -@color -</pre> + @color </td> <td> @color @@ -932,8 +995,9 @@ String[] a POJO will not cause the UI to update. The real power of data binding can be used by giving your data objects the ability to notify when data changes. There are three different data change notification mechanisms, - <code>Observable</code> objects, <code>ObservableField</code>s, and - <code>observable collections</code>. + <a href="#observable_objects">Observable objects</a>, + <a href="#observablefields">observable fields</a>, and + <a href="#observable_collections">observable collection</a>s. </p> <p> @@ -946,49 +1010,49 @@ String[] </h3> <p> - A class implementing <code>android.databinding.Observable</code> interface + A class implementing the {@link android.databinding.Observable} interface will allow the binding to attach a single listener to a bound object to listen for changes of all properties on that object. </p> <p> - The <code>Observable</code> interface has a mechanism to add and remove + The {@link android.databinding.Observable} interface has a mechanism to add and remove listeners, but notifying is up to the developer. To make development easier, - a base class, <code>BaseObservable,</code> was created to implement the + a base class, {@link android.databinding.BaseObservable}, was created to implement the listener registration mechanism. The data class implementer is still responsible for notifying when the properties change. This is done by - assigning a <code>Bindable</code> annotation to the getter and notifying in + assigning a {@link android.databinding.Bindable} annotation to the getter and notifying in the setter. </p> <pre> -<strong>private static class </strong>User <strong>extends </strong>BaseObservable { - <strong>private </strong>String <strong>firstName</strong>; - <strong>private </strong>String <strong>lastName</strong>; +private static class User extends BaseObservable { + private String firstName; + private String lastName; @Bindable - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>firstName</strong>; + public String getFirstName() { + return this.firstName; } @Bindable - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>lastName</strong>; + public String getLastName() { + return this.lastName; } - <strong>public void </strong>setFirstName(String firstName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; + public void setFirstName(String firstName) { + this.firstName = firstName; notifyPropertyChanged(BR.firstName); } - <strong>public void </strong>setLastName(String lastName) { - <strong>this</strong>.<strong>lastName </strong>= lastName; + public void setLastName(String lastName) { + this.lastName = lastName; notifyPropertyChanged(BR.lastName); } } </pre> <p> - The <code>Bindable</code> annotation generates an entry in the BR class file + The {@link android.databinding.Bindable} annotation generates an entry in the BR class file during compilation. The BR class file will be generated in the module - package.If the base class for data classes cannot be changed, the - <code>Observable</code> interface may be implemented using the convenient - <code>PropertyChangeRegistry</code> to store and notify listeners + package. If the base class for data classes cannot be changed, the + {@link android.databinding.Observable} interface may be implemented using the convenient + {@link android.databinding.PropertyChangeRegistry} to store and notify listeners efficiently. </p> @@ -997,20 +1061,30 @@ String[] </h3> <p> - A little work is involved in creating Observable classes, so developers who - want to save time or have few properties may use ObservableFields. - ObservableFields are self-contained observable objects that have a single - field. There are versions for all primitive types and one for reference - types. To use, create a public final field in the data class: + A little work is involved in creating {@link android.databinding.Observable} classes, so + developers who want to save time or have few properties may use + {@link android.databinding.ObservableField} and its siblings + {@link android.databinding.ObservableBoolean}, + {@link android.databinding.ObservableByte}, + {@link android.databinding.ObservableChar}, + {@link android.databinding.ObservableShort}, + {@link android.databinding.ObservableInt}, + {@link android.databinding.ObservableLong}, + {@link android.databinding.ObservableFloat}, + {@link android.databinding.ObservableDouble}, and + {@link android.databinding.ObservableParcelable}. + <code>ObservableFields</code> are self-contained observable objects that have a single + field. The primitive versions avoid boxing and unboxing during access operations. + To use, create a public final field in the data class: </p> <pre> -<strong>private static class </strong>User <strong>extends </strong>BaseObservable { - <strong>public final </strong>ObservableField<String> <strong>firstName </strong>= - <strong>new </strong>ObservableField<>(); - <strong>public final </strong>ObservableField<String> <strong>lastName </strong>= - <strong>new </strong>ObservableField<>(); - <strong>public final </strong>ObservableInt <strong>age </strong>= <strong>new </strong>ObservableInt(); +private static class User { + public final ObservableField<String> firstName = + new ObservableField<>(); + public final ObservableField<String> lastName = + new ObservableField<>(); + public final ObservableInt age = new ObservableInt(); } </pre> <p> @@ -1018,8 +1092,8 @@ String[] </p> <pre> -user.<strong>firstName</strong>.set(<strong>"Google"</strong>); -<strong>int </strong>age = user.<strong>age</strong>.get(); +user.firstName.set("Google"); +int age = user.age.get(); </pre> <h3 id="observable_collections"> Observable Collections @@ -1027,43 +1101,44 @@ user.<strong>firstName</strong>.set(<strong>"Google"</strong>); <p> Some applications use more dynamic structures to hold data. Observable - collections allow keyed access to these data objects.ObservableArrayMap is + collections allow keyed access to these data objects. + {@link android.databinding.ObservableArrayMap} is useful when the key is a reference type, such as String. </p> <pre> -ObservableArrayMap<String, Object> user = <strong>new </strong>ObservableArrayMap<>(); -user.put(<strong>"firstName"</strong>, <strong>"Google"</strong>); -user.put(<strong>"lastName"</strong>, <strong>"Inc."</strong>); -user.put(<strong>"age"</strong>, 17); +ObservableArrayMap<String, Object> user = new ObservableArrayMap<>(); +user.put("firstName", "Google"); +user.put("lastName", "Inc."); +user.put("age", 17); </pre> <p> In the layout, the map may be accessed through the String keys: </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.databinding.ObservableMap"</strong>/> - <<strong>variable name="user" type="ObservableMap&lt;String, Object>"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.databinding.ObservableMap"/> + <variable name="user" type="ObservableMap&lt;String, Object>"/> +</data> … -<<strong>TextView +<TextView android:text='@{user["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> -<<strong>TextView + android:layout_height="wrap_content"/> +<TextView android:text='@{String.valueOf(1 + (Integer)user["age"])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> - ObservableArrayList is useful when the key is an integer: + {@link android.databinding.ObservableArrayList} is useful when the key is an integer: </p> <pre> -ObservableArrayList<Object> user = <strong>new </strong>ObservableArrayList<>(); -user.add(<strong>"Google"</strong>); -user.add(<strong>"Inc."</strong>); +ObservableArrayList<Object> user = new ObservableArrayList<>(); +user.add("Google"); +user.add("Inc."); user.add(17); </pre> <p> @@ -1071,20 +1146,20 @@ user.add(17); </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.databinding.ObservableList"</strong>/> - <<strong>import type="com.example.my.app.Fields"</strong>/> - <<strong>variable name="user" type="ObservableList&lt;Object>"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.databinding.ObservableList"/> + <import type="com.example.my.app.Fields"/> + <variable name="user" type="ObservableList&lt;Object>"/> +</data> … -<<strong>TextView +<TextView android:text='@{user[Fields.LAST_NAME]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> -<<strong>TextView + android:layout_height="wrap_content"/> +<TextView android:text='@{String.valueOf(1 + (Integer)user[Fields.AGE])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <h2 id="generated_binding"> Generated Binding @@ -1094,7 +1169,7 @@ user.add(17); The generated binding class links the layout variables with the Views within the layout. As discussed earlier, the name and package of the Binding may be <a href="#custom_binding_class_names">customized</a>. The Generated binding - classes all extend <code>android.databinding.ViewDataBinding</code>. + classes all extend {@link android.databinding.ViewDataBinding}. </p> <h3 id="creating"> @@ -1107,13 +1182,13 @@ user.add(17); within the layout. There are a few ways to bind to a layout. The most common is to use the static methods on the Binding class.The inflate method inflates the View hierarchy and binds to it all it one step. There is a simpler - version that only takes a <code>LayoutInflater</code> and one that takes a - <code>ViewGroup</code> as well: + version that only takes a {@link android.view.LayoutInflater} and one that takes a + {@link android.view.ViewGroup} as well: </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(<strong>layoutInflater</strong>); -MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(LayoutInflater, viewGroup, false); +MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater); +MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater, viewGroup, false); </pre> <p> If the layout was inflated using a different mechanism, it may be bound @@ -1121,17 +1196,17 @@ MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(LayoutInflater, viewG </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.<em>bind</em>(viewRoot); +MyLayoutBinding binding = MyLayoutBinding.bind(viewRoot); </pre> <p> Sometimes the binding cannot be known in advance. In such cases, the binding - can be created using the DataBindingUtil class: + can be created using the {@link android.databinding.DataBindingUtil} class: </p> <pre> -ViewDataBinding binding = DataBindingUtil.<em>inflate</em>(LayoutInflater, layoutId, +ViewDataBinding binding = DataBindingUtil.inflate(LayoutInflater, layoutId, parent, attachToParent); -ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); +ViewDataBinding binding = DataBindingUtil.bindTo(viewRoot, layoutId); </pre> <h3 id="views_with_ids"> Views With IDs @@ -1145,32 +1220,32 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); </p> <pre> -<<strong>layout xmlns:android="http://schemas.android.com/apk/res/android"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>TextView android:layout_width="wrap_content" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong> - <strong>android:id="@+id/firstName"</strong>/> - <<strong>TextView android:layout_width="wrap_content" + android:text="@{user.firstName}" + android:id="@+id/firstName"/> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}"</strong> - <strong>android:id="@+id/lastName"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:text="@{user.lastName}" + android:id="@+id/lastName"/> + </LinearLayout> +</layout> </pre> <p> Will generate a binding class with: </p> <pre> -<strong>public final </strong>TextView <strong>firstName</strong>; -<strong>public final </strong>TextView <strong>lastName</strong>; +public final TextView firstName; +public final TextView lastName; </pre> <p> IDs are not nearly as necessary as without data binding, but there are still @@ -1186,49 +1261,49 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.graphics.drawable.Drawable"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> - <<strong>variable name="image" type="Drawable"</strong>/> - <<strong>variable name="note" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.graphics.drawable.Drawable"/> + <variable name="user" type="com.example.User"/> + <variable name="image" type="Drawable"/> + <variable name="note" type="String"/> +</data> </pre> <p> will generate setters and getters in the binding: </p> <pre> -<strong>public abstract </strong>com.example.User getUser(); -<strong>public abstract void </strong>setUser(com.example.User user); -<strong>public abstract </strong>Drawable getImage(); -<strong>public abstract void </strong>setImage(Drawable image); -<strong>public abstract </strong>String getNote(); -<strong>public abstract void </strong>setNote(String note); +public abstract com.example.User getUser(); +public abstract void setUser(com.example.User user); +public abstract Drawable getImage(); +public abstract void setImage(Drawable image); +public abstract String getNote(); +public abstract void setNote(String note); </pre> <h3 id="viewstubs"> ViewStubs </h3> <p> - ViewStubs are a little different from normal Views. They start off invisible + {@link android.view.ViewStub}s are a little different from normal Views. They start off invisible and when they either are made visible or are explicitly told to inflate, they replace themselves in the layout by inflating another layout. </p> <p> - Because the ViewStub essentially disappears from the View hierarchy, the View + Because the <code>ViewStub</code> essentially disappears from the View hierarchy, the View in the binding object must also disappear to allow collection. Because the - Views are final, a ViewStubProxy object takes the place of the ViewStub, - giving the developer access to the ViewStub when it exists and also access to - the inflated View hierarchy when the ViewStub has been inflated. + Views are final, a {@link android.databinding.ViewStubProxy} object takes the place of the + <code>ViewStub</code>, giving the developer access to the ViewStub when it exists and also + access to the inflated View hierarchy when the <code>ViewStub</code> has been inflated. </p> <p> When inflating another layout, a binding must be established for the new - layout. Therefore, the ViewStubProxy must listen to the ViewStub's - OnInflateListener and establish the binding at that time. Since only one can - exist, the ViewStubProxy allows the developer to set an OnInflateListener on - it that it will call after establishing the binding. + layout. Therefore, the <code>ViewStubProxy</code> must listen to the <code>ViewStub</code>'s + {@link android.view.ViewStub.OnInflateListener} and establish the binding at that time. Since + only one can exist, the <code>ViewStubProxy</code> allows the developer to set an + <code>OnInflateListener</code> on it that it will call after establishing the binding. </p> <h3 id="advanced_binding"> @@ -1241,20 +1316,20 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); <p> At times, the specific binding class won't be known. For example, a - RecyclerView Adapter operating against arbitrary layouts won't know the - specific binding class. It still must assign the binding value during the - onBindViewHolder. + {@link android.support.v7.widget.RecyclerView.Adapter} operating against arbitrary layouts + won't know the specific binding class. It still must assign the binding value during the + {@link android.support.v7.widget.RecyclerView.Adapter#onBindViewHolder}. </p> <p> In this example, all layouts that the RecyclerView binds to have an "item" - variable. The BindingHolder has a getBinding method returning the - <code>ViewDataBinding</code> base. + variable. The <code>BindingHolder</code> has a <code>getBinding</code> method returning the + {@link android.databinding.ViewDataBinding} base. </p> <pre> -<strong>public void </strong>onBindViewHolder(BindingHolder holder, <strong>int </strong>position) { - <strong>final </strong>T item = <strong>mItems</strong>.get(position); +public void onBindViewHolder(BindingHolder holder, int position) { + final T item = mItems.get(position); holder.getBinding().setVariable(BR.item, item); holder.getBinding().executePendingBindings(); } @@ -1267,7 +1342,7 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); When a variable or observable changes, the binding will be scheduled to change before the next frame. There are times, however, when binding must be executed immediately. To force execution, use the - <code>executePendingBindings()</code> method. + {@link android.databinding.ViewDataBinding#executePendingBindings()} method. </p> <h4> @@ -1321,17 +1396,18 @@ namespace for the attribute does not matter, only the attribute name itself. <p> Some attributes have setters that don't match by name. For these methods, an attribute may be associated with the setter through - BindingMethods annotation. This must be associated with a class and contains - BindingMethod annotations, one for each renamed method. For example, the - <strong><code>android:tint</code></strong> attribute is really associated - with setImageTintList, not setTint. + {@link android.databinding.BindingMethods} annotation. This must be associated with + a class and contains {@link android.databinding.BindingMethod} annotations, one for + each renamed method. For example, the <strong><code>android:tint</code></strong> attribute + is really associated with {@link android.widget.ImageView#setImageTintList}, not + <code>setTint</code>. </p> <pre> @BindingMethods({ - @BindingMethod(type = <strong>"android.widget.ImageView"</strong>, - attribute = <strong>"android:tint"</strong>, - method = <strong>"setImageTintList"</strong>), + @BindingMethod(type = "android.widget.ImageView", + attribute = "android:tint", + method = "setImageTintList"), }) </pre> <p> @@ -1347,7 +1423,7 @@ namespace for the attribute does not matter, only the attribute name itself. Some attributes need custom binding logic. For example, there is no associated setter for the <strong><code>android:paddingLeft</code></strong> attribute. Instead, <code>setPadding(left, top, right, bottom)</code> exists. - A static binding adapter method with the <code>BindingAdapter</code> + A static binding adapter method with the {@link android.databinding.BindingAdapter} annotation allows the developer to customize how a setter for an attribute is called. </p> @@ -1358,9 +1434,8 @@ namespace for the attribute does not matter, only the attribute name itself. </p> <pre> - -@BindingAdapter(<strong>"android:paddingLeft"</strong>) -<strong>public static void </strong>setPaddingLeft(View view, <strong>int </strong>padding) { +@BindingAdapter("android:paddingLeft") +public static void setPaddingLeft(View view, int padding) { view.setPadding(padding, view.getPaddingTop(), view.getPaddingRight(), @@ -1382,9 +1457,9 @@ namespace for the attribute does not matter, only the attribute name itself. </p> <pre> -@BindingAdapter({<strong>"bind:imageUrl"</strong>, <strong>"bind:error"</strong>}) -<strong>public static void </strong>loadImage(ImageView view, String url, Drawable error) { - Picasso.<em>with</em>(view.getContext()).load(url).error(error).into(view); +@BindingAdapter({"bind:imageUrl", "bind:error"}) +public static void loadImage(ImageView view, String url, Drawable error) { + Picasso.with(view.getContext()).load(url).error(error).into(view); } </pre> <pre> @@ -1406,6 +1481,123 @@ app:error=“@{@drawable/venueError}”/> </li> </ul> +<p> + Binding adapter methods may optionally take the old values in their handlers. A method + taking old and new values should have all old values for the attributes come first, followed + by the new values: +</p> +<pre> +@BindingAdapter("android:paddingLeft") +public static void setPaddingLeft(View view, int oldPadding, int newPadding) { + if (oldPadding != newPadding) { + view.setPadding(newPadding, + view.getPaddingTop(), + view.getPaddingRight(), + view.getPaddingBottom()); + } +} +</pre> +<p> + Event handlers may only be used with interfaces or abstract classes with one abstract method. + For example: +</p> +<pre> +@BindingAdapter("android:onLayoutChange") +public static void setOnLayoutChangeListener(View view, View.OnLayoutChangeListener oldValue, + View.OnLayoutChangeListener newValue) { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + if (oldValue != null) { + view.removeOnLayoutChangeListener(oldValue); + } + if (newValue != null) { + view.addOnLayoutChangeListener(newValue); + } + } +} +</pre> +<p> + When a listener has multiple methods, it must be split into multiple listeners. For example, + {@link android.view.View.OnAttachStateChangeListener} has two methods: + {@link android.view.View.OnAttachStateChangeListener#onViewAttachedToWindow onViewAttachedToWindow()} and + {@link android.view.View.OnAttachStateChangeListener#onViewDetachedFromWindow onViewDetachedFromWindow()}. + We must then create two interfaces to differentiate the attributes and handlers for them. +</p> + +<pre> +@TargetApi(VERSION_CODES.HONEYCOMB_MR1) +public interface OnViewDetachedFromWindow { + void onViewDetachedFromWindow(View v); +} + +@TargetApi(VERSION_CODES.HONEYCOMB_MR1) +public interface OnViewAttachedToWindow { + void onViewAttachedToWindow(View v); +} +</pre> +<p> + Because changing one listener will also affect the other, we must have three different + binding adapters, one for each attribute and one for both, should they both be set. +</p> +<pre> +@BindingAdapter("android:onViewAttachedToWindow") +public static void setListener(View view, OnViewAttachedToWindow attached) { + setListener(view, null, attached); +} + +@BindingAdapter("android:onViewDetachedFromWindow") +public static void setListener(View view, OnViewDetachedFromWindow detached) { + setListener(view, detached, null); +} + +@BindingAdapter({"android:onViewDetachedFromWindow", "android:onViewAttachedToWindow"}) +public static void setListener(View view, final OnViewDetachedFromWindow detach, + final OnViewAttachedToWindow attach) { + if (VERSION.SDK_INT >= VERSION_CODES.HONEYCOMB_MR1) { + final OnAttachStateChangeListener newListener; + if (detach == null && attach == null) { + newListener = null; + } else { + newListener = new OnAttachStateChangeListener() { + @Override + public void onViewAttachedToWindow(View v) { + if (attach != null) { + attach.onViewAttachedToWindow(v); + } + } + + @Override + public void onViewDetachedFromWindow(View v) { + if (detach != null) { + detach.onViewDetachedFromWindow(v); + } + } + }; + } + final OnAttachStateChangeListener oldListener = ListenerUtil.trackListener(view, + newListener, R.id.onAttachStateChangeListener); + if (oldListener != null) { + view.removeOnAttachStateChangeListener(oldListener); + } + if (newListener != null) { + view.addOnAttachStateChangeListener(newListener); + } + } +} +</pre> +<p> + The above example is slightly more complicated than normal because View uses add and remove + for the listener instead of a set method for {@link android.view.View.OnAttachStateChangeListener}. + The <code>android.databinding.adapters.ListenerUtil</code> class helps keep track of the previous + listeners so that they may be removed in the Binding Adaper. +</p> +<p> + By annotating the interfaces <code>OnViewDetachedFromWindow</code> and + <code>OnViewAttachedToWindow</code> with + <code>@TargetApi(VERSION_CODES.HONEYCOMB_MR1)</code>, the data binding code + generator knows that the listener should only be generated when running on Honeycomb MR1 + and new devices, the same version supported by + {@link android.view.View#addOnAttachStateChangeListener}. +</p> <h2 id="converters"> Converters </h2> @@ -1426,10 +1618,10 @@ app:error=“@{@drawable/venueError}”/> </p> <pre> -<<strong>TextView +<TextView android:text='@{userMap["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> @@ -1447,10 +1639,10 @@ The <code>userMap</code> returns an Object and that Object will be automatically </p> <pre> -<<strong>View +<View android:background="@{isError ? @color/red : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Here, the background takes a <code>Drawable</code>, but the color is an @@ -1462,8 +1654,8 @@ The <code>userMap</code> returns an Object and that Object will be automatically <pre> @BindingConversion -<strong>public static </strong>ColorDrawable convertColorToDrawable(<strong>int </strong>color) { - <strong>return new </strong>ColorDrawable(color); +public static ColorDrawable convertColorToDrawable(int color) { + return new ColorDrawable(color); } </pre> <p> @@ -1472,8 +1664,8 @@ The <code>userMap</code> returns an Object and that Object will be automatically </p> <pre> -<<strong>View +<View android:background="@{isError ? @drawable/error : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> |