Programming with fragments

The user interface in this section’s example has three panels — a list of items, a detail panel describing whichever item is selected in the list, and a details-in-more-depth panel. On a small smartphone screen, each panel might be a separate activity. But a tablet screen in landscape mode has room for more than one panel.

Figure 1-1 shows this section’s app with two of the three panels. The panel on the left displays a list of Android SDK components. The panel on the right displays a description of whatever component is chosen in the list on the left. (The description is actually the first few sentences of the component’s SDK documentation.) This details-on-the-right pattern is part of many user interfaces.

To create the display in Figure 1-1, you build one activity. The activity has two fragments — a fragment on the left and another on the right. The left panel displays the same fragment throughout the run of the app, so you can declare that fragment in the activity’s layout file. The right panel displays one fragment at a time, but the fragment changes during the app’s run. So you declare a frame layout in the right panel. Listing 1-1 has the code.

Listing 1-1: The Main Activity’s Layout

<?xml version="1.0" encoding="utf-8"?>

<LinearLayout xmlns:android=

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

    android:orientation="horizontal"

    android:layout_width="match_parent"

    android:layout_height="match_parent">

    <fragment class=

          "com.allmycode.frag.ComponentNamesFragment"

        android:id="@+id/component_names"

        android:layout_height="match_parent"

        android:layout_width="0px"

        android:layout_weight="1" />

    <FrameLayout android:id="@+id/docs"

        android:layout_height="match_parent"

        android:layout_width="0px"

        android:layout_weight="1"

        android:background=

          "?android:attr/detailsElementBackground" />

</LinearLayout>

In Listing 1-1, the android:layout_whatever attributes divide the screen into two halves — one half for the fragment element and the other half for the FrameLayout element. The strategy with these attributes is to start by assigning a minimum of zero pixels for each element. Of course, zero pixels means no width at all (which is the same as being invisible). To keep the two halves of the layout from being invisible, assign equal non-zero layout_weight values to the two halves. With non-zero weight values, each half expands to fill the available space in the layout.

In Listing 1-1, the use of the fragment’s fully qualified class name (com.allmycode.frag.ComponentNamesFragment) is intentional. An abbreviated name (such as .ComponentNamesFragment) won’t cut the mustard.

In case you’re wondering, Android’s built-in detailsElementBackground (also in Listing 1-1) provides a uniform look for things like the right half of Figure 1-1 (things that display details about an item that the user has selected).

The app’s main activity code is impressively uninteresting. (See Listing 1-2.)

Listing 1-2: The Main Activity

package com.allmycode.frag;

import android.app.Activity;

import android.os.Bundle;

public class AllPurposeActivity extends Activity {

  @Override

  protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

  }

}

Listing 1-3 contains the ComponentNamesFragment class. By virtue of the layout in Listing 1-1, Android plants a ComponentNamesFragment on the left side of the device’s screen (refer to Figure 1-1).

Listing 1-3: A Fragment Containing a List of Items

package com.allmycode.frag;

import android.app.FragmentManager;

import android.app.FragmentTransaction;

import android.app.ListFragment;

import android.os.Bundle;

import android.view.View;

import android.widget.ArrayAdapter;

import android.widget.ListView;

public class ComponentNamesFragment extends ListFragment {

  final static String[] COMPONENTS = { "Activity",

      "Service", "BroadcastReceiver", "ContentProvider" };

  @Override

  public void onActivityCreated

      (Bundle savedInstanceState) {

    super.onActivityCreated(savedInstanceState);

    setListAdapter(new ArrayAdapter<>(getActivity(),

        android.R.layout.simple_list_item_1, COMPONENTS));

  }

  @Override

  public void onListItemClick(ListView l, View v,

      int index, long id) {

    //Create fragment with index

    DocsFragment docsFragment = new DocsFragment();

    Bundle args = Helper.getBundleWithIndex(index);

    docsFragment.setArguments(args);

    //Clear the back stack

    FragmentManager fragmentManager =

          getFragmentManager();

    int backStackEntryCount =

        fragmentManager.getBackStackEntryCount();

    for (int i = 0; i < backStackEntryCount; i++) {

      fragmentManager.popBackStackImmediate();

    }

    //Perform the transaction

    FragmentTransaction fragmentTransaction =

          fragmentManager.beginTransaction();

    fragmentTransaction.replace(R.id.docs, docsFragment);

    fragmentTransaction.addToBackStack(null);

    fragmentTransaction.commit();

  }

}

