Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f71f509a authored by Joe Malin's avatar Joe Malin Committed by Andrew Solovay
Browse files

Docs: New swipe-to-refresh training guide. 

Doc-in-progress inherited from xoogler's (unfinished) CL
http://ag/427505 . See comments for staging location.

Patch set 1 is the version inherited from the xoogler; PS2 is after
my edits. Per a conversation with CB, I've removed the "ListFragment"
doc, and just put in a note about that topic in the
"add-swipe-refresh" doc.

Change-Id: Id1a1294b15c5a7363f650ea13237948b0effbc40
parent 1fcc6bd8

docs/html/training/swipe/add-swipe-interface.jd

0 → 100644
+135 −0
Original line number Diff line number Diff line 
page.title=Adding Swipe-to-Refresh To Your App

trainingnavtop=true

@jd:body





<div id="tb-wrapper">

<div id="tb">



<!-- table of contents -->

<h2>This lesson teaches you to</h2>

<ol>

    <li><a href="#AddSwipeWidget">Add the SwipeRefreshLayout Widget</a>

    <li><a href="#AddRefreshAction">Add a Refresh Action to the Action Bar</a>

</ol>



<!-- other docs (NOT javadocs) -->

<h2>You should also read</h2>

<ul>

  <li>

    <a href=

    "{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a>

  </li>



  <li>

    <a href="{@docRoot}training/basics/actionbar/index.html">Adding the Action

    Bar</a>

  </li>

</ul>



<h2>Sample Apps</h2>



<ul>

    <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">

            SwipeRefreshLayoutBasic</a></li>

    <li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">

            SwipeRefreshListFragment</a></li>

</ul>



</div>

</div>





<p>

  The swipe-to-refresh user interface pattern is implemented entirely within

  the {@link android.support.v4.widget.SwipeRefreshLayout} widget, which

  detects the vertical swipe, displays a distinctive progress bar, and triggers

  callback methods in your app. You enable this behavior

  by adding the widget to your layout file as the parent of a {@link

  android.widget.ListView} or {@link android.widget.GridView}, and implementing

  the refresh behavior that gets invoked when the user swipes.

</p>



<p>

  This lesson shows you how to add the widget to an existing layout. It also

  shows you how to add a refresh action to the action bar overflow area, so

  that users who may be unable to use the swipe gesture can trigger a manual

  update with an external device.

</p>



<h2 id="AddSwipeWidget">Add the SwipeRefreshLayout Widget</h2>

<p>

  To add the swipe to refresh widget to an existing app, add {@link

  android.support.v4.widget.SwipeRefreshLayout} as the parent

  of a single {@link android.widget.ListView} or {@link

  android.widget.GridView}. Remember that {@link

  android.support.v4.widget.SwipeRefreshLayout} only supports a single {@link

  android.widget.ListView} or {@link android.widget.GridView} child.

</p>



<p>

  The following example demonstrates how to add the {@link

  android.support.v4.widget.SwipeRefreshLayout} widget to an existing layout

  file containing a {@link android.widget.ListView}:

</p>



<pre>&lt;android.support.v4.widget.SwipeRefreshLayout

    xmlns:android="http://schemas.android.com/apk/res/android"

    android:id="&#64;+id/swiperefresh"

    android:layout_width="match_parent"

    android:layout_height="match_parent"&gt;



    &lt;ListView

        android:id="&#64;android:id/list"

        android:layout_width="match_parent"

        android:layout_height="match_parent" /&gt;



&lt;/android.support.v4.widget.SwipeRefreshLayout&gt;</pre>



<p>

  You can also use the {@link android.support.v4.widget.SwipeRefreshLayout}

  widget with a {@link android.support.v4.app.ListFragment}. If the layout

  contains a {@link android.widget.ListView} with the ID

  <code>"@android:id/list"</code>, the swipe-to-refresh functionality is

  automatically supported. However, explicitly declaring the {@link

  android.widget.ListView} in this way supersedes the default {@link

  android.support.v4.app.ListFragment} view structure. If you want to use the

  default view structure, you will have to override parts of the {@link

  android.support.v4.widget.SwipeRefreshLayout} and {@link

  android.support.v4.app.ListFragment} behavior. For an example of how to do

  this, see the <a href=

  "{@docRoot}samples/SwipeRefreshListFragment/index.html">SwipeRefreshListFragment</a>

  sample app.

</p>



<h2 id="AddRefreshAction">Add a Refresh Action to the Action Bar</h2>



<p>

  You should add a refresh action to your app's action bar to ensure that

  users who may not be able to perform a swipe gesture can still trigger a

  manual update. For example, users with accessibility issues can trigger

  action bar actions using external devices, such as keyboards and D-pads.

