Merge "docs: for AU basic training on fragments including ZIP for sample app" into ics-mr1

Author: scottamain

docs/html/images/training/basics/fragments-screen-mock.graffle/QuickLook/Preview.pdf

@@ -0,0 +1,179 @@
+page.title=Communicating with Other Fragments
+parent.title=Building a Dynamic UI with Fragments
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Building a Flexible UI
+previous.link=fragment-ui.html 
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb"> 
+    <h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#DefineInterface">Define an Interface</a></li>
+  <li><a href="#Implement">Implement the Interface</a></li>
+  <li><a href="#Deliver">Deliver a Message to a Fragment</a></li>
+</ol>
+    
+    <h2>You should also read</h2>
+    <ul>
+      <li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a></li>
+    </ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="http://developer.android.com/shareables/training/FragmentBasics.zip"
+class="button">Download the sample</a>
+ <p class="filename">FragmentBasics.zip</p>
+</div>
+
+  </div>
+</div>
+
+<p>In order to reuse the Fragment UI components, you should build each as a completely 
+self-contained, modular component that defines its own layout and behavior.  Once you 
+have defined these reusable Fragments, you can associate them with an Activity and 
+connect them with the application logic to realize the overall composite UI.</p>
+
+<p>Often you will want one Fragment to communicate with another, for example to change 
+the content based on a user event.  All Fragment-to-Fragment communication is done 
+through the associated Activity.  Two Fragments should never communicate directly.</p>
+
+
+<h2 id="DefineInterface">Define an Interface</h2>
+
+<p>To allow a Fragment to communicate up to its Activity, you can define an interface 
+in the Fragment class and implement it within the Activity.  The Fragment captures 
+the interface implementation during its onAttach() lifecycle method and can then call 
+the Interface methods in order to communicate with the Activity.</p>
+
+<p>Here is an example of Fragment to Activity communication:</p>
+
+<pre>
+public class HeadlinesFragment extends ListFragment {
+    OnHeadlineSelectedListener mCallback;
+
+    // Container Activity must implement this interface
+    public interface OnHeadlineSelectedListener {
+        public void onArticleSelected(int position);
+    }
+
+    &#64;Override
+    public void onAttach(Activity activity) {
+        super.onAttach(activity);
+        
+        // This makes sure that the container activity has implemented
+        // the callback interface. If not, it throws an exception
+        try {
+            mCallback = (OnHeadlineSelectedListener) activity;
+        } catch (ClassCastException e) {
+            throw new ClassCastException(activity.toString()
+                    + " must implement OnHeadlineSelectedListener");
+        }
+    }
+    
+    ...
+}
+</pre>
+
+<p>Now the fragment can deliver messages to the activity by calling the {@code
+onArticleSelected()} method (or other methods in the interface) using the {@code mCallback}
+instance of the {@code OnHeadlineSelectedListener} interface.</p>
+
+<p>For example, the following method in the fragment is called when the user clicks on a list
+item. The fragment uses the callback interface to deliver the event to the parent activity.</p>
+
+<pre>
+    &#64;Override
+    public void onListItemClick(ListView l, View v, int position, long id) {
+        // Send the event to the host activity
+        mCallback.onArticleSelected(position);
+    }
+</pre>
+
+
+
+<h2 id="Implement">Implement the Interface</h2>
+
+<p>In order to receive event callbacks from the fragment, the activity that hosts it must
+implement the interface defined in the fragment class.</p>
+
+<p>For example, the following activity implements the interface from the above example.</p>
+
+<pre>
+public static class MainActivity extends Activity
+        implements HeadlinesFragment.OnHeadlineSelectedListener{
+    ...
+    
+    public void onArticleSelected(Uri articleUri) {
+        // The user selected the headline of an article from the HeadlinesFragment
+        // Do something here to display that article
+    }
+}
+</pre>
+
+
+
+<h2 id="Deliver">Deliver a Message to a Fragment</h2>
+
+<p>The host activity can deliver messages to a fragment by capturing the {@link
+android.support.v4.app.Fragment} instance 
+with {@link android.support.v4.app.FragmentManager#findFragmentById findFragmentById()}, then
+directly call the fragment's public methods.</p>
+
+<p>For instance, imagine that the activity shown above may contain another fragment that's used to
+display the item specified by the data returned in the above callback method. In this case, 
+the activity can pass the information received in the callback method to the other fragment that
+will display the item:</p>
+
+<pre>
+public static class MainActivity extends Activity
+        implements HeadlinesFragment.OnHeadlineSelectedListener{
+    ...
+
+    public void onArticleSelected(int position) {
+        // The user selected the headline of an article from the HeadlinesFragment
+        // Do something here to display that article
+
+        ArticleFragment articleFrag = (ArticleFragment)
+                getSupportFragmentManager().findFragmentById(R.id.article_fragment);
+
+        if (articleFrag != null) {
+            // If article frag is available, we're in two-pane layout...
+
+            // Call a method in the ArticleFragment to update its content
+            articleFrag.updateArticleView(position);
+        } else {
+            // Otherwise, we're in the one-pane layout and must swap frags...
+
+            // Create fragment and give it an argument for the selected article
+            ArticleFragment newFragment = new ArticleFragment();
+            Bundle args = new Bundle();
+            args.putInt(ArticleFragment.ARG_POSITION, position);
+            newFragment.setArguments(args);
+        
+            FragmentTransaction transaction = getSupportFragmentManager().beginTransaction();
+
+            // Replace whatever is in the fragment_container view with this fragment,
+            // and add the transaction to the back stack so the user can navigate back
+            transaction.replace(R.id.fragment_container, newFragment);
+            transaction.addToBackStack(null);
+
+            // Commit the transaction
+            transaction.commit();
+        }
+    }
+}
+</pre>
+
+
+
+
+
+
+
+
+

docs/html/images/training/basics/fragments-screen-mock.graffle/QuickLook/Thumbnail.tiff

@@ -0,0 +1,155 @@
+page.title=Creating a Fragment
+parent.title=Building a Dynamic UI with Fragments
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Using the Android Support Library
+previous.link=support-lib.html
+next.title=Building a Flexible UI
+next.link=fragment-ui.html 
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+    
+    <h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#Create">Create a Fragment Class</a></li>
+  <li><a href="#AddInLayout">Add a Fragment to an Activity using XML</a></li>
+</ol>
+
+    <h2>You should also read</h2>
+    <ul>
+      <li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a></li>
+    </ul>
+
+<h2>Try it out</h2>
+    
+<div class="download-box">
+ <a href="http://developer.android.com/shareables/training/FragmentBasics.zip"
+class="button">Download the sample</a>
+ <p class="filename">FragmentBasics.zip</p>
+</div>
+
+  </div>
+</div>
+
+<p>You can think of a fragment as a modular section of an activity, which has its own lifecycle,
+receives its own input events, and which you can add or remove while the activity is running (sort
+of like a "sub activity" that you can reuse in different activities). This lesson shows how to
+extend the {@link android.support.v4.app.Fragment} class using the Support Library so your app
+remains compatible with devices running system versions as old as Android 1.6.</p>
+
+<p class="note"><strong>Note:</strong> If you decide for other reasons that the minimum
+API level your app requires is 11 or higher, you don't need to use the Support
+Library and can instead use the framework's built in {@link android.app.Fragment} class and related
+APIs. Just be aware that this lesson is focused on using the APIs from the Support Library, which
+use a specific package signature and sometimes slightly different API names than the versions
+included in the platform.</p>
+
+
+
+<h2 id="Create">Create a Fragment Class</h2>
+
+<p>To create a fragment, extend the {@link android.support.v4.app.Fragment} class, then override 
+key lifecycle methods to insert your app logic, similar to the way you would with an {@link
+android.app.Activity} class.</p>
+
+<p>One difference when creating a {@link android.support.v4.app.Fragment} is that you must use the
+{@link android.support.v4.app.Fragment#onCreateView onCreateView()} callback to define the layout.
+In fact, this is the only callback you need in order to get a fragment running. For
+example, here's a simple fragment that specifies its own layout:</p>
+
+<pre>
+import android.os.Bundle;
+import android.support.v4.app.Fragment;
+import android.view.LayoutInflater;
+import android.view.ViewGroup;
+
+public class ArticleFragment extends Fragment {
+    &#64;Override
+    public View onCreateView(LayoutInflater inflater, ViewGroup container, 
+        Bundle savedInstanceState) {
+        // Inflate the layout for this fragment
+        return inflater.inflate(R.layout.article_view, container, false);
+    }
+}
+</pre>
+
+<p>Just like an activity, a fragment should implement other lifecycle callbacks that allow you to
+manage its state as it is added or removed from the activity and as the activity transitions
+between its lifecycle states. For instance, when the activity's {@link
+android.app.Activity#onPause()} method is called, any fragments in the activity also receive a call
+to {@link android.support.v4.app.Fragment#onPause()}.</p>
+
+<p>More information about the fragment lifecycle and callback methods is available in the <a
+href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p>
+
+
+
+<h2 id="AddInLayout">Add a Fragment to an Activity using XML</h2> 
+
+<p>While fragments are reusable, modular UI components, each instance of a {@link
+android.support.v4.app.Fragment} class must be associated with a parent {@link
+android.support.v4.app.FragmentActivity}. You can achieve this association by defining each
+fragment within your activity layout XML file.</p>
+
+<p class="note"><strong>Note:</strong> {@link android.support.v4.app.FragmentActivity} is a
+special activity provided in the Support Library to handle fragments on system versions older than
+API level 11. If the lowest system version you support is API level 11 or higher, then you can use a
+regular {@link android.app.Activity}.</p>
+
+<p>Here is an example layout file that adds two fragments to an activity when the device
+screen is considered "large" (specified by the <code>large</code> qualifier in the directory
+name).</p>
+
+<p><code>res/layout-large/news_articles.xml:</code></p>
+<pre>
+&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:orientation="horizontal"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent">
+
+    &lt;fragment android:name="com.example.android.fragments.HeadlinesFragment"
+              android:id="@+id/headlines_fragment"
+              android:layout_weight="1"
+              android:layout_width="0dp"
+              android:layout_height="match_parent" />
+
+    &lt;fragment android:name="com.example.android.fragments.ArticleFragment"
+              android:id="@+id/article_fragment"
+              android:layout_weight="2"
+              android:layout_width="0dp"
+              android:layout_height="match_parent" />
+
+&lt;/LinearLayout>
+</pre>
+
+<p class="note"><strong>Tip:</strong> For more information about creating layouts for different
+screen sizes, read <a href="{@docRoot}training/multiscreen/screensizes.html">Supporting Different
+Screen Sizes</a>.</p>
+
+<p>Here's how an activity applies this layout:</p>
+
+<pre>
+import android.os.Bundle;
+import android.support.v4.app.FragmentActivity;
+
+public class MainActivity extends FragmentActivity {
+    &#64;Override
+    public void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.news_articles);
+    }
+}
+</pre>
+
+
+<p class="note"><strong>Note:</strong> When you add a fragment to an activity layout by defining
+the fragment in the layout XML file, you <em>cannot</em> remove the fragment at runtime. If you plan
+to swap your fragments in and out during user interaction, you must add the fragment to the activity
+when the activity first starts, as shown in the next lesson.</p>
+
+
+