The class in Listing 1-3 extends Android’s ListFragment class. A ListFragment is a fragment that displays a list. Early on in the fragment’s lifecycle, the code in Listing 1-3 sets a list adapter (more specifically, an ArrayAdapter) for the fragment. So how early is “early on”?

As in the examples from Chapter 2 of Book IV, the ArrayAdapter constructor’s first parameter is a context. But wait! Unlike an activity, a fragment isn’t a context. So you can’t use the keyword this for the ArrayAdapter constructor’s first parameter.

Fortunately, a fragment has a getActivity method. A call to getActivity grabs the activity to which the fragment is attached. So, for the ArrayAdapter constructor’s first parameter, you can call getActivity. Of course, you can’t call getActivity until the fragment is attached to an existing activity. That’s why, in Listing 1-3, I override the fragment’s onActivityCreated method. Android calls onActivityCreated after attaching the fragment and calling the activity’s onCreate method. So everything works as planned.

The android.app.Activity class’s great-grandparent class is android.content.Context. But the android.app.Fragment class’s parent class is plain old java.lang.Object. Therefore, in an activity’s code, the keyword this refers to a context. But in a fragment’s code, the keyword this doesn’t refer to a context.

A ListFragment is like a ListActivity — except that it’s a fragment, not an activity. Many of the ListActivity class’s concepts apply as well to the ListFragment class. To read about Android’s ListActivity class, see Chapter 2 of Book IV.

In Listing 1-3, the constructor for the ArrayAdapter has three parameters.

• The first parameter is the context — that nasty parameter that forces me to put the constructor inside the onActivityCreated method.

• The second parameter is simple_list_item_1 — a standard Android layout.

  The simple_list_item_ 1 layout creates the look that you see on the left side in Figure 1-1. Android has lots of these standard layouts. For a roundup of the available layouts, visit http://developer.android.com/reference/android/R.layout.html.

• The third parameter is the collection of items that will appear in the list.

  In this example, those items come from the COMPONENTS array, which is declared in that same listing — Listing 1-3.

Like a ListActivity, a ListFragment has an onListItemClick method. In Listing 1-3, I respond to a click by working with a DocsFragment, a FragmentTransaction, and a FragmentManager:

• The DocsFragment instance in Listing 1-3 represents the right side of Figure 1-1.
• A fragment transaction is a bunch of things you do with fragments. For example, setting up to replace one fragment with another (as in Listing 1-3) is a transaction.
• A fragment manager does what its name suggests. It manages fragments' arrivals and departures.

Fragments, more fragments, and even more fragments

The right panel in Figure 1-1 has a More button. When the user presses this More button, the app displays a more verbose description of the selected component. To find out how this happens, stare thoughtfully (but joyfully) at the code in Listing 1-4.

Listing 1-4: Code to Create the Fragment on the Right Side of Figure 1-1

package com.allmycode.frag;

import android.app.Fragment;

import android.app.FragmentTransaction;

import android.os.Bundle;

import android.view.LayoutInflater;

import android.view.View;

import android.view.View.OnClickListener;

import android.view.ViewGroup;

import android.widget.Button;

import android.widget.LinearLayout;

import android.widget.TextView;

public class DocsFragment extends Fragment

        implements OnClickListener {

  TextView textView1;

  @Override

  public View onCreateView(LayoutInflater inflater,

        ViewGroup container,

        Bundle savedInstanceState) {

    return myLayout();

  }

  @Override

  public void onClick(View view) {

    int index = getArguments().getInt("index");

    //Create fragment with index

    DocsFragmentVerbose docsFragmentVerbose =

        new DocsFragmentVerbose();

    Bundle args = Helper.getBundleWithIndex(index);

    docsFragmentVerbose.setArguments(args);

    //Perform the transaction

    FragmentTransaction fragmentTransaction =

          getFragmentManager().beginTransaction();

    fragmentTransaction.replace(R.id.docs,

        docsFragmentVerbose);

    fragmentTransaction.addToBackStack(null);

    fragmentTransaction.commit();

  }

  final static int[] DOCS = {

      R.string.doc_activity,

      R.string.doc_service,

      R.string.doc_broadcast_receiver,

      R.string.content_provider

  };

  private LinearLayout myLayout() {

    LinearLayout layout = new LinearLayout(getActivity());

    layout.setOrientation(LinearLayout.VERTICAL);

    int index = getArguments().getInt("index");

    textView1 = new TextView(getActivity());

    textView1.setTextSize(30);

    textView1

        .setText(ComponentNamesFragment.COMPONENTS[index]);

    layout.addView(textView1);

    TextView textView2 = new TextView(getActivity());

    textView2.setTextSize(20);

    textView2.setText(DOCS[index]);

    layout.addView(textView2);

    Button button = new Button(getActivity());

    button.setText(R.string.more);

    button.setOnClickListener(this);

    layout.addView(button);

    return layout;

  }

}