</p>



<p>

  You should add the refresh action as a menu item,

  rather than as a button, by setting the attribute

  <code>android:showAsAction=never</code>. If you display the action as a

  button, users may assume that the refresh button action is different from the

  swipe-to-refresh action. By making the refresh action less conspicuous in the

  action bar, you can encourage users to perform manual updates with the swipe

  gesture while still maintaining the accessible option in a place where D-pad

  users would look for it.

</p>



<p>

  The following code demonstrates how to add the swipe-to-refresh action to the

  overflow area:

</p>



<pre>&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" &gt;

    &lt;item

        android:id="&#64;+id/menu_refresh"

        android:showAsAction="never"

        android:title="&#64;string/menu_refresh"/&gt;

&lt;/menu&gt;</pre>

docs/html/training/swipe/images/swipe.mp4

0 → 100644
+402 KiB

File added.

No diff preview for this file type.

View file

docs/html/training/swipe/images/swipe_original.mp4

0 → 100644
+726 KiB

File added.

No diff preview for this file type.

View file

docs/html/training/swipe/index.jd

0 → 100644
+91 −0
Original line number Diff line number Diff line 
page.title=Supporting Swipe-to-Refresh

trainingnavtop=true

startpage=true





@jd:body



<div id="tb-wrapper">

<div id="tb">



<h2>Dependencies and prerequisites</h2>

<ul>

  <li>Android 1.6 (API level 4) or later

  </li>



  <li>Latest version of the Android v4 <a href=

  "{@docRoot}tools/support-library/index.html">Support Library</a>

  </li>

</ul>



<h2>Sample Apps</h2>



<ul>

    <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">

            SwipeRefreshLayoutBasic</a></li>

    <li><a href="{@docRoot}samples/SwipeRefreshListFragment/index.html">

            SwipeRefreshListFragment</a></li>

    <li><a href="{@docRoot}samples/SwipeRefreshMultipleViews/index.html">

            SwipeRefreshMultipleViews</a></li>

</ul>



</div>

</div>



<p>

  Even if your app automatically updates its content on a regular basis, you

  can allow users to request manual updates as well. For example, a weather

  forecasting app can allow users get the latest forecasts on demand. To

  provide a standard user experience for requesting updates, the Android

  platform includes the swipe-to-refresh design pattern, which allows users

  to trigger an update with a vertical swipe.

</p>



<p class="note">

  <strong>Note:</strong> This class requires the latest version of the Android

  v4 Support Library APIs. If you have not used the Support Library before,

  follow the instructions in the <a href=

  "{@docRoot}tools/support-library/setup.html">Support Library Setup</a>

  document.

</p>



<h2>Lessons</h2>



<dl>

  <dt>

    <b><a href="add-swipe-interface.html">Adding Swipe-to-Refresh To Your

    App</a></b>

  </dt>



  <dd>

    <div style="width:290px;margin-right:35px;float:right">

      <div class="framed-nexus5-port-span-5">

        <video class="play-on-hover" autoplay alt=

        "When the user performs a swipe gesture, the SwipeRefreshLayout widget displays a progress indicator until your app finishes updating its data.">

        <!-- Preferred video size 216x384 (portrait) -->

          <source src="images/swipe.mp4">

        </video>

      </div>



      <div style="font-size:10pt;margin-left:20px;margin-bottom:30px">

        <em>To replay the movie, click on the device screen</em>

      </div>

    </div>

  </dd>



  <dd>

    Learn how to provide swipe-to-refresh support in a {@link

    android.widget.ListView} or {@link android.widget.GridView}, and how to

    provide an accessible refresh option using the action bar.

  </dd>



  <dt>

    <b><a href="respond-refresh-request.html">Responding to a Refresh

    Request</a></b>

  </dt>



  <dd>

    Learn how to respond to the swipe-to-refresh gesture, and how to perform the

    same update from an action bar action.

  </dd>

</dl>

docs/html/training/swipe/respond-refresh-request.jd

0 → 100644
+158 −0
Original line number Diff line number Diff line 
page.title=Responding to a Refresh Request



trainingnavtop=true

@jd:body



<div id="tb-wrapper">

<div id="tb">



<!-- table of contents -->

<h2>This lesson teaches you to</h2>

<ol>

  <li><a href="#RespondRefresh">Respond to the Refresh Gesture</a></li>

  <li><a href="#RespondAction">Respond to the Refresh Action</a>

</ol>



<h2>Sample App</h2>



<ul>

    <li><a href="{@docRoot}samples/SwipeRefreshLayoutBasic/index.html">

            SwipeRefreshLayoutBasic</a></li>

</ul>





</div>

