Activity templates cleanup.

This change cleans up the BlankActivity and MasterDetailFlow activity templates
in the following ways:

- Unused search icons are removed.
- Many comments are added for a better explanation of what's going on. See
  http://code.google.com/p/android/issues/detail?id=34463
- Code and comments are in better alignment with Android code style and
  import order (per http://source.android.com/source/code-style.html)
- Non-trivial BlankActivity templates now require API 11 instead of 14.
  More work TBD here.
- Templates are more lint-friendly.
- android:parentActivityName is added when building against API 16.

Change-Id: Iba7b807c7567b161b0e50fb39306209172627c35

7 files changed, 146 insertions, 134 deletions

diff --git a/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
index a7bbff0..fb19202 100644
--- a/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
@@ -1,12 +1,12 @@
 package ${packageName};
 
+<#if minApi < 14>import android.annotation.TargetApi;</#if>
 import android.app.ActionBar;
-import android.app.FragmentTransaction;
-import android.content.Context;
 import android.os.Bundle;
+<#if minApi < 14>import android.content.Context;
+import android.os.Build;</#if>
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
-import android.support.v4.app.FragmentManager;
 import android.support.v4.app.NavUtils;
 import android.view.Gravity;
 import android.view.LayoutInflater;
@@ -19,29 +19,34 @@ import android.widget.TextView;
 
 public class ${activityClass} extends FragmentActivity implements ActionBar.OnNavigationListener {
 
+    /**
+     * The serialization (saved instance state) Bundle key representing the
+     * current dropdown position.
+     */
     private static final String STATE_SELECTED_NAVIGATION_ITEM = "selected_navigation_item";
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
 
-        // Set up the action bar.
+        // Set up the action bar to show a dropdown list.
         final ActionBar actionBar = getActionBar();
         actionBar.setDisplayShowTitleEnabled(false);
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
 
         // Set up the dropdown list navigation in the action bar.
         actionBar.setListNavigationCallbacks(
                 // Specify a SpinnerAdapter to populate the dropdown list.
-                new ArrayAdapter(
-                        actionBar.getThemedContext(),
+                new ArrayAdapter<String>(
+                        <#if minApi gte 14>actionBar.getThemedContext()<#else>getActionBarThemedContextCompat()</#if>,
                         android.R.layout.simple_list_item_1,
                         android.R.id.text1,
-                        new String[]{
+                        new String[] {
                                 getString(R.string.title_section1),
                                 getString(R.string.title_section2),
                                 getString(R.string.title_section3),
@@ -49,8 +54,25 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
                 this);
     }
 
+    <#if minApi < 14>
+    /**
+     * Backward-compatible version of {@link ActionBar#getThemedContext()} that
+     * simply returns the {@link android.app.Activity} if
+     * <code>getThemedContext</code> is unavailable.
+     */
+    @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH)
+    private Context getActionBarThemedContextCompat() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
+            return getActionBar().getThemedContext();
+        } else {
+            return this;
+        }
+    }
+    </#if>
+
     @Override
     public void onRestoreInstanceState(Bundle savedInstanceState) {
+        // Restore the previously serialized current dropdown position.
         if (savedInstanceState.containsKey(STATE_SELECTED_NAVIGATION_ITEM)) {
             getActionBar().setSelectedNavigationItem(
                     savedInstanceState.getInt(STATE_SELECTED_NAVIGATION_ITEM));
@@ -59,20 +81,18 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
 
     @Override
     public void onSaveInstanceState(Bundle outState) {
+        // Serialize the current dropdown position.
         outState.putInt(STATE_SELECTED_NAVIGATION_ITEM,
                 getActionBar().getSelectedNavigationIndex());
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
     @Override
     public boolean onNavigationItemSelected(int position, long id) {
-        // When the given tab is selected, show the tab contents in the container
+        // When the given dropdown item is selected, show its contents in the
+        // container view.
         Fragment fragment = new DummySectionFragment();
         Bundle args = new Bundle();
         args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, position + 1);
@@ -83,23 +103,6 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
         return true;
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
-
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
index 6021829..a409ad4 100644
--- a/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
@@ -15,16 +15,12 @@ public class ${activityClass} extends Activity {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
         <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
         getActionBar().setDisplayHomeAsUpEnabled(true);
         </#if>
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
-<#if parentActivityClass != "">
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
-</#if>
+
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
index ba5c26c..b0a2f5d 100644
--- a/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
@@ -2,11 +2,9 @@ package ${packageName};
 
 import android.app.ActionBar;
 import android.app.FragmentTransaction;
-import android.content.Context;
 import android.os.Bundle;
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
-import android.support.v4.app.FragmentManager;
 import android.support.v4.app.NavUtils;
 import android.view.Gravity;
 import android.view.LayoutInflater;
@@ -18,19 +16,24 @@ import android.widget.TextView;
 
 public class ${activityClass} extends FragmentActivity implements ActionBar.TabListener {
 
+    /**
+     * The serialization (saved instance state) Bundle key representing the
+     * current tab position.
+     */
     private static final String STATE_SELECTED_NAVIGATION_ITEM = "selected_navigation_item";
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
 
-        // Set up the action bar.
+        // Set up the action bar to show tabs.
         final ActionBar actionBar = getActionBar();
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
 
         // For each of the sections in the app, add a tab to the action bar.
         actionBar.addTab(actionBar.newTab().setText(R.string.title_section1).setTabListener(this));
@@ -40,6 +43,7 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
 
     @Override
     public void onRestoreInstanceState(Bundle savedInstanceState) {
+        // Restore the previously serialized current tab position.
         if (savedInstanceState.containsKey(STATE_SELECTED_NAVIGATION_ITEM)) {
             getActionBar().setSelectedNavigationItem(
                     savedInstanceState.getInt(STATE_SELECTED_NAVIGATION_ITEM));
@@ -48,24 +52,18 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
 
     @Override
     public void onSaveInstanceState(Bundle outState) {
+        // Serialize the current tab position.
         outState.putInt(STATE_SELECTED_NAVIGATION_ITEM,
                 getActionBar().getSelectedNavigationIndex());
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
     @Override
-    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-    }
-
-    @Override
     public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-        // When the given tab is selected, show the tab contents in the container
+        // When the given tab is selected, show the tab contents in the
+        // container view.
         Fragment fragment = new DummySectionFragment();
         Bundle args = new Bundle();
         args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, tab.getPosition() + 1);
@@ -76,26 +74,13 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
     }
 
     @Override
-    public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
+    @Override
+    public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    }
 
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
index 58f6452..9e82449 100644
--- a/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
@@ -1,8 +1,7 @@
 package ${packageName};
 
-import android.app.ActionBar;
-import android.app.FragmentTransaction;
-import android.content.Context;
+<#if navType?contains("tabs")>import android.app.ActionBar;
+import android.app.FragmentTransaction;</#if>
 import android.os.Bundle;
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
@@ -21,10 +20,12 @@ import android.widget.TextView;
 public class ${activityClass} extends FragmentActivity<#if navType?contains("tabs")> implements ActionBar.TabListener</#if> {
 
     /**
-     * The {@link android.support.v4.view.PagerAdapter} that will provide fragments for each of the
-     * sections. We use a {@link android.support.v4.app.FragmentPagerAdapter} derivative, which will
-     * keep every loaded fragment in memory. If this becomes too memory intensive, it may be best
-     * to switch to a {@link android.support.v4.app.FragmentStatePagerAdapter}.
+     * The {@link android.support.v4.view.PagerAdapter} that will provide
+     * fragments for each of the sections. We use a
+     * {@link android.support.v4.app.FragmentPagerAdapter} derivative, which
+     * will keep every loaded fragment in memory. If this becomes too memory
+     * intensive, it may be best to switch to a
+     * {@link android.support.v4.app.FragmentStatePagerAdapter}.
      */
     SectionsPagerAdapter mSectionsPagerAdapter;
 
@@ -37,27 +38,32 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
-        // Create the adapter that will return a fragment for each of the three primary sections
-        // of the app.
-        mSectionsPagerAdapter = new SectionsPagerAdapter(getSupportFragmentManager());
 
         <#if navType?contains("tabs")>
         // Set up the action bar.
         final ActionBar actionBar = getActionBar();
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
+        <#elseif parentActivityClass != "">
+        // Show the Up button in the action bar.
+        getActionBar().setDisplayHomeAsUpEnabled(true);
         </#if>
 
+        // Create the adapter that will return a fragment for each of the three
+        // primary sections of the app.
+        mSectionsPagerAdapter = new SectionsPagerAdapter(getSupportFragmentManager());
+
         // Set up the ViewPager with the sections adapter.
         mViewPager = (ViewPager) findViewById(R.id.pager);
         mViewPager.setAdapter(mSectionsPagerAdapter);
 
         <#if navType?contains("tabs")>
-        // When swiping between different sections, select the corresponding tab.
-        // We can also use ActionBar.Tab#select() to do this if we have a reference to the
-        // Tab.
+        // When swiping between different sections, select the corresponding
+        // tab. We can also use ActionBar.Tab#select() to do this if we have
+        // a reference to the Tab.
         mViewPager.setOnPageChangeListener(new ViewPager.SimpleOnPageChangeListener() {
             @Override
             public void onPageSelected(int position) {
@@ -67,9 +73,10 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
 
         // For each of the sections in the app, add a tab to the action bar.
         for (int i = 0; i < mSectionsPagerAdapter.getCount(); i++) {
-            // Create a tab with text corresponding to the page title defined by the adapter.
-            // Also specify this Activity object, which implements the TabListener interface, as the
-            // listener for when this tab is selected.
+            // Create a tab with text corresponding to the page title defined by
+            // the adapter. Also specify this Activity object, which implements
+            // the TabListener interface, as the callback (listener) for when
+            // this tab is selected.
             actionBar.addTab(
                     actionBar.newTab()
                             .setText(mSectionsPagerAdapter.getPageTitle(i))
@@ -78,32 +85,27 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
         </#if>
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
-    <#if navType?contains("tabs")>
-    @Override
-    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    <#if navType?contains("tabs")>@Override
+    public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+        // When the given tab is selected, switch to the corresponding page in
+        // the ViewPager.
+        mViewPager.setCurrentItem(tab.getPosition());
     }
 
     @Override
-    public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-        // When the given tab is selected, switch to the corresponding page in the ViewPager.
-        mViewPager.setCurrentItem(tab.getPosition());
+    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
     }
 
     @Override
     public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-    }
-    </#if>
+    }</#if>
 
     /**
-     * A {@link FragmentPagerAdapter} that returns a fragment corresponding to one of the primary
-     * sections of the app.
+     * A {@link FragmentPagerAdapter} that returns a fragment corresponding to
+     * one of the sections/tabs/pages.
      */
     public class SectionsPagerAdapter extends FragmentPagerAdapter {
 
@@ -112,47 +114,37 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
         }
 
         @Override
-        public Fragment getItem(int i) {
+        public Fragment getItem(int position) {
+            // getItem is called to instantiate the fragment for the given page.
+            // Return a DummySectionFragment (defined as a static inner class
+            // below) with the page number as its lone argument.
             Fragment fragment = new DummySectionFragment();
             Bundle args = new Bundle();
-            args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, i + 1);
+            args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, position + 1);
             fragment.setArguments(args);
             return fragment;
         }
 
         @Override
         public int getCount() {
+            // Show 3 total pages.
             return 3;
         }
 
         @Override
         public CharSequence getPageTitle(int position) {
             switch (position) {
-                case 0: return getString(R.string.title_section1).toUpperCase();
-                case 1: return getString(R.string.title_section2).toUpperCase();
-                case 2: return getString(R.string.title_section3).toUpperCase();
+                case 0:
+                    return getString(R.string.title_section1).toUpperCase();
+                case 1:
+                    return getString(R.string.title_section2).toUpperCase();
+                case 2:
+                    return getString(R.string.title_section3).toUpperCase();
             }
             return null;
         }
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
-
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl
new file mode 100644
index 0000000..c455fc5
--- /dev/null
+++ b/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl
@@ -0,0 +1,25 @@
+    /**
+     * A dummy fragment representing a section of the app, but that simply
+     * displays dummy text.
+     */
+    public static class DummySectionFragment extends Fragment {
+        /**
+         * The fragment argument representing the section number for this
+         * fragment.
+         */
+        public static final String ARG_SECTION_NUMBER = "section_number";
+
+        public DummySectionFragment() {
+        }
+
+        @Override
+        public View onCreateView(LayoutInflater inflater, ViewGroup container,
+                Bundle savedInstanceState) {
+            // Create a new TextView and set its text to the fragment's section
+            // number argument value.
+            TextView textView = new TextView(getActivity());
+            textView.setGravity(Gravity.CENTER);
+            textView.setText(Integer.toString(getArguments().getInt(ARG_SECTION_NUMBER)));
+            return textView;
+        }
+    }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl
new file mode 100644
index 0000000..005d629
--- /dev/null
+++ b/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl
@@ -0,0 +1,6 @@
+    @Override
+    public boolean onCreateOptionsMenu(Menu menu) {
+        // Inflate the menu; this adds items to the action bar if it is present.
+        getMenuInflater().inflate(R.menu.${menuName}, menu);
+        return true;
+    }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
index 001e08f..e1dc462 100644
--- a/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
@@ -1,14 +1,19 @@
-
     <#if parentActivityClass != "">
 
     @Override
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
             case android.R.id.home:
+                // This ID represents the Home or Up button. In the case of this
+                // activity, the Up button is shown. Use NavUtils to allow users
+                // to navigate up one level in the application structure. For
+                // more details, see the Navigation pattern on Android Design:
+                //
+                // http://developer.android.com/design/patterns/navigation.html#up-vs-back
+                //
                 NavUtils.navigateUpFromSameTask(this);
                 return true;
         }
         return super.onOptionsItemSelected(item);
     }
     </#if>
-