In Listing 1-4, the onCreateView and myLayout methods use Java code to compose a layout — the layout on the right side in Figure 1-1. The listing’s onCreateView method returns a linear layout, which is a view group, which is a view. And that view becomes the fragment’s visible presence on the tablet screen.

In Listing 1-4, I define a fragment’s layout using Java code instead of a res/layout XML document. Book IV, Chapter 1 goes into more detail on using Java code to define views and layouts.

The DOCS array near the bottom of Listing 1-4 is interesting. I use this array in the middle of the listing to set the text in a text view. This array is an array of int values — an array of code numbers for strings defined in the project’s res/values/strings.xml file. The lines in the file are very long, so I don’t paste the entire strings.xml file onto this page. But here’s a chopped-off version of the file:

<?xml version="1.0" encoding="utf-8"?>

<resources>

  <string name="app_name">MyFragmentCode</string>

  <string name="more">More</string>

  <string name="doc_activity">An activity is a single, focused thing that <string name="doc_service">A Service is an application component representing

  <string name="doc_broadcast_receiver">Base class for code that will receive

  <string name="content_provider">Content providers are one of the primary

</resources>

The text in each string is a few sentences copied from the Android SDK documentation. (Just for fun, try turning this printed page so that you’re reading it in landscape mode. Maybe then you’ll see the chopped-off portion of the strings.xml file.)

In the description of a broadcast receiver, the documentation contains the phrase the <receiver> tag, with angle brackets and all. (Refer to Figure 1-1.) You can’t just plop the text the <receiver> tag inside your strings.xml file because the angle brackets in

<string name="…">Base class…< receiver > … </string>

would confuse an XML parser. You have to tell the XML parser that the angle brackets surrounding the word receiver are plain old text — not official parts of the XML code. Fortunately, XML provides a standard way of doing this. You enclose the angle brackets in CDATA sections:

the <![CDATA[<]]>receiver<![CDATA[>]]> tag

Building the fragment stack

In Listing 1-4, the onClick method replaces the right side of Figure 1-1 with a brand-new fragment — an instance of my DocsFragmentVerbose class. And clever guy that I am, I programmed the DocsFragmentVerbose class to display a page from the official Android documentation website. Listing 1-5 contains the code.

Listing 1-5: A Fragment Containing a Web View

package com.allmycode.frag;

import android.app.Fragment;

import android.os.Bundle;

import android.view.LayoutInflater;

import android.view.View;

import android.view.ViewGroup;

import android.webkit.WebView;

public class DocsFragmentVerbose extends Fragment {

  @Override

  public View onCreateView(LayoutInflater inflater,

        ViewGroup container,

        Bundle savedInstanceState) {

    WebView webView = new WebView(getActivity());

    int index = getArguments().getInt("index");

    webView.loadUrl(

        "http://developer.android.com/reference/android/"

            + ((index < 2) ? "app/" : "content/")

            + ComponentNamesFragment.COMPONENTS[index]

            + ".html");

    return webView;

  }

}

 

At this point, I can describe the whole storyboard for this section’s grand example:

• The user sees a list — namely, the list of component names in the left fragment in Figure 1-1.

• The user selects an item in the list.

  In response, the app displays a brief description of the selected item. In Figure 1-1, the description is the first few sentences of Android’s BroadcastReceiver documentation.

  To display the description, the code in Listing 1-3 calls replace(R.id.docs, docsFragment). That is, the code places a fragment into the R.id.docs view.

• The newly displayed fragment contains a brief description and a button. (Refer to Figure 1-1.) If the user clicks the button, the app covers this fragment with an even newer fragment.

  In Figure 1-2, the new fragment displays the BroadcastReceiver's online documentation page.

To load a page from the Internet, your app’s AndroidManifest.xml document must have a <uses-permission android:name="android.permission.INTERNET" /> element.

Change 1: Create an additional activity

Listing 1-6 contains the new DocsActivityVerbose activity.

Listing 1-6: An Activity That’s a Wrapper for a Fragment

package com.allmycode.frag;

import android.app.Activity;

import android.app.FragmentManager;

import android.app.FragmentTransaction;

import android.os.Bundle;

public class DocsActivityVerbose extends Activity {

  @Override

