Home > Devices > Fire Phone

Incorporating Glyphs into Your App

Introduction

A glyph is a 3D model that can be attached to some Euclid controls. Glyphs can enhance the user experience of interacting with the controls in your app.

This page discusses the basics of working with glyphs in your app.

Note: If you plan to localize your app, be sure to define your asset strings, such as VBL names and scene names, in a separate XML file that is not localized. If your asset strings are translated into other languages, your app will not be able to find those assets.

Available Built-in system Visual Bundles (VBLs) and Scenes

The Fire Phone SDK includes a set of system-level VBLs that are built into its platform. You can view unzipped contents of the standard available VBLs by viewing the contents of the following directory on your device:

/system/euclid/vbls

You can browse most VBL files.  To view the scenes available within an app-specific VBL file, you must unzip that VBL file before viewing the included files.

The Fire Phone SDK includes the following built-in glyphs, which represent standard UI elements for many apps and are accessible through a string resource in the Euclid package. These glyphs are resources that can be found under euclid.R.string.*.

The following table lists the available built-in glyphs and shows their Android equivalents for easy mapping:

String Resource Name Description Fire Image Android Name(s) Android Image
glyph_volume_muted Scene name of the built-in glyph that represents muted audio.
ic_action_volume_muted
glyph_volume_on Scene name of the built-in glyph that represents represents audio playback.
ic_action_volume_on

glyph_settings

Scene name of the built-in glyph that represents settings.
ic_action_settings

 

glyph_warning

Scene name of the built-in glyph that represents an alert.
ic_action_warning
glyph_error Scene name of the built-in glyph that represents an error.
ic_action_error
glyph_next_item Scene name of the built-in glyph that represents navigating to the next item.
ic_action_next_item
glyph_previous_item Scene name of the built-in glyph that represents navigating to the previous item.
ic_action_previous_item
glyph_call Scene name of the built-in glyph that represents a phone call.
ic_action_call
glyph_camera Scene name of the built-in glyph that represents camera access.
ic_action_camera
glyph_search Scene name of the built-in glyph that represents search functionality.
ic_action_search
glyph_print Scene name of the built-in glyph that represents printing functionality.
N/A N/A
glyph_not_secure Scene name of the built-in glyph that represents unlocked or unsecured content.
ic_action_not_secure

glyph_secure

Scene name of the built-in glyph that represents locked or secured content.
ic_action_secure
glyph_zoom_in Scene name of the built-in glyph that represents the functionality for zooming in on content.
N/A N/A
glyph_zoom_out Scene name of the built-in glyph that represents the functionality for zooming out on content.
N/A N/A
glyph_star Scene name of the built-in glyph that represents favorites or ratings.
ic_action_important
glyph_discard
Scene name of the built-in glyph that represents deleting an item.
ic_action_discard
glyph_save
Scene name of the built-in glyph that represents saving an item.
ic_action_save
glyph_send
Scene name of the built-in glyph that represents sending or submitting an item.
ic_action_send_now
glyph_new
Scene name of the built-in glyph that represents adding an item.
ic_action_new
glyph_remove Scene name of the built-in glyph that represents removing an item.

ic_action_remove

ic_action_cancel


glyph_cancel Scene name of the built-in glyph that represents cancelling an item or operation.

ic_action_remove

ic_action_cancel


glyph_recent Scene name of the built-in glyph that represents displaying recent items.
N/A N/A
glyph_edit Scene name of the built-in glyph that represents editing or modifying an item.
ic_action_edit
glyph_share Scene name of the built-in glyph that represents sharing items.
ic_action_share
glyph_refresh Scene name of the built-in glyph that represents refreshing an item or list of items.
ic_action_refresh
glyph_collapse Scene name of the built-in glyph that represents collapsing a list of items.
ic_action_collapse
glyph_expand Scene name of the built-in glyph that represents expanding a list of items.
ic_action_expand
glyph_show_more Scene name of the built-in glyph that represents displaying additional items.
N/A N/A
glyph_accept Scene name of the built-in glyph that represents accepting an item. ic_action_accept
glyph_download Scene name of the built-in glyph that represents downloading functionality.
ic_action_download
glyph_download_done Scene name of the built-in glyph that represents a successfully completed download.
N/A N/A
glyph_upload Scene name of the built-in glyph that represents upload functionality.
ic_action_upload
glyph_person Scene name of the built-in glyph that represents one or more contacts.
ic_action_person
glyph_add_person Scene name of the built-in glyph that represents adding a contact.
ic_action_add_person
glyph_group Scene name of the built-in glyph that represents a group of contacts.
ic_action_group

