Home > Devices > Fire Phone

Implementing SidePanelLayout

Introduction

You can use side panels to provide extra functionality or information that does not need to reside on your app's main panel. For example, if your app plays audio and video in the center panel, you can use a side panel to provide advanced media settings.

About the SidePanel

A SidePanelLayout consists of left, right, and center view objects. The center, or main, view object remains visible until covered by one of the side view objects. A side panel is displayed when a user swipes inward from an edge or tilts the device. For example, to show the left view, the user swipes inward from the left edge or tilts the device to the right. To show the right view, the user swipes inward from the right edge or tilts the device to the left.

The SidePanelLayout provides access to the left and right panel through the SidePanel interface. An implementation of this interface for each panel can be retrieved from the SidePanelLayout.

SidePanelLayout Example

The following screen shot shows a left, center, and right panel. The left panel has a red background, the center panel has a white background, and the right panel has a blue background.

In this example, the center panel records information about the states of the left and right panels as they open and close. The left and right panels also record information about their own state.

Programming Guide

Amazon device apps are essentially Android apps with some added extensions. For more information about how to create your first Android app, see the tutorial in the documentation on the Android developer portal.

You can create an app for an Amazon device by using a variety of integrated development environments. We recommend that you use the Android Studio IDE.

The following sections discuss how to create the example app discussed above.

Preparing the Android Manifest

The Android manifest needs to be modified to include a <uses-library> tag for the EAC library. It should also be modified to use one of the Amazon themes.

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    ...
    <application android:theme="@amazon:style/Theme.Amazon.Light">
        <!-- could also be @amazon:style/Theme.Amazon.Dark -->

        <uses-library android:name="eaclibrary"/>
        ...
    </application>
</manifest>

Creating the XML Layout

The XML layout for this example nests three TextViews inside of a SidePanelLayout object. Each TextView is assigned an id that is used by the SidePanelLayout to assign a panel position of left, center, or right.

<amazon.widget.SidePanelLayout
   xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:amazon="http://schemas.android.com/apk/res/amazon"
   android:id="@+id/side_panel_layout"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
   amazon:content="@+id/side_panel_layout_content_panel"
   amazon:leftPanel="@+id/side_panel_layout_left_panel"
   amazon:rightPanel="@+id/side_panel_layout_right_panel">

   <TextView
      android:id="@id/side_panel_layout_left_panel"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      android:text="@string/left_panel"
      android:background="#ff0000"/> <!-- background is red -->

    <TextView android:id="@id/side_panel_layout_content_panel"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      android:text="@string/content_panel"/>

    <TextView android:id="@id/side_panel_layout_right_panel"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      android:text="@string/right_panel"
      android:background="#0000ff"/> <!-- background is blue -->

 </amazon.widget.sidepanellayout>

The strings.xml file defines the following strings:

<string name="left_panel">This is the left panel</string>
<string name="content_panel">This is the content panel</string>
<string name="right_panel">This is the right panel</string>

Implementing the Example Class

The following sections discuss how to implement the Java class for this example.

Importing Packages

To follow this example, you must import the following packages:

import java.util.Date;
import amazon.widget.SidePanel;
import amazon.widget.SidePanel.PanelListener;
import amazon.widget.SidePanelLayout;
import android.os.Bundle;
import android.app.Activity;
import android.view.Window;
import android.widget.TextView;

Class Overview

The class under discussion extends android.app.Activity and includes a private inner class that is an implementation of the amazon.widget.SidePanel.PanelListener interface, as well as a standard Android onCreate(Bundle) method.

Initializing the Activity with onCreate(Bundle)

Within the onCreate(Bundle) method, we perform several groups of steps in order to get our activity ready for use. We inflate the layout from XML, get references to the inflated TextView objects for later use, and get references to the left and right SidePanels and set listeners on them. Inflating the XML layout and getting references to the inflated objects are not discussed in this guide.

Setting Listeners on the Left and Right SidePanels

To set listeners on the left and right SidePanels, we use a reference to the main SidePanelLayout to retrieve the appropriate SidePanel, then instantiate a new listener class and add it as a listener to the SidePanel.

sidePanelLayout.getLeftPanel().addListener(new MySidePanelListener(LEFT_PANEL));
sidePanelLayout.getRightPanel().addListener(new MySidePanelListener(RIGHT_PANEL));

MySidePanelListener Inner Class

MySidePanelListener is an implementation of the amazon.widget.SidePanel.PanelListener interface. When instantiated, it receives the name of the panel to which it is attached and keeps track of this name. It sends log messages to the left, center, and right panels as appropriate when certain panel activities are detected.

Full Class Listing

The following code shows the entire class in context.

public class MainActivity extends Activity {

	public static final String LEFT_PANEL = "Left panel";
	public static final String RIGHT_PANEL = "Right panel";
	private TextView mLeftPanel;
	private TextView mRightPanel;
	private TextView mContentPanel;
	
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		// hide Android title bar
		requestWindowFeature(Window.FEATURE_NO_TITLE);
		
		// inflate view from XML layout
		setContentView(R.layout.activity_main);

		// get a reference to the SidePanelLayout
		SidePanelLayout sidePanelLayout =
(SidePanelLayout) findViewById(R.id.side_panel_layout);

		// assign TextView references to instance variables
		mLeftPanel =
(TextView) findViewById(R.id.side_panel_layout_left_panel);
		mRightPanel =
(TextView) findViewById(R.id.side_panel_layout_right_panel);
		mContentPanel =
(TextView) findViewById(R.id.side_panel_layout_content_panel);
		
		// get a reference to the left panel and add a listener
		sidePanelLayout.getLeftPanel().addListener(
new MySidePanelListener(LEFT_PANEL));

		// get a reference to the right panel and add a listener
		sidePanelLayout.getRightPanel().addListener(
new MySidePanelListener(RIGHT_PANEL));
	}
	
	// inner class implementing the PanelListener interface
	private class MySidePanelListener implements PanelListener {
		private String mPanelName;
		
		// constructor
		public MySidePanelListener(String panelName) {
			// remember the name of the panel
			mPanelName = panelName;
		}
		
		// following are methods to log the different
		// activities that can take place
		@Override
		public void onClosed(SidePanel panel) {
			log(mPanelName, "closed");
		}

		@Override
		public void onClosing(SidePanel panel) {
			log(mPanelName, "closing");
		}

		@Override
		public void onOpened(SidePanel panel) {
			log(mPanelName, "opened");
		}

		@Override
		public void onOpening(SidePanel panel) {
			log(mPanelName, "opening");
		}

		@Override
		public void onPeeked(SidePanel panel) {
			log(mPanelName, "peeked");
		}

		@Override
		public void onPeeking(SidePanel panel) {
			log(mPanelName, "peeking");
		}
		
		// helper method to log panel activities to the appropriate panel
		private void log(String panelName, String action) {
			Date now = new Date();
			String logText = "\n" + panelName + " " + action + " at " + now;
			mContentPanel.append(logText);
			if (panelName.equals(LEFT_PANEL)) {
				mLeftPanel.append(logText);
			} else if (panelName.equals(RIGHT_PANEL)) {
				mRightPanel.append(logText);
			}
		}
        }
}

The SidePanel Simulator

If you don't have a Fire phone you can use the simulator to test your SidePanel implementations.