  public void onCreate(Bundle bundle) {

    super.onCreate(bundle);

    setContentView(R.layout.docs_verbose);

    int index = getIntent().getIntExtra("index", 0);

    //Create fragment with index

    DocsFragmentVerbose docsFragmentVerbose =

          new DocsFragmentVerbose();

    Bundle args = Helper.getBundleWithIndex(index);

    docsFragmentVerbose.setArguments(args);

    //Perform the transaction

    FragmentManager fragmentManager =

            getFragmentManager();

    FragmentTransaction fragmentTransaction =

          fragmentManager.beginTransaction();

    fragmentTransaction.replace(R.id.docs_verbose_frame,

            docsFragmentVerbose);

    fragmentTransaction.commit();

  }

}

The new DocsActivityVerbose class performs the same fragment transaction that’s performed by the onClick method in Listing 1-4.

Notice that the code in Listing 1-6 doesn’t call the addToBackStack method. If you were to call addToBackStack in Listing 1-6, Android would push the web page fragment on top of an initially empty fragment. Then, if the user were to press the Back button, Android would pop the web page fragment off the stack. The user would see an empty fragment that consumes the entire screen.

When you add an activity to a project (such as the activity in Listing 1-6), you must add an <activity> element to the project’s AndroidManifest.xml document. For the code in Listing 1-6, the new <activity> element looks like this:

<activity android:name=

  "com.allmycode.frag.DocsActivityVerbose" />

If you create the new activity using Android Studio’s tools, the <activity> element is added automatically. But if you create a new Java class and then turn the class into an activity, you must add the <activity> element manually.

Like many activity classes, the new DocsActivityVerbose class uses its own layout resource. And sure enough, the onCreate method in Listing 1-6 refers to an R.layout.docs_verbose resource. Listing 1-7 contains my docs_verbose.xml file.

Listing 1-7: A Layout for the New DocsActivityVerbose Class

<?xml version="1.0" encoding="utf-8"?>

<LinearLayout xmlns:android=

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

    android:layout_width="match_parent"

    android:layout_height="match_parent">

    <FrameLayout android:id="@+id/docs_verbose_frame"

        android:layout_height="match_parent"

        android:layout_width="match_parent"

        android:layout_weight="1" />

</LinearLayout>

The layout for the DocsActivityVerbose class contains only one element — namely, the fragment that displays an Android documentation web page.

Change 2: Tweak the DocsFragment code

Having created the new DocsActivityVerbose class and its required layout resource, you’re ready to integrate these files into the rest of the app’s code. To do this, consider two situations:

• When the user presses the More button, you either replace the existing fragment or start your new DocsActivityVerbose, depending on the screen’s orientation.
• When the user turns the device sideways, you check whether the new orientation will cause the awkward crunch shown back in Figure 1-3. If so, you need to back away from displaying the web page fragment.

To handle the first situation, replace the DocsFragment code’s onClick method (see Listing 1-8).

Listing 1-8: Deciding What to Do When the User Clicks a Button

@Override

public void onClick(View view) {

  int index = getArguments().getInt("index");

  if (Helper.isDenseWideScreen(getActivity())) {

    //Create fragment with index

    DocsFragmentVerbose docsFragmentVerbose =

            new DocsFragmentVerbose();

    Bundle args = Helper.getBundleWithIndex(index);

    docsFragmentVerbose.setArguments(args);

    //Perform the transaction

    FragmentTransaction fragmentTransaction =

        getFragmentManager().beginTransaction();

    fragmentTransaction.replace(R.id.docs,

                docsFragmentVerbose);

    fragmentTransaction.addToBackStack(null);

    fragmentTransaction.commit();

  } else {

    Intent intent = new Intent();

    intent.setClass(getActivity(),

    DocsActivityVerbose.class);

    intent.putExtra("index", index);

    startActivity(intent);

  }

}

The original DocsFragment class in Listing 1-4 doesn’t check the screen’s size or orientation. But the code in Listing 1-8 responds in different ways, depending on the result of the isDenseWideScreen method call. On a dense, wide screen, the code in Listing 1-8 mimics the code in Listing 1-4. But on a lesser screen, Listing 1-8 starts an instance of the new DocsActivityVerbose class.

The code for the isDenseWideScreen method is in Listing 1-9, along with the rest of this chapter’s Helper class.

Listing 1-9: The Helper Method

package com.allmycode.frag;

import android.app.Activity;

import android.content.res.Configuration;

import android.os.Bundle;

import android.util.DisplayMetrics;

public class Helper {

  static Bundle getBundleWithIndex(int index) {

    Bundle bundle = new Bundle();

    bundle.putInt("index", index);

    return bundle;

  }