Euclid Control Support for Glyphs

Five Euclid controls directly use glyphs:

  • ZImageButton
  • ZSceneView
  • ZTabBar
  • ZToggleButton
  • ZToolBar

The following controls also can use glyphs, but they do so through the use of a ZImageButton:

  • ZHeaderNavigationBar
  • ZMediaController
  • ZCaptionedIconButton

The next sections on this page describe common use cases for adding glyphs to these Euclid controls.

Displaying Glyphs on Euclid Controls

This section provides code snippet examples for various use cases that incorporate glyphs into an app.

Display a built-in glyph on a simple Euclid control

To specify a specific 3D scene for a control to display, add the name of VBL file (such as "glyphs") and the scene to be displayed to your layout XML file as attributes of your control.

For example, the following XML specifies that a ZImageButton control play a scene from the built-in glyphs.vbl file called "glyph_new":

<com.amazon.euclid.widget.ZImageButton
    android:id="@+id/zbutton2"
    android:layout_width="50dp"
    android:layout_height="wrap_content"
    euclid:layout_depth="wrap_content"
    android:onClick="onClick"
    euclid:vbl="glyphs"
    euclid:scene="@euclid:string/glyph_new"/>

Display a built-in glyph on a ZTabBarItem or ZToolBarItem

Specifying a glyph for a ZTabBarItem or ZToolBarItem is similar to other controls, but with a slight change in syntax.

In your layout XML, use the iconScene attribute instead of the scene attribute to specify the glyph. This example sets the ZTabBarItem glyph to "glyph_call".

<com.amazon.euclid.widget.ZTabBarItem
    euclid:vbl="glyphs"
    euclid:iconScene="@euclid:string/glyph_call"
   ...

Display a custom glyph 3D on a 3D control

You can also associate a custom 3D scene from a non-built-in VBL with your control.

To specify a custom 3D scene for your control to play:

  1. Copy your VBL file into the res/raw folder of your app.
    Warnng:Place your VBL files directly into the res/raw folder. Do not create subfolders under raw, or the resource IDs for the VBLs will not be generated correctly.
  2. Add the VBL and scene location to the XML attributes for your control.

    For example, the following XML specifies that a ZImageButton control plays the "glyph_myglyph" scene from a custom "myvbls" file:
<com.amazon.euclid.widget.ZImageButton
    android:id="@+id/zbutton1"
    android:layout_width="50dp"
    android:layout_height="wrap_content"
    euclid:layout_depth="wrap_content"
    android:onClick="onClick"
    euclid:vbl="@raw/myvbls"
    euclid:scene="glyph_myglyph.scene"/>

Display a custom glyph independent of a 3D control

If you want to display a custom glyph with no added behavior, use a ZSceneView, and set your VBL and scene attributes for the ZSceneView to point to the glyph in your XML or in your Java code. You can also set the glyph explicitly by calling the setScene method on the ZSceneViewDelegate.

Programmatically set a glyph for a ZImageButton

The ZImageButton control supports using a resource handle (via a ZResourceHandle) to specify a 3D glyph to visually represent the button. ZResourceHandles are opaque handles to 3D scenes that can be only be retrieved through the Euclid ZVisualBundleManager class:

  • Use the getBuiltInVBLResource method to specify built-in assets.
  • Use the registerVisualBundleFromResource followed by the getResource methods to specify custom assets. (First register your VBL, then retrieve a resource handle from that registered VBL.)

The following example sets the glyph on a ZImageButton to be the "glyph_new" scene from the built-in glyphs.vbl file.

ZResourceHandle handle;

ZImageButton button = (ZImageButton)findViewById(R.id.button1);

try { handle = ZVisualBundleManager.getBuiltInVBLResource(context, "glyphs", getResources().getString(euclid.R.string.glyph_new); }
  catch (IOException e) { Log.e("TestApp", "Visual resource not found", e); }

button.getDelegate().setGlyph(handle);]]>

Programmatically set a glyph for a ZTabBarItem, ZToolBarItem, or ZMediaController

Some controls allow you to programmatically set a glyph via an explicit reference. For these controls, specify a built-in VBL name or a custom VBL ID and a scene name from inside that VBL:

  • ZTabBarItem/ZToolBarItem: Sets the 3D glyph displayed by the ZTabBarItem or ZToolBarItem. See the constructor reference documentation for more details.
  • ZMediaController: Sets the 3D glyphs for secondary buttons (ZImageButtons) through methods that take a VBL ID and scene name and internally use a resource handle to set the glyph.

