Home > Devices > Fire Phone

Building an App that Includes a Custom Control

Introduction

This page describes the high-level process for incorporating a custom control into your app. The goal of this page is to walk you from beginning-to-end of the process used by the Fire Phone SDK custom control authoring tools so that you will understand the purpose of each tool and when to use the tool in your development process.

The scenario described in this topic uses a fictional ZReader app as an example. The ZReader app has two assets: a book and a page that a designer would need to create for the developer working on ZReader.

Building and Previewing Your Assets

The first step in creating a custom control is to build the assets for your control. An asset is a collection of attachment points, meshes, animations, state machines, and materials. You can preview your assets to see what they look like on a device using the ModelMan utility app.

To build and preview your assets:

  1. Build your assets using your 3D graphic design tool. You will need to bundle your assets as Visual Bundle (VBL) files. See Creating 3D Assets for details.
  2. Push your newly created VBL files to a Fire phone. See Setting up Your Development Environment for instructions.
  3. Preview your assets on a device to verify that they appear as expected. Use the ModelMan utility app to preview the appearance of all animations, state machines, and attachment points. See ModelMan for instructions.

Creating an App For Your Control

Create the app that incorporates your assets. For an example that uses Euclid, see the DynamicPerspectiveControls Sample App, which uses the sample app included in the SDK as an example to point out how to set up your app project in an IDE.

Writing the Java Code for your Assets

This section provides an introduction to the classes and methods that you will use when integrating your assets into your app.

Four parameters define how your assets appear and behave within your app:

  • ZStateMachines
  • Animations
  • Image hosts
  • Attachment points.

You can access all of these parameters programmatically from the ZSceneTree class. To access these parameters, you will need to obtain the correct ZSceneTree for your asset.

ZStateMachines

ZStateMachines have predefined states. For example, the book asset for ZReader has "Open" and "Closed" states. The ZStateMachine transitions through these states, playing the animation sequences that have been applied to the transition.

To get the ZStateMachine associated with your asset's ZSceneTree, call getStateMachine:

ZSceneTree_Object.getStateMachine(ZStateMachine_Name);

You can set the current state and the goal state, and the ZStateMachine will start transitioning from its current state to its goal state:

ZStateMachine_Object.setCurrentState(State_Name);
ZStateMachine_Object.setGoalState(State_Name);

Animations

Your asset can play animations while transitioning from one state to another. An example animation might be turning the pages of the book.

You can see if the current ZSceneTree has an animation by calling hasAnimation, and return animation names for the ZSceneTree using getAnimationName:

ZSceneTree_Object.hasAnimation(Animation_Name);
ZSceneTree_Object.getAnimationNames();

Image Host

The image host specifies the raw images used. Return an array of image host names from getImageHostNames, and then set the image using setImage:

ZSceneTree_Object.getImageHostNames();
ZSceneTree_Object.setImage(ImageHost_Name, ZTexture_Texture);

Attachment Points

Attachment points are nodes on a ZSceneTree to which you can attach another component.

In the context of ZReader, the book has attachment points for its pages.

You can retrieve an array of attachment point names or an array of attachment points:

ZSceneTree_Object.getAttachPointNames();
ZSceneTree_Object.getAttachPoints();

Creating Your Layout and Installing the APK to your Device

When you have a general idea of what you want your Java code to do, you can lay out the controls and other elements in your layout XML file. Once you have a valid layout, you will be able to build your code and install your APK to your device.

To create your layout and install your APK to a device:

  1. Copy the VBL file containing your assets to the res/raw folder for your app.
  2. Create an XML file for the layout for your activity. (In your IDE, the default layout XML file should be called main.xml.)
  3. Add a ZSceneView element to your layout, as shown in the following sample code:
    <?xml version="1.0" encoding="utf-8"?>
    <com.amazon.euclid.widget.ZShadowReceiver
         xmlns:android="http://schemas.android.com/apk/res/android"
         xmlns:amazon="http://schemas.android.com/apk/res/amazon"
         xmlns:euclid="http://schemas.android.com/apk/res/euclid"
         android:layout_width="match_parent"
         android:layout_height="match_parent">
    
         <LinearLayout android:layout_width="match_parent"
             android:layout_height="match_parent" android:paddingTop="50dp"
             android:orientation="vertical">
             <com.amazon.euclid.widget.ZContainer
                  android:layout_width="match_parent"
                  android:layout_height="wrap_content"
                  euclid:autoPadding="true">
    
                  <com.amazon.euclid.view.ZSceneView
                        android:id="@+id/model_book"
                        android:layout_width="match_parent"
                        android:layout_height="match_parent"
                        android:layout_gravity="top"
                        euclid:layout_depth="wrap_content"
                        euclid:scene="reader_book.scene"
                        euclid:vbl="@raw/reader_proto" />
    
              </com.amazon.euclid.widget.ZContainer>
          </LinearLayout>
    </com.amazon.euclid.widget.ZShadowReceiver>
    
    
  4. For each Z element, specify the layout_depth. ZSceneView is similar to an Android SceneView, but with more features. You typically place your asset inside of a ZSceneView.
  5. In your main activity Java file, add the following code to the onCreate() method to initialize the ZSceneView:
    ZSceneView mModelBook = (ZSceneView) findViewById(R.id.model_book);
    
  6. Build your code.
  7. Install the app to your device, and then launch app.