  static boolean isDenseWideScreen(Activity activity) {

    DisplayMetrics metrics = new DisplayMetrics();

    activity.getWindowManager().

       getDefaultDisplay().getMetrics(metrics);

    boolean isDenseScreen =

       metrics.densityDpi >= DisplayMetrics.DENSITY_XHIGH;

    boolean isWideScreen =

       activity.getResources().

          getConfiguration().orientation ==

                Configuration.ORIENTATION_LANDSCAPE;

    return isDenseScreen && isWideScreen;

  }

}

Change 3: Tweak the app’s main activity

When the user turns the device sideways, Android destroys the current activity and creates the activity anew. If the turn is from landscape to portrait mode, you don’t want a fragment that displays a web page to hang around awkwardly on the right side of the screen. So, when Android calls your main activity’s onCreate method, you need to test for a dense, wide screen. If the user’s screen doesn’t pass this test, then remove any web pages from the fragment’s back stack.

Listing 1-10 contains the enhanced AllPurposeActivity code.

Listing 1-10: Your New, Improved Main Activity

package com.allmycode.frag;

import android.app.Activity;

import android.app.FragmentManager;

import android.os.Bundle;

public class AllPurposeActivity extends Activity {

  @Override

  protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    //Clear the back stack if necessary

    if (!Helper.isDenseWideScreen(this)) {

      FragmentManager fragmentManager =

            getFragmentManager();

      if (fragmentManager.getBackStackEntryCount() > 1) {

          fragmentManager.popBackStackImmediate();

      }

    }

  }

}

The code in Listing 1-10 asks how many fragments are currently on the activity’s stack of fragments. If the count is more than one, the most recently created fragment is the dreaded web page fragment. To eliminate the danger, the code pops the web page fragment off the stack.

Change 4: Create an additional layout

With or without a web page, you don’t want any side-by-side fragments when the screen is small. In this section’s example, a “small screen” means a screen whose width is less than 320 dp or (whatever the width) a screen in portrait mode. To make these requirements stick, I put the layout in Listing 1-11 in the app’s res/layout-w320dp-port folder.

Using the dp measurement, 160 dp represents one inch. So 320 dp is two inches. Indeed, a screen whose width is less than two inches is a very small screen.

To read more about the dp measurement, refer to Chapter 1 in Book IV.

Listing 1-11: A Layout for Small (or Narrow) Screens

<?xml version="1.0" encoding="utf-8"?>

<LinearLayout xmlns:android=

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

    android:orientation="vertical"

    android:layout_width="match_parent"

    android:layout_height="match_parent">

    <fragment class=

        "com.allmycode.frag.ComponentNamesFragment"

      android:id="@+id/component_names"

      android:layout_height="wrap_content"

      android:layout_width="match_parent"

      android:layout_weight="0" />

    <FrameLayout

      android:id="@+id/docs"

      android:layout_height="0px"

      android:layout_width="match_parent"

      android:layout_weight="1"

      android:background=

        "?android:attr/detailsElementBackground" />

</LinearLayout>

The file in Listing 1-11 must have the same name as the main activity’s layout file. (If you’re working directly with Listing 1-10, the file in Listing 1-11 is named main.xml.)

Listing 1-11 is very much like the code in Listing 1-1, but there are a few differences:

• In Listing 1-1, the overall layout’s orientation is horizontal; in Listing 1-11, the orientation is vertical.

  In Figure 1-1, the two fragments in the activity are side-by-side. But in Figure 1-5, one fragment is underneath the other.

• In Listing 1-1, both fragments have layout_weight set to 1. But in Listing 1-11, the ComponentNamesFragment has the layout_weight value set to 0.

  In Figure 1-1, both fragments expand to fill the screen. But in Figure 1-5, the ComponentNamesFragment doesn’t expand. (The lower fragment expands in Figure 1-5, but you don’t see the expansion because most of that lower fragment is blank.)

• After changing the layout_weight for the ComponentNamesFragment, you have to adjust the fragment’s layout_height values.

  In Listing 1-1, the fragments' layout sizes are match_parent and 0px. But in Listing 1-11, the ComponentNamesFragment has the layout_weight value set to 0. Accordingly, the ComponentNamesFragment takes up no more space than it requires on the screen. If you don’t describe this space requirement, the ComponentNamesFragment shrinks to nothing. To specify the space requirement, you make the layout_height of the ComponentNamesFragment be wrap_content.

With the changes that you make in this section’s steps, the user can turn the device sideways, upside-down, or whatever. When the user wants to see a web page, the app displays the page in a fragment or in an entire activity, whichever is best.