diff options
Diffstat (limited to 'docs/html/tools')
| -rw-r--r-- | docs/html/tools/data-binding/guide.jd | 732 |
1 files changed, 270 insertions, 462 deletions
diff --git a/docs/html/tools/data-binding/guide.jd b/docs/html/tools/data-binding/guide.jd index 2de5bc2..7c4c15a 100644 --- a/docs/html/tools/data-binding/guide.jd +++ b/docs/html/tools/data-binding/guide.jd @@ -28,10 +28,6 @@ page.tags="databinding", "layouts" <li> <a href="#binding_data">Binding Data</a> </li> - - <li> - <a href="#binding_events">Binding Events</a> - </li> </ol> </li> @@ -145,7 +141,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-beta4</strong> +<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta1</strong> or higher is required.</p> <h4>Beta release</h4> @@ -191,9 +187,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-beta4 -or higher</strong>, so update your build dependencies (in the top-level -<code>build.gradle</code> file) as needed.</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>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 @@ -205,18 +201,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 top-level <code>build.gradle</code> file, right below "android". + path of your <code>build.gradle</code> file, right below "android". </p> <pre> dependencies { - classpath <strong>"com.android.tools.build:gradle:1.3.0-beta4"</strong> - classpath <strong>"com.android.databinding:dataBinder:1.0-rc1"</strong> + classpath <strong>"com.android.tools.build:gradle:1.3.0-beta1" + </strong>classpath <strong>"com.android.databinding:dataBinder:</strong>1.0-rc0" } +} </pre> <p> - Then make sure jcenter is in the repositories list for your projects in the top-level - <code>build.gradle</code> file. + Then make sure jcenter is in the repositories list for your sub projects. </p> <pre> @@ -232,8 +228,8 @@ allprojects { </p> <pre> -apply plugin: 'com.android.application' -apply plugin: 'com.android.databinding' +apply plugin: ‘com.android.application' +apply plugin: '<strong>com.android.databinding</strong>' </pre> <p> The data binding plugin is going to add necessary <strong>provided</strong> @@ -256,23 +252,23 @@ apply plugin: 'com.android.databinding' </p> <pre> -<?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 +<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 android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"> - <TextView android:layout_width="wrap_content" + android:layout_height="match_parent"</strong>> + <<strong>TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"/> - <TextView android:layout_width="wrap_content" + android:text="@{user.firstName}"</strong>/> + <<strong>TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}"/> - </LinearLayout> -</layout> + android:text="@{user.lastName}"</strong>/> + </<strong>LinearLayout</strong>> +</<strong>layout</strong>> </pre> <p> The user <strong>variable</strong> within <strong>data</strong> describes a @@ -289,9 +285,9 @@ apply plugin: 'com.android.databinding' </p> <pre> -<TextView android:layout_width="wrap_content" +<<strong>TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"/> + android:text="@{user.firstName}"</strong>/> </pre> <h3 id="data_object"> Data Object @@ -302,12 +298,12 @@ apply plugin: 'com.android.databinding' </p> <pre> -public class User { - public final String firstName; - public final String lastName; - public User(String firstName, String lastName) { - this.firstName = firstName; - this.lastName = lastName; +<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; } } </pre> @@ -318,18 +314,18 @@ public class User { </p> <pre> -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 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 String getFirstName() { - return this.firstName; + <strong>public </strong>String getFirstName() { + <strong>return this</strong>.<strong>firstName</strong>; } - public String getLastName() { - return this.lastName; + <strong>public </strong>String getLastName() { + <strong>return this</strong>.<strong>lastName</strong>; } } </pre> @@ -338,8 +334,7 @@ public class User { 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. Alternatively, it - will also be resolved to <code>firstName()</code> if that method exists. + and the <code>getFirstName()</code> method in the latter class. </p> <h3 id="binding_data"> @@ -349,8 +344,8 @@ public class User { <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>main_activity.xml</code> so the generate class was - <code>MainActivityBinding</code>. This class holds all the bindings from the + 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 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: @@ -358,10 +353,10 @@ public class User { <pre> @Override -protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - MainActivityBinding binding = DataBindingUtil.setContentView(this, R.layout.main_activity); - User user = new User("Test", "User"); +<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>); binding.setUser(user); } </pre> @@ -379,55 +374,11 @@ 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> @@ -443,20 +394,20 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data> - <import type="android.view.View"/> -</data> +<<strong>data</strong>> + <<strong>import type="android.view.View"</strong>/> +</<strong>data</strong>> </pre> <p> Now, View may be used within your binding expression: </p> <pre> -<TextView +<<strong>TextView android:text="@{user.lastName}" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/> + android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"</strong>/> </pre> <p> When there are class name conflicts, one of the classes may be renamed to an @@ -464,9 +415,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<import type="android.view.View"/> -<import type="com.example.real.estate.View" - alias="Vista"/> +<<strong>import type="android.view.View"</strong>/> +<<strong>import type="com.example.real.estate.View" + alias="Vista"</strong>/> </pre> <p> Now, <strong><code>Vista</code></strong> may be used to reference the @@ -477,12 +428,12 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data> - <import type="com.example.User"/> - <import type="java.util.List"/> - <variable name="user" type="User"/> - <variable name="userList" type="List&lt;User>"/> -</data> +<<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>> </pre> <p class="caution"> <strong>Note</strong>: Android Studio does not yet handle imports so the @@ -492,10 +443,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<TextView +<<strong>TextView android:text="@{((User)(user.connection)).lastName}" android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <p> Imported types may also be used when referencing static fields and methods in @@ -503,15 +454,15 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data> - <import type="com.example.MyStringUtils"/> - <variable name="user" type="com.example.User"/> -</data> +<<strong>data</strong>> + <<strong>import type="com.example.MyStringUtils"</strong>/> + <<strong>variable name="user" type="com.example.User"</strong>/> +</<strong>data</strong>> … -<TextView +<<strong>TextView android:text="@{MyStringUtils.capitalize(user.lastName)}" android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <p> Just as in Java, <code>java.lang.*</code> is imported automatically. @@ -530,16 +481,16 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<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> +<<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>> </pre> <p> The variable types are inspected at compile time, so if a variable implements - {@link android.databinding.Observable} or is an <a href= + <a href="#observable_objects">Observable</a> 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 @@ -582,9 +533,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data class="ContactItem"> +<<strong>data class="ContactItem"</strong>> ... -</data> +</<strong>data</strong>> </pre> <p> This generates the binding class as <code>ContactItem</code> in the @@ -594,9 +545,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data class=".ContactItem"> +<<strong>data class=".ContactItem"</strong>> ... -</data> +</<strong>data</strong>> </pre> <p> In this case, <code>ContactItem</code> is generated in the module package @@ -604,9 +555,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<data class="com.example.ContactItem"> +<<strong>data class="com.example.ContactItem"</strong>> ... -</data> +</<strong>data</strong>> </pre> <h3 id="includes"> Includes @@ -619,46 +570,28 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </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> - <LinearLayout +<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 android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"> - <include layout="@layout/name" - bind:user="@{user}"/> - <include layout="@layout/contact" - bind:user="@{user}"/> - </LinearLayout> -</layout> + 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>> </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> @@ -680,10 +613,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </li> <li> - Logical <strong><code>&& ||</code></strong> + <code>L</code>ogical <strong><code>&& ||</code></strong> </li> - <li>Binary <strong><code>& | ^</code></strong> + <li>Binary <strong><code>&</code> <code>|</code> <code>^</code></strong> </li> <li>Unary <strong><code>+ - ! ~</code></strong> @@ -726,9 +659,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -android:text="@{String.valueOf(index + 1)}" +<strong>android:text="@{String.valueOf(index + 1)}" android:visibility="@{age &lt; 13 ? View.GONE : View.VISIBLE}" -android:transitionName='@{"image_" + id}' +android:transitionName='@{"image_" + id}'</strong> </pre> <h4 id="missing_operations"> Missing Operations @@ -813,23 +746,23 @@ android:transitionName='@{"image_" + id}' </p> <pre> -<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>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>> … -android:text="@{sparse[index]}" -… -android:text="@{map[key]}" - +<strong>android:text="@{list[index]}" +</strong>… +<strong>android:text="@{sparse[index]}" +</strong>… +<strong>android:text="@{map[key]}" +</strong> </pre> <h4 id="string_literals"> String Literals @@ -841,7 +774,7 @@ android:text="@{map[key]}" </p> <pre> -android:text='@{map["firstName"]}' +<strong>android:text='@{map["firstName"]}'</strong> </pre> <p> It is also possible to use double quotes to surround the attribute value. @@ -850,8 +783,8 @@ android:text='@{map["firstName"]}' </p> <pre> -android:text="@{map[`firstName`}" -android:text="@{map[&quot;firstName&quot;]}" +<strong>android:text="@{map[`firstName`}" +android:text="@{map[&quot;firstName&quot;]}"</strong> </pre> <h4 id="resources"> Resources @@ -863,15 +796,15 @@ android:text="@{map[&quot;firstName&quot;]}" </p> <pre> -android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}" +<strong>android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"</strong> </pre> <p> Format strings and plurals may be evaluated by providing parameters: </p> <pre> -android:text="@{@string/nameFormat(firstName, lastName)}" -android:text="@{@plurals/banana(bananaCount)}" +<strong>android:text="@{@string/nameFormat(firstName, lastName)}" +android:text="@{@plurals/banana(bananaCount)}"</strong> </pre> <p> When a plural takes multiple parameters, all parameters should be passed: @@ -882,7 +815,7 @@ android:text="@{@plurals/banana(bananaCount)}" Have an orange Have %d oranges -android:text="@{@plurals/orange(orangeCount, orangeCount)}" +android:text="<strong>@{@plurals/orange(orangeCount, orangeCount)}</strong>" </pre> <p> Some resources require explicit type evaluation. @@ -903,7 +836,9 @@ android:text="@{@plurals/orange(orangeCount, orangeCount)}" <tr> <td> - String[] + <pre> +String[] +</pre> </td> <td> @array @@ -966,7 +901,9 @@ android:text="@{@plurals/orange(orangeCount, orangeCount)}" color <code>int</code> </td> <td> - @color + <pre> +@color +</pre> </td> <td> @color @@ -995,9 +932,8 @@ android:text="@{@plurals/orange(orangeCount, orangeCount)}" 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, - <a href="#observable_objects">Observable objects</a>, - <a href="#observablefields">observable fields</a>, and - <a href="#observable_collections">observable collection</a>s. + <code>Observable</code> objects, <code>ObservableField</code>s, and + <code>observable collections</code>. </p> <p> @@ -1010,49 +946,49 @@ android:text="@{@plurals/orange(orangeCount, orangeCount)}" </h3> <p> - A class implementing the {@link android.databinding.Observable} interface + A class implementing <code>android.databinding.Observable</code> 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 {@link android.databinding.Observable} interface has a mechanism to add and remove + The <code>Observable</code> interface has a mechanism to add and remove listeners, but notifying is up to the developer. To make development easier, - a base class, {@link android.databinding.BaseObservable}, was created to implement the + a base class, <code>BaseObservable,</code> 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 {@link android.databinding.Bindable} annotation to the getter and notifying in + assigning a <code>Bindable</code> annotation to the getter and notifying in the setter. </p> <pre> -private static class User extends BaseObservable { - private String firstName; - private String lastName; +<strong>private static class </strong>User <strong>extends </strong>BaseObservable { + <strong>private </strong>String <strong>firstName</strong>; + <strong>private </strong>String <strong>lastName</strong>; @Bindable - public String getFirstName() { - return this.firstName; + <strong>public </strong>String getFirstName() { + <strong>return this</strong>.<strong>firstName</strong>; } @Bindable - public String getLastName() { - return this.lastName; + <strong>public </strong>String getFirstName() { + <strong>return this</strong>.<strong>lastName</strong>; } - public void setFirstName(String firstName) { - this.firstName = firstName; + <strong>public void </strong>setFirstName(String firstName) { + <strong>this</strong>.<strong>firstName </strong>= firstName; notifyPropertyChanged(BR.firstName); } - public void setLastName(String lastName) { - this.lastName = lastName; + <strong>public void </strong>setLastName(String lastName) { + <strong>this</strong>.<strong>lastName </strong>= lastName; notifyPropertyChanged(BR.lastName); } } </pre> <p> - The {@link android.databinding.Bindable} annotation generates an entry in the BR class file + The <code>Bindable</code> 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 - {@link android.databinding.Observable} interface may be implemented using the convenient - {@link android.databinding.PropertyChangeRegistry} to store and notify listeners + 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 efficiently. </p> @@ -1061,30 +997,20 @@ private static class User extends BaseObservable { </h3> <p> - 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: + 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: </p> <pre> -private static class User { - public final ObservableField<String> firstName = - new ObservableField<>(); - public final ObservableField<String> lastName = - new ObservableField<>(); - public final ObservableInt age = new ObservableInt(); +<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(); } </pre> <p> @@ -1092,8 +1018,8 @@ private static class User { </p> <pre> -user.firstName.set("Google"); -int age = user.age.get(); +user.<strong>firstName</strong>.set(<strong>"Google"</strong>); +<strong>int </strong>age = user.<strong>age</strong>.get(); </pre> <h3 id="observable_collections"> Observable Collections @@ -1101,44 +1027,43 @@ int age = user.age.get(); <p> Some applications use more dynamic structures to hold data. Observable - collections allow keyed access to these data objects. - {@link android.databinding.ObservableArrayMap} is + collections allow keyed access to these data objects.ObservableArrayMap is useful when the key is a reference type, such as String. </p> <pre> -ObservableArrayMap<String, Object> user = new ObservableArrayMap<>(); -user.put("firstName", "Google"); -user.put("lastName", "Inc."); -user.put("age", 17); +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); </pre> <p> In the layout, the map may be accessed through the String keys: </p> <pre> -<data> - <import type="android.databinding.ObservableMap"/> - <variable name="user" type="ObservableMap&lt;String, Object>"/> -</data> +<<strong>data</strong>> + <<strong>import type="android.databinding.ObservableMap"</strong>/> + <<strong>variable name="user" type="ObservableMap&lt;String, Object>"</strong>/> +</<strong>data</strong>> … -<TextView +<<strong>TextView android:text='@{user["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"/> -<TextView + android:layout_height="wrap_content"</strong>/> +<<strong>TextView android:text='@{String.valueOf(1 + (Integer)user["age"])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <p> - {@link android.databinding.ObservableArrayList} is useful when the key is an integer: + ObservableArrayList is useful when the key is an integer: </p> <pre> -ObservableArrayList<Object> user = new ObservableArrayList<>(); -user.add("Google"); -user.add("Inc."); +ObservableArrayList<Object> user = <strong>new </strong>ObservableArrayList<>(); +user.add(<strong>"Google"</strong>); +user.add(<strong>"Inc."</strong>); user.add(17); </pre> <p> @@ -1146,20 +1071,20 @@ user.add(17); </p> <pre> -<data> - <import type="android.databinding.ObservableList"/> - <import type="com.example.my.app.Fields"/> - <variable name="user" type="ObservableList&lt;Object>"/> -</data> +<<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>> … -<TextView +<<strong>TextView android:text='@{user[Fields.LAST_NAME]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"/> -<TextView + android:layout_height="wrap_content"</strong>/> +<<strong>TextView android:text='@{String.valueOf(1 + (Integer)user[Fields.AGE])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <h2 id="generated_binding"> Generated Binding @@ -1169,7 +1094,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 {@link android.databinding.ViewDataBinding}. + classes all extend <code>android.databinding.ViewDataBinding</code>. </p> <h3 id="creating"> @@ -1182,13 +1107,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 {@link android.view.LayoutInflater} and one that takes a - {@link android.view.ViewGroup} as well: + version that only takes a <code>LayoutInflater</code> and one that takes a + <code>ViewGroup</code> as well: </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater); -MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater, viewGroup, false); +MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(<strong>layoutInflater</strong>); +MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(LayoutInflater, viewGroup, false); </pre> <p> If the layout was inflated using a different mechanism, it may be bound @@ -1196,17 +1121,17 @@ MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater, viewGroup, fal </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.bind(viewRoot); +MyLayoutBinding binding = MyLayoutBinding.<em>bind</em>(viewRoot); </pre> <p> Sometimes the binding cannot be known in advance. In such cases, the binding - can be created using the {@link android.databinding.DataBindingUtil} class: + can be created using the DataBindingUtil class: </p> <pre> -ViewDataBinding binding = DataBindingUtil.inflate(LayoutInflater, layoutId, +ViewDataBinding binding = DataBindingUtil.<em>inflate</em>(LayoutInflater, layoutId, parent, attachToParent); -ViewDataBinding binding = DataBindingUtil.bindTo(viewRoot, layoutId); +ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); </pre> <h3 id="views_with_ids"> Views With IDs @@ -1220,32 +1145,32 @@ ViewDataBinding binding = DataBindingUtil.bindTo(viewRoot, layoutId); </p> <pre> -<layout xmlns:android="http://schemas.android.com/apk/res/android"> - <data> - <variable name="user" type="com.example.User"/> - </data> - <LinearLayout +<<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 android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"> - <TextView android:layout_width="wrap_content" + android:layout_height="match_parent"</strong>> + <<strong>TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}" - android:id="@+id/firstName"/> - <TextView android:layout_width="wrap_content" + android:text="@{user.firstName}"</strong> + <strong>android:id="@+id/firstName"</strong>/> + <<strong>TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}" - android:id="@+id/lastName"/> - </LinearLayout> -</layout> + android:text="@{user.lastName}"</strong> + <strong>android:id="@+id/lastName"</strong>/> + </<strong>LinearLayout</strong>> +</<strong>layout</strong>> </pre> <p> Will generate a binding class with: </p> <pre> -public final TextView firstName; -public final TextView lastName; +<strong>public final </strong>TextView <strong>firstName</strong>; +<strong>public final </strong>TextView <strong>lastName</strong>; </pre> <p> IDs are not nearly as necessary as without data binding, but there are still @@ -1261,49 +1186,49 @@ public final TextView lastName; </p> <pre> -<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> +<<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>> </pre> <p> will generate setters and getters in the binding: </p> <pre> -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); +<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); </pre> <h3 id="viewstubs"> ViewStubs </h3> <p> - {@link android.view.ViewStub}s are a little different from normal Views. They start off invisible + ViewStubs 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 <code>ViewStub</code> essentially disappears from the View hierarchy, the View + Because the ViewStub essentially disappears from the View hierarchy, the View in the binding object must also disappear to allow collection. Because the - 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. + 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. </p> <p> When inflating another layout, a binding must be established for the new - 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. + 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. </p> <h3 id="advanced_binding"> @@ -1316,20 +1241,20 @@ public abstract void setNote(String note); <p> At times, the specific binding class won't be known. For example, a - {@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}. + RecyclerView Adapter operating against arbitrary layouts won't know the + specific binding class. It still must assign the binding value during the + onBindViewHolder. </p> <p> In this example, all layouts that the RecyclerView binds to have an "item" - variable. The <code>BindingHolder</code> has a <code>getBinding</code> method returning the - {@link android.databinding.ViewDataBinding} base. + variable. The BindingHolder has a getBinding method returning the + <code>ViewDataBinding</code> base. </p> <pre> -public void onBindViewHolder(BindingHolder holder, int position) { - final T item = mItems.get(position); +<strong>public void </strong>onBindViewHolder(BindingHolder holder, <strong>int </strong>position) { + <strong>final </strong>T item = <strong>mItems</strong>.get(position); holder.getBinding().setVariable(BR.item, item); holder.getBinding().executePendingBindings(); } @@ -1342,7 +1267,7 @@ public void onBindViewHolder(BindingHolder holder, int position) { 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 - {@link android.databinding.ViewDataBinding#executePendingBindings()} method. + <code>executePendingBindings()</code> method. </p> <h4> @@ -1396,18 +1321,17 @@ 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 - {@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>. + 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. </p> <pre> @BindingMethods({ - @BindingMethod(type = "android.widget.ImageView", - attribute = "android:tint", - method = "setImageTintList"), + @BindingMethod(type = <strong>"android.widget.ImageView"</strong>, + attribute = <strong>"android:tint"</strong>, + method = <strong>"setImageTintList"</strong>), }) </pre> <p> @@ -1423,7 +1347,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 {@link android.databinding.BindingAdapter} + A static binding adapter method with the <code>BindingAdapter</code> annotation allows the developer to customize how a setter for an attribute is called. </p> @@ -1434,8 +1358,9 @@ namespace for the attribute does not matter, only the attribute name itself. </p> <pre> -@BindingAdapter("android:paddingLeft") -public static void setPaddingLeft(View view, int padding) { + +@BindingAdapter(<strong>"android:paddingLeft"</strong>) +<strong>public static void </strong>setPaddingLeft(View view, <strong>int </strong>padding) { view.setPadding(padding, view.getPaddingTop(), view.getPaddingRight(), @@ -1457,9 +1382,9 @@ public static void setPaddingLeft(View view, int padding) { </p> <pre> -@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); +@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); } </pre> <pre> @@ -1481,123 +1406,6 @@ 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> @@ -1618,10 +1426,10 @@ public static void setListener(View view, final OnViewDetachedFromWindow detach, </p> <pre> -<TextView +<<strong>TextView android:text='@{userMap["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <p> @@ -1639,10 +1447,10 @@ The <code>userMap</code> returns an Object and that Object will be automatically </p> <pre> -<View +<<strong>View android:background="@{isError ? @color/red : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> <p> Here, the background takes a <code>Drawable</code>, but the color is an @@ -1654,8 +1462,8 @@ The <code>userMap</code> returns an Object and that Object will be automatically <pre> @BindingConversion -public static ColorDrawable convertColorToDrawable(int color) { - return new ColorDrawable(color); +<strong>public static </strong>ColorDrawable convertColorToDrawable(<strong>int </strong>color) { + <strong>return new </strong>ColorDrawable(color); } </pre> <p> @@ -1664,8 +1472,8 @@ public static ColorDrawable convertColorToDrawable(int color) { </p> <pre> -<View +<<strong>View android:background="@{isError ? @drawable/error : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"/> + android:layout_height="wrap_content"</strong>/> </pre> |