Fix up javadoc. Bug 22175560 Change-Id: Ib5bfd87f66602919764bd9b28c0afdcbe55a7ce5
diff --git a/baseLibrary/src/main/java/android/databinding/Bindable.java b/baseLibrary/src/main/java/android/databinding/Bindable.java index 3dcebdd..45436d6 100644 --- a/baseLibrary/src/main/java/android/databinding/Bindable.java +++ b/baseLibrary/src/main/java/android/databinding/Bindable.java
@@ -15,11 +15,20 @@ */ package android.databinding; +import android.databinding.Observable.OnPropertyChangedCallback; + import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * The Bindable annotation should be applied to any getter accessor method of an + * {@link Observable} class. Bindable will generate a field in the BR class to identify + * the field that has changed. + * + * @see OnPropertyChangedCallback#onPropertyChanged(Observable, int) + */ @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) // this is necessary for java analyzer to work public @interface Bindable {
diff --git a/baseLibrary/src/main/java/android/databinding/BindingAdapter.java b/baseLibrary/src/main/java/android/databinding/BindingAdapter.java index 8e88377..09bc482 100644 --- a/baseLibrary/src/main/java/android/databinding/BindingAdapter.java +++ b/baseLibrary/src/main/java/android/databinding/BindingAdapter.java
@@ -18,7 +18,58 @@ import java.lang.annotation.ElementType; import java.lang.annotation.Target; +/** + * BindingAdapter is applied to methods that are used to manipulate how values with expressions + * are set to views. The simplest example is to have a public static method that takes the view + * and the value to set: + * <p><pre> + *<code>@BindingAdapter("android:bufferType") + * public static void setBufferType(TextView view, TextView.BufferType bufferType) { + * view.setText(view.getText(), bufferType); + * }</code></pre> + * In the above example, when android:bufferType is used on a TextView, the method + * setBufferType is called. + * <p> + * It is also possible to take previously set values, if the old values are listed first: + * <p><pre> + *<code>@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); + * } + * } + * }</code></pre> + * When a binding adapter may also take multiple attributes, it will only be called when all + * attributes associated with the binding adapter have binding expressions associated with them. + * This is useful when there are unusual interactions between attributes. For example: + * <p><pre> + *<code>@BindingAdapter({"android:onClick", "android:clickable"}) + * public static void setOnClick(View view, View.OnClickListener clickListener, + * boolean clickable) { + * view.setOnClickListener(clickListener); + * view.setClickable(clickable); + * }</code></pre> + * The order of the parameters must match the order of the attributes in values in the + * BindingAdapter. + * <p> + * A binding adapter may optionally take a class extending DataBindingComponent as the first + * parameter as well. If it does, it will be passed the value passed in during binding, either + * directly in the inflate method or indirectly, using the value from + * {@link DataBindingUtil#getDefaultComponent()}. + * <p> + * If a binding adapter is an instance method, the generated DataBindingComponent will have + * a getter to retrieve an instance of the BindingAdapter's class to use to call the method. + */ @Target(ElementType.METHOD) public @interface BindingAdapter { + + /** + * @return The attributes associated with this binding adapter. + */ String[] value(); }
diff --git a/baseLibrary/src/main/java/android/databinding/BindingBuildInfo.java b/baseLibrary/src/main/java/android/databinding/BindingBuildInfo.java index 5b0c0b4..a67c97b 100644 --- a/baseLibrary/src/main/java/android/databinding/BindingBuildInfo.java +++ b/baseLibrary/src/main/java/android/databinding/BindingBuildInfo.java
@@ -20,6 +20,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * @hide + */ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.SOURCE) public @interface BindingBuildInfo {
diff --git a/baseLibrary/src/main/java/android/databinding/BindingConversion.java b/baseLibrary/src/main/java/android/databinding/BindingConversion.java index 9942f5c..053ab39 100644 --- a/baseLibrary/src/main/java/android/databinding/BindingConversion.java +++ b/baseLibrary/src/main/java/android/databinding/BindingConversion.java
@@ -19,6 +19,12 @@ import java.lang.annotation.ElementType; import java.lang.annotation.Target; +/** + * Annotate methods that are used to automatically convert from the expression type to the value + * used in the setter. The converter should take one parameter, the expression type, and the + * return value should be the target value type used in the setter. Converters are used + * whenever they can be applied and are not specific to any attribute. + */ @Target({ElementType.METHOD}) public @interface BindingConversion { }
diff --git a/baseLibrary/src/main/java/android/databinding/BindingMethod.java b/baseLibrary/src/main/java/android/databinding/BindingMethod.java index c10d4af..3585c0c 100644 --- a/baseLibrary/src/main/java/android/databinding/BindingMethod.java +++ b/baseLibrary/src/main/java/android/databinding/BindingMethod.java
@@ -15,8 +15,26 @@ */ package android.databinding; +/** + * Used within an {@link BindingMethods} annotation to describe a renaming of an attribute to + * the setter used to set that attribute. By default, an attribute attr will be associated with + * setter setAttr. + */ public @interface BindingMethod { + + /** + * @return the View Class that the attribute is associated with. + */ Class type(); + + /** + * @return The attribute to rename. Use android: namespace for all android attributes or + * no namespace for application attributes. + */ String attribute(); + + /** + * @return The method to call to set the attribute value. + */ String method(); }
diff --git a/baseLibrary/src/main/java/android/databinding/BindingMethods.java b/baseLibrary/src/main/java/android/databinding/BindingMethods.java index a3d39f8..552b1ba 100644 --- a/baseLibrary/src/main/java/android/databinding/BindingMethods.java +++ b/baseLibrary/src/main/java/android/databinding/BindingMethods.java
@@ -18,6 +18,11 @@ import java.lang.annotation.ElementType; import java.lang.annotation.Target; +/** + * Used to enumerate attribute-to-setter renaming. By default, an attribute is associated with + * setAttribute setter. If there is a simple rename, enumerate them in an array of + * {@link BindingMethod} annotations in the value. + */ @Target({ElementType.TYPE}) public @interface BindingMethods { BindingMethod[] value();
diff --git a/baseLibrary/src/main/java/android/databinding/CallbackRegistry.java b/baseLibrary/src/main/java/android/databinding/CallbackRegistry.java index 002692f..0cd7b43 100644 --- a/baseLibrary/src/main/java/android/databinding/CallbackRegistry.java +++ b/baseLibrary/src/main/java/android/databinding/CallbackRegistry.java
@@ -19,7 +19,7 @@ import java.util.List; /** - * Tracks callbacks for the event. This class supports reentrant modification + * A utility for storing and notifying callbacks. This class supports reentrant modification * of the callbacks during notification without adversely disrupting notifications. * A common pattern for callbacks is to receive a notification and then remove * themselves. This class handles this behavior with constant memory under @@ -27,11 +27,13 @@ * * <p>A subclass of {@link CallbackRegistry.NotifierCallback} must be passed to * the constructor to define how notifications should be called. That implementation - * does the actual notification on the listener.</p> + * does the actual notification on the listener. It is typically a static instance + * that can be reused for all similar CallbackRegistries.</p> * - * <p>This class supports only callbacks with at most two parameters. - * Typically, these are the notification originator and a parameter, but these may - * be used as required. If more than two parameters are required or primitive types + * <p>This class supports only callbacks with at most three parameters. + * Typically, these are the notification originator and a parameter, with another to + * indicate which method to call, but these may be used as required. If more than + * three parameters are required or primitive types other than the single int provided * must be used, <code>A</code> should be some kind of containing structure that * the subclass may reuse between notifications.</p> * @@ -78,11 +80,11 @@ * Notify all callbacks. * * @param sender The originator. This is an opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg2 An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} */ public synchronized void notifyCallbacks(T sender, int arg, A arg2) { mNotificationLevel++; @@ -109,11 +111,11 @@ * Notify up to the first Long.SIZE callbacks that don't have a bit set in <code>removed</code>. * * @param sender The originator. This is an opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg2 An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} */ private void notifyFirst64(T sender, int arg, A arg2) { final int maxNotified = Math.min(Long.SIZE, mCallbacks.size()); @@ -128,11 +130,11 @@ * <p>Recursion is used to avoid allocating temporary state on the heap.</p> * * @param sender The originator. This is an opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg2 An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} */ private void notifyRecurse(T sender, int arg, A arg2) { final int callbackCount = mCallbacks.size(); @@ -155,11 +157,11 @@ * remainderIndex is -1, the first 64 will be notified instead. * * @param sender The originator. This is an opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg2 An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param remainderIndex The index into mRemainderRemoved that should be notified. */ private void notifyRemainder(T sender, int arg, A arg2, int remainderIndex) { @@ -181,11 +183,11 @@ * endIndex should be notified. * * @param sender The originator. This is an opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param arg2 An opaque parameter passed to - * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, A)} + * {@link CallbackRegistry.NotifierCallback#onNotifyCallback(Object, Object, int, Object)} * @param startIndex The index into the mCallbacks to start notifying. * @param endIndex One past the last index into mCallbacks to notify. * @param bits A bit field indicating which callbacks have been removed and shouldn't @@ -245,6 +247,7 @@ /** * Removes callbacks from startIndex to startIndex + Long.SIZE, based * on the bits set in removed. + * * @param startIndex The index into the mCallbacks to start removing callbacks. * @param removed The bits indicating removal, where each bit is set for one callback * to be removed. @@ -264,6 +267,7 @@ /** * Remove a callback. This callback won't be notified after this call completes. + * * @param callback The callback to remove. */ public synchronized void remove(C callback) { @@ -297,29 +301,12 @@ } } - /* - private void clearRemovalBit(int index) { - if (index < Long.SIZE) { - // It is in the first 64 callbacks, just check the bit. - final long bitMask = 1L << index; - mFirst64Removed &= ~bitMask; - } else if (mRemainderRemoved != null) { - final int maskIndex = (index / Long.SIZE) - 1; - if (maskIndex < mRemainderRemoved.length) { - // There is something marked for removal, so we have to check the bit. - final long bitMask = 1L << (index % Long.SIZE); - mRemainderRemoved[maskIndex] &= ~bitMask; - } - } - } - */ - /** * Makes a copy of the registered callbacks and returns it. * * @return a copy of the registered callbacks. */ - public synchronized ArrayList<C> copyListeners() { + public synchronized ArrayList<C> copyCallbacks() { ArrayList<C> callbacks = new ArrayList<C>(mCallbacks.size()); int numListeners = mCallbacks.size(); for (int i = 0; i < numListeners; i++) { @@ -331,6 +318,21 @@ } /** + * Modifies <code>callbacks</code> to contain all callbacks in the CallbackRegistry. + * + * @param callbacks modified to contain all callbacks registered to receive events. + */ + public synchronized void copyCallbacks(List<C> callbacks) { + callbacks.clear(); + int numListeners = mCallbacks.size(); + for (int i = 0; i < numListeners; i++) { + if (!isRemoved(i)) { + callbacks.add(mCallbacks.get(i)); + } + } + } + + /** * Returns true if there are no registered callbacks or false otherwise. * * @return true if there are no registered callbacks or false otherwise. @@ -364,6 +366,10 @@ } } + /** + * @return A copy of the CallbackRegistry with all callbacks listening to both instances. + */ + @SuppressWarnings("unchecked") public synchronized CallbackRegistry<C, T, A> clone() { CallbackRegistry<C, T, A> clone = null; try { @@ -393,7 +399,8 @@ */ public abstract static class NotifierCallback<C, T, A> { /** - * Used to notify the callback. + * Called by CallbackRegistry during + * {@link CallbackRegistry#notifyCallbacks(Object, int, Object)}} to notify the callback. * * @param callback The callback to notify. * @param sender The opaque sender object.
diff --git a/baseLibrary/src/main/java/android/databinding/Untaggable.java b/baseLibrary/src/main/java/android/databinding/Untaggable.java index a1ce3ac..c6b1c3d 100644 --- a/baseLibrary/src/main/java/android/databinding/Untaggable.java +++ b/baseLibrary/src/main/java/android/databinding/Untaggable.java
@@ -18,6 +18,9 @@ import java.lang.annotation.ElementType; import java.lang.annotation.Target; +/** + * @hide + */ @Target({ElementType.TYPE}) public @interface Untaggable { String[] value();
diff --git a/compiler/src/test/java/android/databinding/CallbackRegistryTest.java b/compiler/src/test/java/android/databinding/CallbackRegistryTest.java index fd1562d..f4cb59d 100644 --- a/compiler/src/test/java/android/databinding/CallbackRegistryTest.java +++ b/compiler/src/test/java/android/databinding/CallbackRegistryTest.java
@@ -59,29 +59,29 @@ registry = new CallbackRegistry<Integer, CallbackRegistryTest, Integer>(notifier); Integer callback = 0; - assertNotNull(registry.copyListeners()); - assertEquals(0, registry.copyListeners().size()); + assertNotNull(registry.copyCallbacks()); + assertEquals(0, registry.copyCallbacks().size()); registry.add(callback); - ArrayList<Integer> callbacks = registry.copyListeners(); + ArrayList<Integer> callbacks = registry.copyCallbacks(); assertEquals(1, callbacks.size()); assertEquals(callback, callbacks.get(0)); registry.add(callback); - callbacks = registry.copyListeners(); + callbacks = registry.copyCallbacks(); assertEquals(1, callbacks.size()); assertEquals(callback, callbacks.get(0)); Integer otherListener = 1; registry.add(otherListener); - callbacks = registry.copyListeners(); + callbacks = registry.copyCallbacks(); assertEquals(2, callbacks.size()); assertEquals(callback, callbacks.get(0)); assertEquals(otherListener, callbacks.get(1)); registry.remove(callback); registry.add(callback); - callbacks = registry.copyListeners(); + callbacks = registry.copyCallbacks(); assertEquals(2, callbacks.size()); assertEquals(callback, callbacks.get(1)); assertEquals(otherListener, callbacks.get(0)); @@ -130,7 +130,7 @@ assertEquals(1, notify2); assertEquals(1, notify3); - ArrayList<Integer> callbacks = registry.copyListeners(); + ArrayList<Integer> callbacks = registry.copyCallbacks(); assertEquals(1, callbacks.size()); assertEquals(callback3, callbacks.get(0)); } @@ -156,7 +156,7 @@ assertEquals(2, notify2); assertEquals(3, notify3); - ArrayList<Integer> callbacks = registry.copyListeners(); + ArrayList<Integer> callbacks = registry.copyCallbacks(); assertEquals(0, callbacks.size()); } @@ -183,7 +183,7 @@ registry.add(callback3); registry.notifyCallbacks(this, 0, null); - ArrayList<Integer> callbacks = registry.copyListeners(); + ArrayList<Integer> callbacks = registry.copyCallbacks(); assertEquals(3, callbacks.size()); assertEquals(callback1, callbacks.get(0)); assertEquals(callback3, callbacks.get(1)); @@ -220,7 +220,7 @@ assertEquals(expectedCount, deepNotifyCount[i]); } - ArrayList<Integer> callbackList = registry.copyListeners(); + ArrayList<Integer> callbackList = registry.copyCallbacks(); assertEquals(0, callbackList.size()); } @@ -240,7 +240,7 @@ } registry.clear(); - ArrayList<Integer> callbackList = registry.copyListeners(); + ArrayList<Integer> callbackList = registry.copyCallbacks(); assertEquals(0, callbackList.size()); registry.notifyCallbacks(this, 0, null); @@ -269,7 +269,7 @@ assertEquals(1, deepNotifyCount[i]); } - ArrayList<Integer> callbackList = registry.copyListeners(); + ArrayList<Integer> callbackList = registry.copyCallbacks(); assertEquals(0, callbackList.size()); }
diff --git a/extensions/baseAdapters/src/main/java/android/databinding/adapters/ListenerUtil.java b/extensions/baseAdapters/src/main/java/android/databinding/adapters/ListenerUtil.java index d8c3125..9643be2 100644 --- a/extensions/baseAdapters/src/main/java/android/databinding/adapters/ListenerUtil.java +++ b/extensions/baseAdapters/src/main/java/android/databinding/adapters/ListenerUtil.java
@@ -34,9 +34,7 @@ * so will not keep a strong reference to either. * * Example usage: - * <pre> - * {@code - * @BindingAdapter("onFoo") + *<pre><code>@BindingAdapter("onFoo") * public static void addFooListener(MyView view, OnFooListener listener) { * OnFooListener oldValue = ListenerUtil.trackListener(view, listener, R.id.fooListener); * if (oldValue != null) { @@ -45,9 +43,7 @@ * if (listener != null) { * view.addOnFooListener(listener); * } - * } - * } - * </pre> + * }</code></pre> * * @param view The View that will have this listener * @param listener The listener to keep track of. May be null if the listener is being removed.
diff --git a/library/src/doc/java/com/android/databinding/library/R.java b/library/src/doc/java/com/android/databinding/library/R.java new file mode 100644 index 0000000..668a20c --- /dev/null +++ b/library/src/doc/java/com/android/databinding/library/R.java
@@ -0,0 +1,30 @@ +/* + * Copyright (C) 2015 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.android.databinding.library; + +/** + * This is only here to allow building the javadoc without building the rest of + * data binding. + * + * This should be removed when data binding is included in the framework build. + * + * @hide + */ +public class R { + public static class id { + public static int dataBinding = 0; + } +} \ No newline at end of file
diff --git a/library/src/main/java/android/databinding/BaseObservable.java b/library/src/main/java/android/databinding/BaseObservable.java index 6c19c4d..f3be2c6 100644 --- a/library/src/main/java/android/databinding/BaseObservable.java +++ b/library/src/main/java/android/databinding/BaseObservable.java
@@ -18,7 +18,7 @@ /** * A convenience class that implements {@link android.databinding.Observable} interface and provides - * {@link #notifyPropertyChanged(int)} and @{link #notifyChange} methods. + * {@link #notifyPropertyChanged(int)} and {@link #notifyChange} methods. */ public class BaseObservable implements Observable { private transient PropertyChangeRegistry mCallbacks; @@ -27,26 +27,36 @@ } @Override - public synchronized void addOnPropertyChangedCallback(OnPropertyChangedCallback listener) { + public synchronized void addOnPropertyChangedCallback(OnPropertyChangedCallback callback) { if (mCallbacks == null) { mCallbacks = new PropertyChangeRegistry(); } - mCallbacks.add(listener); + mCallbacks.add(callback); } @Override - public synchronized void removeOnPropertyChangedCallback(OnPropertyChangedCallback listener) { + public synchronized void removeOnPropertyChangedCallback(OnPropertyChangedCallback callback) { if (mCallbacks != null) { - mCallbacks.remove(listener); + mCallbacks.remove(callback); } } + /** + * Notifies listeners that all properties of this instance have changed. + */ public synchronized void notifyChange() { if (mCallbacks != null) { mCallbacks.notifyCallbacks(this, 0, null); } } + /** + * Notifies listeners that a specific property has changed. The getter for the property + * that changes should be marked with {@link Bindable} to generate a field in + * <code>BR</code> to be used as <code>fieldId</code>. + * + * @param fieldId The generated BR id for the Bindable field. + */ public void notifyPropertyChanged(int fieldId) { if (mCallbacks != null) { mCallbacks.notifyCallbacks(this, fieldId, null);
diff --git a/library/src/main/java/android/databinding/DataBinderMapper.java b/library/src/main/java/android/databinding/DataBinderMapper.java index 044880f..683615a 100644 --- a/library/src/main/java/android/databinding/DataBinderMapper.java +++ b/library/src/main/java/android/databinding/DataBinderMapper.java
@@ -22,6 +22,7 @@ * This class will be stripped from the jar and then replaced by the annotation processor * as part of the code generation step. This class's existence is just to ensure that * compile works and no reflection is needed to access the generated class. + * @hide */ class DataBinderMapper { public ViewDataBinding getDataBinder(DataBindingComponent bindingComponent, View view,
diff --git a/library/src/main/java/android/databinding/DataBindingComponent.java b/library/src/main/java/android/databinding/DataBindingComponent.java index d609118..a8fb2fe 100644 --- a/library/src/main/java/android/databinding/DataBindingComponent.java +++ b/library/src/main/java/android/databinding/DataBindingComponent.java
@@ -15,6 +15,10 @@ */ package android.databinding; +import android.view.LayoutInflater; +import android.view.View; +import android.view.ViewGroup; + /** * This interface is generated during compilation to contain getters for all used instance * BindingAdapters. When a BindingAdapter is an instance method, an instance of the class @@ -25,8 +29,12 @@ * An instance of this class may also be passed into static or instance BindingAdapters as the * first parameter. * <p> - * If you are using Dagger 2, you should extend this interface and annotate the extended interface + * If using Dagger 2, the developer should extend this interface and annotate the extended interface * as a Component. + * + * @see DataBindingUtil#setDefaultComponent(DataBindingComponent) + * @see DataBindingUtil#inflate(LayoutInflater, int, ViewGroup, boolean, DataBindingComponent) + * @see DataBindingUtil#bind(View, DataBindingComponent) */ public interface DataBindingComponent { }
diff --git a/library/src/main/java/android/databinding/DataBindingUtil.java b/library/src/main/java/android/databinding/DataBindingUtil.java index 9860a4a..c2e616f 100644 --- a/library/src/main/java/android/databinding/DataBindingUtil.java +++ b/library/src/main/java/android/databinding/DataBindingUtil.java
@@ -32,17 +32,30 @@ private static DataBindingComponent sDefaultComponent = null; /** - * Set the default {@link DataBindingComponent} to use for data binding. When instance - * method BindingAdapters are used, the class instance for the binding adapter is retrieved - * from the DataBindingComponent. + * Prevent DataBindingUtil from being instantiated. + */ + private DataBindingUtil() {} + + /** + * Set the default {@link DataBindingComponent} to use for data binding. + * <p> + * <code>bindingComponent</code> may be passed as the first parameter of binding adapters. + * <p> + * When instance method BindingAdapters are used, the class instance for the binding adapter + * is retrieved from the DataBindingComponent. */ public static void setDefaultComponent(DataBindingComponent bindingComponent) { sDefaultComponent = bindingComponent; } /** - * @return the default {@link DataBindingComponent} used in data binding. Can be <code>null</code> - * if no default was set in {@link #setDefaultComponent(DataBindingComponent)}. + * Returns the default {@link DataBindingComponent} used in data binding. This can be + * <code>null</code> if no default was set in + * {@link #setDefaultComponent(DataBindingComponent)}. + * + * @return the default {@link DataBindingComponent} used in data binding. This can be + * <code>null</code> if no default was set in + * {@link #setDefaultComponent(DataBindingComponent)}. */ public static DataBindingComponent getDefaultComponent() { return sDefaultComponent; @@ -52,6 +65,9 @@ * Inflates a binding layout and returns the newly-created binding for that layout. * This uses the DataBindingComponent set in * {@link #setDefaultComponent(DataBindingComponent)}. + * <p> + * Use this version only if <code>layoutId</code> is unknown in advance. Otherwise, use + * the generated Binding's inflate method to ensure type-safe inflation. * * @param inflater The LayoutInflater used to inflate the binding layout. * @param layoutId The layout resource ID of the layout to inflate. @@ -74,6 +90,9 @@ /** * Inflates a binding layout and returns the newly-created binding for that layout. + * <p> + * Use this version only if <code>layoutId</code> is unknown in advance. Otherwise, use + * the generated Binding's inflate method to ensure type-safe inflation. * * @param inflater The LayoutInflater used to inflate the binding layout. * @param layoutId The layout resource ID of the layout to inflate. @@ -117,6 +136,9 @@ * Returns the binding for the given layout root or creates a binding if one * does not exist. This uses the DataBindingComponent set in * {@link #setDefaultComponent(DataBindingComponent)}. + * <p> + * Prefer using the generated Binding's <code>bind</code> method to ensure type-safe inflation + * when it is known that <code>root</code> has not yet been bound. * * @param root The root View of the inflated binding layout. * @return A ViewDataBinding for the given root View. If one already exists, the @@ -132,6 +154,9 @@ /** * Returns the binding for the given layout root or creates a binding if one * does not exist. + * <p> + * Prefer using the generated Binding's <code>bind</code> method to ensure type-safe inflation + * when it is known that <code>root</code> has not yet been bound. * * @param root The root View of the inflated binding layout. * @param bindingComponent The DataBindingComponent to use in data binding. @@ -177,7 +202,7 @@ * <code>null</code> will be returned. * <p> * This differs from {@link #getBinding(View)} in that findBinding takes any view in the - * layout and searches for the binding associated with the root <code>getBinding</code> + * layout and searches for the binding associated with the root. <code>getBinding</code> * takes only the root view. * * @param view A <code>View</code> in the bound layout.
diff --git a/library/src/main/java/android/databinding/ListChangeRegistry.java b/library/src/main/java/android/databinding/ListChangeRegistry.java index 4ea2c6f..e13f867 100644 --- a/library/src/main/java/android/databinding/ListChangeRegistry.java +++ b/library/src/main/java/android/databinding/ListChangeRegistry.java
@@ -17,6 +17,9 @@ import android.support.v4.util.Pools; +/** + * Utility class for managing ObservableList callbacks. + */ public class ListChangeRegistry extends CallbackRegistry<ObservableList.OnListChangedCallback, ObservableList, @@ -57,25 +60,59 @@ } }; + /** + * Notify registered callbacks that there was an unknown or whole-list change. + * + * @param list The list that changed. + */ public void notifyChanged(ObservableList list) { notifyCallbacks(list, ALL, null); } + /** + * Notify registered callbacks that some elements have changed. + * + * @param list The list that changed. + * @param start The index of the first changed element. + * @param count The number of changed elements. + */ public void notifyChanged(ObservableList list, int start, int count) { ListChanges listChanges = acquire(start, 0, count); notifyCallbacks(list, CHANGED, listChanges); } + /** + * Notify registered callbacks that elements were inserted. + * + * @param list The list that changed. + * @param start The index where the elements were inserted. + * @param count The number of elements that were inserted. + */ public void notifyInserted(ObservableList list, int start, int count) { ListChanges listChanges = acquire(start, 0, count); notifyCallbacks(list, INSERTED, listChanges); } + /** + * Notify registered callbacks that elements were moved. + * + * @param list The list that changed. + * @param from The index of the first element moved. + * @param to The index of where the element was moved to. + * @param count The number of elements moved. + */ public void notifyMoved(ObservableList list, int from, int to, int count) { ListChanges listChanges = acquire(from, to, count); notifyCallbacks(list, MOVED, listChanges); } + /** + * Notify registered callbacks that elements were deleted. + * + * @param list The list that changed. + * @param start The index of the first element to be removed. + * @param count The number of elements removed. + */ public void notifyRemoved(ObservableList list, int start, int count) { ListChanges listChanges = acquire(start, 0, count); notifyCallbacks(list, REMOVED, listChanges); @@ -101,9 +138,6 @@ } } - /** - * Creates an EventRegistry that notifies the event with notifier. - */ public ListChangeRegistry() { super(NOTIFIER_CALLBACK); }
diff --git a/library/src/main/java/android/databinding/MapChangeRegistry.java b/library/src/main/java/android/databinding/MapChangeRegistry.java index 5815606..9c453b6 100644 --- a/library/src/main/java/android/databinding/MapChangeRegistry.java +++ b/library/src/main/java/android/databinding/MapChangeRegistry.java
@@ -15,6 +15,9 @@ */ package android.databinding; +/** + * Utility class for managing ObservableMap callbacks. + */ public class MapChangeRegistry extends CallbackRegistry<ObservableMap.OnMapChangedCallback, ObservableMap, Object> { @@ -31,6 +34,12 @@ super(NOTIFIER_CALLBACK); } + /** + * Notifies registered callbacks that an element has been added, removed, or changed. + * + * @param sender The map that has changed. + * @param key The key of the element that changed. + */ public void notifyChange(ObservableMap sender, Object key) { notifyCallbacks(sender, 0, key); }
diff --git a/library/src/main/java/android/databinding/ObservableArrayList.java b/library/src/main/java/android/databinding/ObservableArrayList.java index 88c27e4..864e09e 100644 --- a/library/src/main/java/android/databinding/ObservableArrayList.java +++ b/library/src/main/java/android/databinding/ObservableArrayList.java
@@ -18,6 +18,9 @@ import java.util.ArrayList; import java.util.Collection; +/** + * An {@link ObservableList} implementation using ArrayList as an implementation. + */ public class ObservableArrayList<T> extends ArrayList<T> implements ObservableList<T> { private transient ListChangeRegistry mListeners = new ListChangeRegistry();
diff --git a/library/src/main/java/android/databinding/ObservableBoolean.java b/library/src/main/java/android/databinding/ObservableBoolean.java index f85ad08..73c65aa 100644 --- a/library/src/main/java/android/databinding/ObservableBoolean.java +++ b/library/src/main/java/android/databinding/ObservableBoolean.java
@@ -21,7 +21,14 @@ import java.io.Serializable; /** - * An observable class that holds a primitive int. + * An observable class that holds a primitive boolean. + * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableBoolean isAdult = new ObservableBoolean(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because @@ -46,10 +53,16 @@ public ObservableBoolean() { } + /** + * @return the stored value. + */ public boolean get() { return mValue; } + /** + * Set the stored value. + */ public void set(boolean value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableByte.java b/library/src/main/java/android/databinding/ObservableByte.java index 9133ec9..bba7ec1 100644 --- a/library/src/main/java/android/databinding/ObservableByte.java +++ b/library/src/main/java/android/databinding/ObservableByte.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive byte. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableByte flags = new ObservableByte(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableByte() { } + /** + * @return the stored value. + */ public byte get() { return mValue; } + /** + * Set the stored value. + */ public void set(byte value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableChar.java b/library/src/main/java/android/databinding/ObservableChar.java index acd5e84..883cb90 100644 --- a/library/src/main/java/android/databinding/ObservableChar.java +++ b/library/src/main/java/android/databinding/ObservableChar.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive char. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableChar firstInitial = new ObservableChar(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableChar() { } + /** + * @return the stored value. + */ public char get() { return mValue; } + /** + * Set the stored value. + */ public void set(char value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableDouble.java b/library/src/main/java/android/databinding/ObservableDouble.java index 3582017..78f6a48 100644 --- a/library/src/main/java/android/databinding/ObservableDouble.java +++ b/library/src/main/java/android/databinding/ObservableDouble.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive double. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableDouble temperature = new ObservableDouble(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableDouble() { } + /** + * @return the stored value. + */ public double get() { return mValue; } + /** + * Set the stored value. + */ public void set(double value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableField.java b/library/src/main/java/android/databinding/ObservableField.java index a3e49bc..6de798b 100644 --- a/library/src/main/java/android/databinding/ObservableField.java +++ b/library/src/main/java/android/databinding/ObservableField.java
@@ -19,6 +19,14 @@ /** * An object wrapper to make it observable. + * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableField<String> name = new ObservableField<String>(); + * public final ObservableInt age = new ObservableInt(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. * * @param <T> The type parameter for the actual object. * @see android.databinding.ObservableParcelable @@ -42,10 +50,16 @@ public ObservableField() { } + /** + * @return the stored value. + */ public T get() { return mValue; } + /** + * Set the stored value. + */ public void set(T value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableFloat.java b/library/src/main/java/android/databinding/ObservableFloat.java index 7e7f829..0eb8969 100644 --- a/library/src/main/java/android/databinding/ObservableFloat.java +++ b/library/src/main/java/android/databinding/ObservableFloat.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive float. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableFloat temperature = new ObservableFloat(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableFloat() { } + /** + * @return the stored value. + */ public float get() { return mValue; } + /** + * Set the stored value. + */ public void set(float value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableInt.java b/library/src/main/java/android/databinding/ObservableInt.java index 8affde2..cb25c56 100644 --- a/library/src/main/java/android/databinding/ObservableInt.java +++ b/library/src/main/java/android/databinding/ObservableInt.java
@@ -23,6 +23,14 @@ /** * An observable class that holds a primitive int. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableField<String> name = new ObservableField<String>(); + * public final ObservableInt age = new ObservableInt(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +54,16 @@ public ObservableInt() { } + /** + * @return the stored value. + */ public int get() { return mValue; } + /** + * Set the stored value. + */ public void set(int value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableLong.java b/library/src/main/java/android/databinding/ObservableLong.java index fbc98af..954e326 100644 --- a/library/src/main/java/android/databinding/ObservableLong.java +++ b/library/src/main/java/android/databinding/ObservableLong.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive long. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableLong friendCount = new ObservableLong(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableLong() { } + /** + * @return the stored value. + */ public long get() { return mValue; } + /** + * Set the stored value. + */ public void set(long value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/ObservableParcelable.java b/library/src/main/java/android/databinding/ObservableParcelable.java index 92ff87b..96eec27 100644 --- a/library/src/main/java/android/databinding/ObservableParcelable.java +++ b/library/src/main/java/android/databinding/ObservableParcelable.java
@@ -24,6 +24,14 @@ /** * An observable class that holds a parcelable object. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableParcelable<String> name = new ObservableParcelable<String>(); + * public final ObservableInt age = new ObservableInt(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable but you should keep in mind that listeners are ignored when the object * is parcelled. Unless you add custom observers, this should not be an issue because data binding * framework always re-registers observers when the view is bound.
diff --git a/library/src/main/java/android/databinding/ObservableShort.java b/library/src/main/java/android/databinding/ObservableShort.java index b4de9ea..57e428d 100644 --- a/library/src/main/java/android/databinding/ObservableShort.java +++ b/library/src/main/java/android/databinding/ObservableShort.java
@@ -23,6 +23,13 @@ /** * An observable class that holds a primitive short. * <p> + * Observable field classes may be used instead of creating an Observable object: + * <pre><code>public class MyDataObject { + * public final ObservableShort age = new ObservableShort(); + * }</code></pre> + * Fields of this type should be declared final because bindings only detect changes in the + * field's value, not of the field itself. + * <p> * This class is parcelable and serializable but callbacks are ignored when the object is * parcelled / serialized. Unless you add custom callbacks, this will not be an issue because * data binding framework always re-registers callbacks when the view is bound. @@ -46,10 +53,16 @@ public ObservableShort() { } + /** + * @return the stored value. + */ public short get() { return mValue; } + /** + * Set the stored value. + */ public void set(short value) { if (value != mValue) { mValue = value;
diff --git a/library/src/main/java/android/databinding/PropertyChangeRegistry.java b/library/src/main/java/android/databinding/PropertyChangeRegistry.java index 59de731..5e1858c 100644 --- a/library/src/main/java/android/databinding/PropertyChangeRegistry.java +++ b/library/src/main/java/android/databinding/PropertyChangeRegistry.java
@@ -15,6 +15,9 @@ */ package android.databinding; +/** + * Utility class for managing Observable callbacks. + */ public class PropertyChangeRegistry extends CallbackRegistry<Observable.OnPropertyChangedCallback, Observable, Void> { @@ -30,6 +33,13 @@ super(NOTIFIER_CALLBACK); } + /** + * Notifies registered callbacks that a specific property has changed. + * + * @param observable The Observable that has changed. + * @param propertyId The BR id of the property that has changed or BR._all if the entire + * Observable has changed. + */ public void notifyChange(Observable observable, int propertyId) { notifyCallbacks(observable, propertyId, null); }
diff --git a/library/src/main/java/android/databinding/ViewDataBinding.java b/library/src/main/java/android/databinding/ViewDataBinding.java index ee117a2..b23d7b8 100644 --- a/library/src/main/java/android/databinding/ViewDataBinding.java +++ b/library/src/main/java/android/databinding/ViewDataBinding.java
@@ -27,12 +27,19 @@ import android.text.TextUtils; import android.util.SparseIntArray; import android.view.Choreographer; +import android.view.LayoutInflater; import android.view.View; import android.view.View.OnAttachStateChangeListener; import android.view.ViewGroup; import java.lang.ref.WeakReference; +/** + * Base class for generated data binding classes. If possible, the generated binding should + * be instantiated using one of its generated static bind or inflate methods. If the specific + * binding is unknown, {@link DataBindingUtil#bind(View)} or + * {@link DataBindingUtil#inflate(LayoutInflater, int, ViewGroup, boolean)} should be used. + */ public abstract class ViewDataBinding { /** @@ -48,6 +55,8 @@ /** * Prefix for android:tag on Views with binding. The root View and include tags will not have * android:tag attributes and will use ids instead. + * + * @hide */ public static final String BINDING_TAG_PREFIX = "binding_"; @@ -267,6 +276,7 @@ * @param fieldId The BR ID of the field being changed or _all if * no specific field is being notified. * @return true if this change should cause a change to the UI. + * @hide */ protected abstract boolean onFieldChange(int localFieldId, Object object, int fieldId); @@ -394,7 +404,9 @@ } /** - * Returns the outermost View in the layout file associated with the Binding. + * Returns the outermost View in the layout file associated with the Binding. If this + * binding is for a merge layout file, this will return the first root in the merge tag. + * * @return the outermost View in the layout file associated with the Binding. */ public View getRoot() { @@ -540,6 +552,7 @@ * @return An array of size numBindings containing all Views in the hierarchy that have IDs * (with elements in viewsWithIds), are tagged containing expressions, or the bindings for * included layouts. + * @hide */ protected static Object[] mapBindings(DataBindingComponent bindingComponent, View root, int numBindings, IncludedLayouts includes, SparseIntArray viewsWithIds) {
diff --git a/library/src/main/java/android/databinding/ViewStubProxy.java b/library/src/main/java/android/databinding/ViewStubProxy.java index 2f2f512..6979928 100644 --- a/library/src/main/java/android/databinding/ViewStubProxy.java +++ b/library/src/main/java/android/databinding/ViewStubProxy.java
@@ -21,8 +21,9 @@ /** * This class represents a ViewStub before and after inflation. Before inflation, - * the ViewStub is accessible. After inflation, the ViewDataBinding is accessible - * if the inflated View has bindings. If not, the root View will be accessible. + * the ViewStub is accessible. After inflation, the root View of the inflated layout + * will be available. If the inflated layout has data binding, the ViewDataBinding for the inflated + * View is accessible. */ public class ViewStubProxy { private ViewStub mViewStub; @@ -58,31 +59,42 @@ } /** - * @return <code>true</code> if the ViewStub has replaced itself with the inflated layout + * Returns <code>true</code> if the ViewStub has replaced itself with the inflated layout * or <code>false</code> if not. + * + * @return <code>true</code> if the ViewStub has replaced itself with the inflated layout + * or <code>false</code> if not */ public boolean isInflated() { return mRoot != null; } /** - * @return The root View of the layout replacing the ViewStub once it has been inflated. + * Returns the root View of the layout replacing the ViewStub once it has been inflated. * <code>null</code> is returned prior to inflation. + * + * @return the root View of the layout replacing the ViewStub once it has been inflated. + * <code>null</code> is returned prior to inflation */ public View getRoot() { return mRoot; } /** - * @return The data binding associated with the inflated layout once it has been inflated. + * Returns the data binding associated with the inflated layout once it has been inflated. * <code>null</code> prior to inflation or if there is no binding associated with the layout. + * + * @return the data binding associated with the inflated layout once it has been inflated. + * <code>null</code> prior to inflation or if there is no binding associated with the layout */ public ViewDataBinding getBinding() { return mViewDataBinding; } /** - * @return The ViewStub in the layout or <code>null</code> if the ViewStub has been inflated. + * Returns the ViewStub in the layout or <code>null</code> if the ViewStub has been inflated. + * + * @return the ViewStub in the layout or <code>null</code> if the ViewStub has been inflated. */ public ViewStub getViewStub() { return mViewStub;