Introduction

The ZHeaderNavigationBar is a Euclid control included in the Fire Phone SDK that provides navigation and orientation within your app. Visually, this control is placed at the top of the screen.

Why Use a ZHeaderNavigationBar?

Apps designed for the Fire are meant to be full-screen experiences. These apps use a ZHeaderNavigationBar at the top of their activity layout instead of an Android title bar or Android ActionBar. A ZHeaderNavigationBar is tailored to the Fire experience and includes support for 3D glyphs and peek text. In your app design, replace an ActionBar or Android title bar with a ZHeaderNavigationBar.

Suggested Layout Placement for a ZHeaderNavigationBar

Use the following guidelines for a suggested layout, which places your ZHeaderNavigationBar above all other 3D content. This section also describes how to make content from the main panel scroll underneath your header and footer if you choose.

• Divide your layout into three sections: header containing a ZHeaderNavigationBar, main content, and an optional footer that can contain a ZTabBar or ZToolBar.
  The header and footer should have a separate ZShadowReceiver wrapping a ZContainer For the main content section, follow the standard recommendations for ZContainer discussed in Best Practices for Integrating Depth, Shadows, and Dynamic Perspective Sensor Effects.
• The ZShadowReceiver for the header should be the sibling, along with the main content ZShadowReceiver in your layout XML file.
  The dedicated ZShadowReceiver/ZContainer for the header and footer sections must not be contained within any other ZShadowReceiver/ZContainer.
• Use a FrameLayout or LinearLayout to wrap the three ZShadowReceivers.

The following XML shows an example of this type of layout. This layout maps the above guidelines as follows:

• The main content ZShadowReceiver contains a ListView.
• The header ZShadowReceiver contains the ZHeaderNavigationBar.
• The footer ZShadowReceiver contains a ZTabBar.

<FrameLayout>
    <!-- ZShadowReceiver for the main content.-->
    <com.amazon.euclid.widget.ZShadowReceiver
        android:layout_width="match_parent"
        android:layout_height="wrap_content" >

        <ListView .../>
        <!-- main page contents here -->
    </com.amazon.euclid.widget.ZShadowReceiver>

    <!-- Header ZShadowReceiver for the ZHeaderNavigationBar -->
    <com.amazon.euclid.widget.ZShadowReceiver
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        <!-- ZShadowReceiver should cast shadows on the screen -->
        euclid:shadowDepth="@euclid:dimen/globalLayerScreen"
        <!-- See below section on Setting a Background -->
        android:background="@euclid:drawable/translucent_background_dark" >

        <com.amazon.euclid.widget.ZContainer
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            <!-- Shadows should be "medium" only in the ZHeaderNavigationBar -->
            euclid:shadowMode="medium" >

            <com.amazon.euclid.widget.ZHeaderNavigationBar
                android:id="@+id/zheadernavigationbar"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                euclid:layout_depth="wrap_content" />
        </com.amazon.euclid.widget.ZContainer>
    </com.amazon.euclid.widget.ZShadowReceiver>

    <!-- Footer ZShadowReceiver for the ZTabBar/ZToolBar -->
    <com.amazon.euclid.widget.ZShadowReceiver
        android:layout_width="match_parent"
        android:layout_height="wrap_content"

        <com.amazon.euclid.widget.ZContainer
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            euclid:baseDepth="@euclid:dimen/globalLayerScreen" >

            <com.amazon.euclid.widget.ZTabBar
                android:id="@+id/ztabbar"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                euclid:layout_depth="wrap_content" />
        </com.amazon.euclid.widget.ZContainer>
    </com.amazon.euclid.widget.ZShadowReceiver>

</FrameLayout>

Configuring Shadow Effects for a ZHeaderNavigationBar

Configure the following settings to optimally display shadows cast by your ZHeaderNavigationBar:

• The parent ZShadowReceiver of the ZHeaderNavigationBar should set the shadowDepth attribute: euclid:shadowDepth="@euclid:dimen/globalLayerScreen"
• If you are using a Euclid Light theme, set the shadowMode attribute: euclid:shadowMode="medium"


Setting the Background of a ZHeaderNavigationBar

The Euclid API includes translucent_background_light and translucent_background_dark drawables. These two backgrounds are standard to display behind ZHeaderNavigationBars with Euclid Light or Dark themes, and both drawables are a single color with 95% opacity with a fully-opaque 2 pixel bottom border of a second color. You can also apply a custom header background by providing your own drawable to the ZShadowReceiver containing the ZHeaderNavigationBar.

If you want your shadows to appear to be casting onto the background from your ZHeaderNavigationBar, set a background on the ZShadowReceiver that wraps the ZHeaderNavigationBar, and set the ZShadowReceiver shadowDepth to be at the glass level (euclid:shadowDepth="@euclid:dimen/globalLayerScreen). This arrangement makes your shadows appear to be casting onto the background, which is drawn at glass-level:

<com.amazon.euclid.widget.ZShadowReceiver
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    euclid:shadowDepth="@euclid:dimen/globalLayerScreen"
    android:background="@euclid:drawable/translucent_background_dark" >
   <!-- for light theme, use translucent_background_light-->
    <com.amazon.euclid.widget.ZContainer
        android:layout_width="match_parent"
        android:layout_height="wrap_content" >
        <com.amazon.euclid.widget.ZHeaderNavigationBar
            android:id="@+id/zheadernavigationbar"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            euclid:layout_depth="wrap_content" />
    </com.amazon.euclid.widget.ZContainer>
</com.amazon.euclid.widget.ZShadowReceiver>

Applying a Widget-specific Theme to a ZHeaderNavigationBar

You can apply a custom theme to your ZHeaderNavigationBar to provide contrast against its parent ZShadowReceiver's background.

To change the ZHeaderNavigationBar theme in XML, use the euclid:widgetTheme attribute, as shown in the following example:

<com.amazon.euclid.widget.ZHeaderNavigationBar
    android:id="@+id/zheadernavigationbar"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    euclid:layout_depth="wrap_content"
    euclid:widgetTheme="@euclid:style/Theme.Euclid.Dark" />

Improving the Initial Start Time of a ZHeaderNavigationBar

A ZHeaderNavigationBar control has three associated glyphs:

• An Up navigation glyph
• Two ZImageButtons that each contain a glyph

The ZHeaderNavigationBar does not load these glyphs until their functionality is enabled. To improve the cold start time of your ZHeaderNavigationBar, do not enable the various glyph elements until they are needed.

Adding a Loading Progress Bar to Your Header

To add a loading progress bar to your header, wrap the ZContainer that contains your ZHeaderNavigationBar in a HeaderModeViewContainer. To have the container start with the progress bar visible, set the progressBarEnabled attribute to true, as shown in the following XML snippet:

<amazon.widget.HeaderModeViewContainer
    android:id="@+id/contextual_container"
    android:layout_width="match_parent"
    android:layout_height="@amazon:dimen/header_bar_height"
    amazon:progressBarEnabled="true">
    <com.amazon.euclid.widget.ZContainer
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        euclid:shadowMode="medium" >
        <com.amazon.euclid.widget.ZHeaderNavigationBar
            android:id="@+id/zheadernavigationbar"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            euclid:layout_depth="wrap_content"
            amazon:headerTitle="@string/zheader_bar_title"/>
    </com.amazon.euclid.widget.ZContainer>
</amazon.widget.HeaderModeViewContainer>

To toggle the progress bar in code, call setProgressBarEnabled(boolean) on the HeaderModeViewContainer:

HeaderModeViewContainer container = (HeaderModeViewContainer)findViewById(R.id.contextual_container);
container.setProgressBarEnabled(false);