In this example, the app has a VBL file named myvbls.vbl in its res/raw directory, and the VBL contains a scene named "glyph_myglyph.scene":

ZMediaController media = (ZMediaController)findViewById(R.id.media1);
media.setSecondaryButtonOne(R.raw.myvbls, glyph_myglyph.scene, clickListener);]]>

Note that if you are setting the glyph to a built-in asset, you need to use a ZResourceHandle. If you are setting the glyph to a custom asset, use a Resource ID and string name.

Set the color of a glyph

When a glyph is loaded into any of these controls, the glyph color is automatically set to the color specified by the current theme of the activity (Euclid Light or Euclid Dark). Avoid loading a glyph into a ZSceneView because the glyph will not be automatically colored and will stay its default color. If you need to manually set the glyph color, retrieve the ZSceneTree from the ZSceneView that has loaded the glyph, then call setColor(“Color_group”, color) on the scene tree to set the color, where "Color_group" is the name of the material that you want to set the color on.

Controls that use glyphs via a ZImageButton (for example, ZHeaderNavigationBar), get the same automatic coloring behavior as the ZImageButton.

Customizing a Menu or Bar-style Control from XML

The Dynamic Perspective UI includes three compound controls that incorporate glyphs and can be used for navigation or a menu within your app:

  • ZHeaderNavigationBar
  • ZTabBar
  • ZToolBar

The following table gives an overview of the components in these controls and when to use each control type:

Control Included components Use case
ZHeaderNavigationBar
  • Navigation control
  • Title
  • Subtitle
  • Navigation text
  • Action buttons (2)
Place a ZHeaderNavigationBar at the top of your activity to add a standardized set of navigation widgets in a context that users are familiar with. Set the Action buttons to trigger commonly used app actions, such as "Search" or "Add to Favorites".
ZTabBar
  • Up to four ZTabBarItems in portrait mode.
  • Up to six ZTabBarItems in landscape mode.
Place a ZTabBar at the bottom of your activity to add a tabbed navigation layout, such as in a phone app that includes tabs, for recent calls, contacts, keypad, and voicemail. Tabs remain selected until a user selects a different tab.
ZToolBar
  • Up to four ZToolBarItems in portrait mode.
  • Up to six ZToolBarItems in landscape mode.
Place a ZToolBarItem at the bottom of your activity to add a navigation toolbar to perform actions such as navigating forward or backward in an activity sequence. Toolbar items do not maintain a selected state once a user makes a selection.

Updating the Hosted Items in a Menu or Bar Control

Updating the hosted items in a menu or bar control works similarly with the ZHeaderNavigationBar, ZTabBar, and ZToolBar controls. The following high-level procedure outlines the steps in setting up the code for your menu or bar control:

  1. Create your menu XML file.
  2. Create your string resource definition file.
  3. Inflate the menu XML.

Create your menu XML file

A menu XML file defines the content of the menu or bar control. Create this file in your res/menu folder.

The following example shows a res/menu/menu.xml file with two menu item elements that correspond to the two action buttons in a ZHeaderNavigationBar:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:id="@+id/menu_item1"
        android:title="@string/zheader_action_1_title"
        android:icon="@string/zheader_action_1_scene"
    />
    <item
        android:id="@+id/menu_item2"
        android:title="@string/zheader_action_2_title"
        android:icon="@string/zheader_action_2_scene"
    />
</menu>

Most of the time, the number of <item> elements in your XML should equal the number of items hosted by your control:

  • Each menu item in the menu XML represents one hosted item, such as an action button, a ZTabBarItem, or a ZToolBarItem.
  • Keep the following guidelines in mind for a ZHeaderNavigationBar:
    • If the menu XML contains more than two menu items, the first two menu items will be read and turned into action buttons.
    • If your ZHeaderNavigationBar has more action buttons than the menu XML has menu items (for example, two action buttons and one menu item), only action buttons with a corresponding menu item will be displayed. Any remaining action buttons will be set to GONE.
  • Keep the following guidelines in mind for a ZTabBar or a ZToolBar:
    • Both of these controls can host a maximum of four items in portrait mode; six items in landscape mode.
    • You can override this limit by subclassing the control to create a custom version of the control.
    • For ZToolBar, any hosted items beyond the maximum limit will appear in a newly created overflow menu.
    • ZTabBar cannot show more than the maximum number of items.

To update the action buttons based on a menu, assign the icon attribute of menu item to a string resource using the following format:

<item  android:id = "@+id/[Menu_Item_ID]" android:icon="@string/[String_Resource_ID]" />

Create your string resource definition file

A second XML file defines the string resources that will be used by your menu XML. Create this file in your res/values folder.

The following code example shows a sample res/values/strings.xml file, which defines two scenes to be associated with the Action buttons of the previously shown ZHeaderNavigationBar:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="zheader_action_1_scene">:glyphs:glyph_add</string> <!-- this uses built-in vbl file named glyphs -->
    <string name="zheader_action_2_scene">myvbls::ic_add_amazon_3d_new.scene</string> <!--this uses local vbl file named myvbls, located in res/raw folder-->
    <string name="zheader_action_1_title>Action 1</string>
    <string name="zheader_action_2_title>Action 2</string>
</resources>

For each defined menu icon attribute that is associated with a string in the menu XML file, for example, <item android:id="@+id/menu_item1" android:icon="@string/zheader_action_1_scene" />, define a string element that specifies which glyph scene to associate with the action button. This glyph can come from either one of the built in VBL files or a custom VBL file that resides locally on your system in the /res/raw folder.

String resource elements have the following format in the strings XML file:

 <string name = "Resource_Name" >Custom_VBL :Built-in_VBL:Scene </string>

Each string element has the following characteristics:

  • The name attribute of the string must match the name specified in the "@string/[Name]" menu item that was defined for the icon.
  • The string resource must specify the VBL containing the scene.
  • The string resource must name the scene to use.
  • The two VBL and scene IDs are delimited by colon characters (:).
  • The VBL and scene names cannot contain colon characters (:).

If you are using a built-in VBL, leave the spot for the custom VBL blank, and if you are using a custom VBL, leave the spot for the built-in VBL blank.

The following table gives examples of the string resource syntax used for a built-in or custom VBL:

Usage String resource format String element syntax
Use the glyph_search scene from the built-in glyphs VBL.
  • VBL file in res/raw folder = empty
  • Built-in VBL name = glyphs
  • Scene name = glyph_search.scene
<string name="asset_string">:glyphs:glyph_search</string>
Use the glyph_dialer.scene from the local custom tabbar VBL.
  • VBL file in res/raw folder = tabbar
  • Built-in VBL name = empty
  • Scene name = glyph_dialer.scene
<string name="asset_string">tabbar::glyph_dialer.scene</string>

Inflate the menu XML

At the point that you want to update the content of your bar or menu, call the appropriate method for your control type:

  • For a ZHeaderNavigationBar, call the setActionsMenu method to update the Action buttons according to the menu XML.
  • For a ZTabBar or ZToolBar, call the Inflate method to inflate the control from the menu XML.

Both methods take the menu resource ID as its parameter. The following code snippet inflates a ZTabBar using the menu XML:

ZTabBar tabbar = (ZTabBar)findViewById(R.id.tabbar1);
tabbar.inflate(R.menu.mymenu);

Updating a Glyph via State Change

You can update the glyph displayed by a ZImageButton upon a state change. ZImageButton uses the euclid:src attribute to update a glyph. The euclid:src attribute is similar to the android:src attribute, which can point to a stateful drawable in XML; however, euclid:src changes glyphs instead of drawables based on state.

To update the glyph displayed by a ZImageButton on a state change:

  1. Define your string resources in an XML file in your res/values folder, as shown in the following example. The string attribute format is the same as described in Create your string resource definition file:
    <resources>
        <string name="zimagebutton_selector1">tabbar::glyph_dialer.scene</string>
        <string name="zimagebutton_selector2">:glyphs:glyph_camera</string>
    </resources>
    
  2. In your xml folder, create an XML file that defines your glyph selections. The following example shows a glyph_selector.xml file that displays the "glyph_dialer.scene" when the ZImageButton is in a pressed state:
    <selector xmlns:android="http://schemas.android.com/apk/res/android">
        <item android:state_pressed="true"
            android:drawable="@string/zimagebutton_selector1" />
        <item android:drawable="@string/zimagebutton_selector2" />
    <selector />
    
  3. Reference your glyph selector file in the layout XML for your ZImageButton:
    <com.amazon.euclid.widget.ZImageButton
        android:layout_width="100dp"
        android:layout_height="100dp"
        euclid:layout_depth="wrap_content"
        euclid:src="@xml/glyph_selector"/>
    

    Note: If you use both the euclid:src attribute and the euclid:vbl and euclid:scene attribute combination, euclid:src overwrites the scenes set by the other two attributes.