Table of Contents
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:
- 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.
- Push your newly created VBL files to a Fire phone. See Setting up Your Development Environment for instructions.
- Preview your assets on a device to verify that they appear as expected. Use theModelMan for instructions. utility app to preview the appearance of all animations, state machines, and attachment points. See
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:
- 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 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
You can set the current state and the goal state, and the
ZStateMachine will start transitioning from its current state to its goal state:
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
The image host specifies the raw images used. Return an array of image host names from
and then set the image using
ZSceneTree_Object.getImageHostNames(); ZSceneTree_Object.setImage(ImageHost_Name, ZTexture_Texture);
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:
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:
- Copy the VBL file containing your assets to the
res/rawfolder for your app.
- Create an XML file for the layout for your activity. (In your IDE, the default layout XML file should be called main.xml.)
- Add a
ZSceneViewelement 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>
- For each Z element, specify the
ZSceneViewis similar to an Android
SceneView, but with more features. You typically place your asset inside of a
- In your main activity Java file, add the following code to the
onCreate()method to initialize the
ZSceneView mModelBook = (ZSceneView) findViewById(R.id.model_book);
- Build your code.
- Install the app to your device, and then launch app.