Merge "docs: Wear DataItem listener improvements" into lmp-docs

docs/html/training/wearables/data-layer/data-items.jd

@@ -46,7 +46,7 @@ directly. Instead, you:
 </ol>
 
 <p>
-However, instead of working with raw bytes using <a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html#setData(byte[])">setData()</a>,
+However, instead of working with raw bytes using <a href="{@docRoot}reference/com/google/android/gms/wearable/PutDataRequest.html#setData(byte[])"><code>setData()</code></a>,
 we recommend you <a href="#SyncData">use a data map</a>, which exposes
 a data item in an easy-to-use {@link android.os.Bundle}-like interface.
 </p>
@@ -88,39 +88,121 @@ app, you should create a path scheme that matches the structure of the data.
   </li>
 </ol>
 
-<p>The following example shows how to create a data map and put data on it:</p>
+<p>The <code>increaseCounter()</code> method in the following example shows how to create a
+data map and put data in it:</p>
 
 <pre>
-PutDataMapRequest dataMap = PutDataMapRequest.create("/count");
-dataMap.getDataMap().putInt(COUNT_KEY, count++);
-PutDataRequest request = dataMap.asPutDataRequest();
-PendingResult&lt;DataApi.DataItemResult&gt; pendingResult = Wearable.DataApi
-        .putDataItem(mGoogleApiClient, request);
-</pre>
+public class MainActivity extends Activity implements
+        DataApi.DataListener,
+        GoogleApiClient.ConnectionCallbacks,
+        GoogleApiClient.OnConnectionFailedListener {
 
-<h2 id="ListenEvents">Listen for Data Item Events</h2>
-If one side of the data layer connection changes a data item, you probably want
-to be notified of any changes on the other side of the connection.
-You can do this by implementing a listener for data item events.
+    private static final String COUNT_KEY = "com.example.key.count";
 
-<p>For example, here's what a typical callback looks like to carry out certain actions
-when data changes:</p>
+    private GoogleApiClient mGoogleApiClient;
+    private int count = 0;
 
-<pre>
-&#64;Override
-public void onDataChanged(DataEventBuffer dataEvents) {
-    for (DataEvent event : dataEvents) {
-        if (event.getType() == DataEvent.TYPE_DELETED) {
-            Log.d(TAG, "DataItem deleted: " + event.getDataItem().getUri());
-        } else if (event.getType() == DataEvent.TYPE_CHANGED) {
-             Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri());
-        }
+    ...
+
+    // Create a data map and put data in it
+    private void <strong>increaseCounter</strong>() {
+        PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count");
+        putDataMapReq.getDataMap().putInt(COUNT_KEY, count++);
+        PutDataRequest putDataReq = putDataMapReq.asPutDataRequest();
+        PendingResult&lt;DataApi.DataItemResult> pendingResult =
+                Wearable.DataApi.putDataItem(mGoogleApiClient, putDataReq);
     }
+
+    ...
 }
 </pre>
-<p>
-This is just a snippet that requires more implementation details. Learn about
-how to implement a full listener service or activity in
+
+<p>For more information about handling the
+<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">
+<code>PendingResult</code></a> object, see
+<a href="{@docRoot}training/wearables/data-layer/events.html#Wait">Wait for the Status of Data
+Layer Calls</a>.</p>
+
+
+<h2 id="ListenEvents">Listen for Data Item Events</h2>
+
+<p>If one side of the data layer connection changes a data item, you probably want
+to be notified of any changes on the other side of the connection.
+You can do this by implementing a listener for data item events.</p>
+
+<p>The code snippet in the following example notifies your app when the value of the
+counter defined in the previous example changes:</p>
+
+<pre>
+public class MainActivity extends Activity implements
+        DataApi.DataListener,
+        GoogleApiClient.ConnectionCallbacks,
+        GoogleApiClient.OnConnectionFailedListener {
+
+    private static final String COUNT_KEY = "com.example.key.count";
+
+    private GoogleApiClient mGoogleApiClient;
+    private int count = 0;
+
+    &#64;Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_main);
+
+        mGoogleApiClient = new GoogleApiClient.Builder(this)
+                .addApi(Wearable.API)
+                .addConnectionCallbacks(this)
+                .addOnConnectionFailedListener(this)
+                .build();
+    }
+
+    &#64;Override
+    protected void onResume() {
+        super.onStart();
+        mGoogleApiClient.connect();
+    }
+
+    &#64;Override
+    public void onConnected(Bundle bundle) {
+        <strong>Wearable.DataApi.addListener</strong>(mGoogleApiClient, this);
+    }
+
+    &#64;Override
+    protected void onPause() {
+        super.onPause();
+        <strong>Wearable.DataApi.removeListener</strong>(mGoogleApiClient, this);
+        mGoogleApiClient.disconnect();
+    }
+
+    &#64;Override
+    public void <strong>onDataChanged</strong>(DataEventBuffer dataEvents) {
+        for (DataEvent event : dataEvents) {
+            if (event.getType() == DataEvent.TYPE_CHANGED) {
+                // DataItem changed
+                DataItem item = event.getDataItem();
+                if (item.getUri().getPath().compareTo("/count") == 0) {
+                    DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap();
+                    updateCount(dataMap.getInt(COUNT_KEY));
+                }
+            } else if (event.getType() == DataEvent.TYPE_DELETED) {
+                // DataItem deleted
+            }
+        }
+    }
+
+    // Our method to update the count
+    private void updateCount(int c) { ... }
+
+    ...
+}
+</pre>
+
+<p>This activity implements the
+<a href="{@docRoot}reference/com/google/android/gms/wearable/DataApi.DataListener.html">
+<code>DataItem.DataListener</code></a> interface. This activity adds itself as a listener
+for data item events inside the <code>onConnected()</code> method and removes the listener
+in the <code>onPause()</code> method.</p>
+
+<p>You can also implement the listener as a service. For more information, see
 <a href="{@docRoot}training/wearables/data-layer/events.html#Listen">Listen for Data Layer
-Events</a>.
-</p>
+Events</a>.</p>

docs/html/training/wearables/data-layer/events.jd

@@ -267,6 +267,8 @@ or <a href="{@docRoot}reference/com/google/android/gms/wearable/NodeApi.html#rem
 public class MainActivity extends Activity implements
         DataApi.DataListener, ConnectionCallbacks, OnConnectionFailedListener {
 
+    private GoogleApiClient mGoogleApiClient;
+
     &#64;Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -314,4 +316,5 @@ public class MainActivity extends Activity implements
             }
         }
     }
+}
 </pre>