</div>



<p>

  This lesson shows you how to update your app when the user requests a manual

  refresh, whether the user triggers the refresh with a swipe gesture or by

  using the action bar refresh action.

</p>



<h2 id="RespondRefresh">Respond to the Refresh Gesture</h2>



<p>

  When the user makes a swipe gesture, the system displays the progress

  indicator and calls your app's callback method. Your callback method is

  responsible for actually updating the app's data.

</p>



<p>

  To respond to the refresh gesture in your app, implement the {@link

  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener} interface and

  its {@link

  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh

  onRefresh()} method. The {@link

  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh

  onRefresh()} method is invoked when the user performs a swipe gesture.

</p>



<p>

  You should put the code for the actual update

  operation in a separate method, and call that update method from your {@link

  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh

  onRefresh()} implementation. That way, you can use the same update method to

  perform the update when the user triggers a refresh from the action bar.

</p>



<p>

  Your update method calls {@link

  android.support.v4.widget.SwipeRefreshLayout#setRefreshing

  setRefreshing(false)} when it has finished updating the data. Calling this

  method instructs the {@link android.support.v4.widget.SwipeRefreshLayout} to

  remove the progress indicator and update the view contents.

</p>



<p>

  For example, the following code implements {@link

  android.support.v4.widget.SwipeRefreshLayout.OnRefreshListener#onRefresh

  onRefresh()} and invokes the method {@code myUpdateOperation()} to update the

  data displayed by the {@link android.widget.ListView}:

</p>



<pre>/*

 * Sets up a SwipeRefreshLayout.OnRefreshListener that is invoked when the user

 * performs a swipe-to-refresh gesture.

 */

mySwipeRefreshLayout.setOnRefreshListener(

    new SwipeRefreshLayout.OnRefreshListener() {

        &#64;Override

        public void onRefresh() {

            Log.i(LOG_TAG, "onRefresh called from SwipeRefreshLayout");



            // This method performs the actual data-refresh operation.

            // The method calls setRefreshing(false) when it's finished.

            myUpdateOperation();

        }

    }

);</pre>



<h2 id="RespondAction">Respond to the Refresh Action</h2>



<p>

  If the user requests a refresh by using the action bar, the system calls the

  {@link android.support.v4.app.Fragment#onOptionsItemSelected

  onOptionsItemSelected()} method. Your app should respond to this call by

  displaying the progress indicator and refreshing the app's data.

</p>



<p>

  To respond to the refresh action, override {@link

  android.support.v4.app.Fragment#onOptionsItemSelected

  onOptionsItemSelected()}. In your override method, trigger the {@link

  android.support.v4.widget.SwipeRefreshLayout} progress indicator by calling

  {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing

  setRefreshing()} with the value {@code true}, then perform the update

  operation. Once again, you should be doing the actual update in a separate

  method, so the same method can be called whether the user triggers the update

  with a swipe or by using the action bar. When the update has finished, call

  {@link android.support.v4.widget.SwipeRefreshLayout#setRefreshing

  setRefreshing(false)} to remove the refresh progress indicator.

</p>



<p>The following code shows how to respond to the request action:

</p>



<pre>/*

 * Listen for option item selections so that we receive a notification

 * when the user requests a refresh by selecting the refresh action bar item.

 */

&#64;Override

public boolean onOptionsItemSelected(MenuItem item) {

    switch (item.getItemId()) {



        // Check if user triggered a refresh:

        case R.id.menu_refresh:

            Log.i(LOG_TAG, "Refresh menu item selected");



            // Signal SwipeRefreshLayout to start the progress indicator

            mySwipeRefreshLayout.setRefreshing(true);



            // Start the refresh background task.

            // This method calls setRefreshing(false) when it's finished.

            myUpdateOperation();



            return true;

    }



    // User didn't trigger a refresh, let the superclass handle this action

    return super.onOptionsItemSelected(item);



}</pre>



<p class="note">

  <strong>Note:</strong> When the user triggers a refresh with a swipe action as

  described in <a href="#RespondRefresh">Respond to the Refresh Gesture</a>,

  you do not need to call {@link

  android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.

  The {@link

  android.support.v4.widget.SwipeRefreshLayout} widget takes care of displaying

  the progress indicator and removing it when the update has finished. However,

  if the update is triggered by any means <em>other than</em> a swipe gesture,

  you need to explicitly turn the progress indicator on with {@link

  android.support.v4.widget.SwipeRefreshLayout#setRefreshing setRefreshing()}.

  The method which actually refreshes the data calls {@link

  android.support.v4.widget.SwipeRefreshLayout#setRefreshing

  setRefreshing(false)} to signal that the update is finished.

</p>