GDK Guide for Building Glass Apps

Google Glass Development Kit
Developer Zone

Glass Development Kit
The Glass Development Kit (GDK) is an add-on to the Android SDK that lets you build
Glassware that runs directly on Glass.

Unlike the Mirror API, Glassware built with the GDK runs on Glass itself, allowing
access to low-level hardware features.

For Android experts
If you're comfortable with Android, here's all you need to know:
Get the Android 4.0.3 (API 15) SDK and Glass Development Kit Sneak Peek add-on from
the Android SDK Manager.
On Glass, turn on USB debugging (Settings > Device Info > Turn on debug).
Import some GDK samples with the File > New Project > Android Sample Project menu.

When you're ready to create a project for your own Glassware, use these settings:
Minimum and Target SDK Versions: 15 (There is only one Glass version, so
minimum and target SDK are the same.)
Compile with: Glass Development Kit Sneak Peek
Theme: None (This allows the Glass theme to be applied.)
Head on over to the developer guides for more learning.

For Android beginners
We recommend starting with the Building Your First App training class at the Android
developers site and then building a few simple Android apps before building GDK
Glassware.
Setting up the development environment
We recommend installing the ADT Bundle for easier development. The rest of these
steps assume you have this installed.
Click Window > Android SDK Manager.
Install the SDK Platform and Google GDK Sneak Peek for Android 4.0.3 (API 15).

Everything else is optional.
On Glass, go to Settings > Device Info > Turn on debug to enable adb, which allows
your development system to communicate with Glass.
Connect Glass to your development system and confirm that it's detected by clicking
Window > Open Perspective > DDMS and verifying Glass appears in the Devices tab.

GDK Sneak Peek
User interface
The GDK offers different options to build the right UI for your Glassware. This section
goes over what they are, when to use each, and how to build them.

Integrate rich content into the timeline
Live cards display frequently updated information to the left of the Glass clock. Options
range from simple text and images to full-blown 3D graphics.

Settings

 Present/Future

Home

Past 

When to use live cards
When using live cards, the timeline still consumes some user input, so live cards
don't support as many types of input features as an immersion. For example,
swiping forward or backward on a live card navigates the timeline instead acting on
the live card itself.
However, live cards have access to many of the same features an immersion does,
such as sensor or GPS data. In general, use live cards when:
You want a limited window into an immersion. Live cards can display summary
information and let users launch immersions if they want to do more.
You require a good amount of control over how to display information but don't
require much input capabilities.
Your information needs to be in the live section of the timeline.

When to use immersions
Glass displays immersions outside the context of the timeline, so they do not have the
user input constraints that cards do. However, in most cases, live cards or static cards
offer enough features and are easier to build. Only use immersions if you require extra
control.

In general, use immersions when:
•You want to take precedence over the timeline and display a UI outside of its context.
•You want to process all user input.
•You require prolonged user attention, such as for a game.

Choose an option
You can use one or all of the UI options in your Glassware. The following table
lays out your options and the benefits of each.

Appears in the
timeline

Access to user input

Control over user
interface

Major uses

No, must be in the
form of a Card

Information display
without user
interaction

Static Cards

Yes

No

Live Cards

Yes

Yes, but timeline takes
Yes, no restrictions
precedence

Rich and live content
with low user
interaction

Immersions

No


Rich and live content
with high user
interaction


Glass theme and UI widgets
The GDK provides a common theme and widgets to let you build UIs that look
consistent with the rest of the Glass platform.
Applying the Glass theme
Glass applies a standard theme to your Glassware, so it stays consistent with the rest
of the user interface. The theme has the following characteristics:
•Uses Roboto typeface
•Displays activities full-screen with no status bar or action bar
•Applies solid, black background
To apply the Glass theme, don't declare a theme in your Android Manifest.
<resources>
<style name="CustomTheme" parent="@android:style/Theme.DeviceDefault">

</style>
</resources>

Creating Glass-styled cards
The Card class creates well-formed cards given a set of properties. You can use a card
wherever you can a view.
A Card has the following properties:
•Main body text
•Left-aligned footer
•Right-aligned footer for a timestamp
•One image for the card's background or multiple images displayed on the left side of the
card
To create and use a Card object:
1. Set properties of the card.
2. Call Card.toView() to convert the card to an Android view.
3. Use the view in your activities, layouts, or in a CardScrollView.

// Create a card with some simple text and a footer.
Card card1 = new Card(context);
card1.setText("This card has a footer.");
card1.setInfo("I'm the footer!");
View card1View = card1.toView();
// Create a card with a full-screen background image.
card2.setText("This card has a puppy background image.");
card2.setInfo("How can you resist?");
card2.setFullScreenImages(true);
card2.addImage(R.drawable.puppy_bg);
// Create a card with multiple images displayed as a mosaic.
card3.setText("This card has a mosaic of puppies.");
card3.setInfo("Aren't they precious?");
card3.addImage(R.drawable.puppy_small_1);

Creating scrolling cards in activities
The Glass display and touchpad are great for displaying swipable
cards, like in the Glass timeline. If you're building an activity, you
can create the same type of effect with the CardScrollView widget.
Implement a CardScrollAdapter to supply cards to the
CardScrollView. You can build a standard view hierarchy yourself or
use the Card class.
Create a CardScrollView that uses the CardScrollAdapter as a supply
for cards.
Set your activity's content view to be the CardScrollView or display
the CardScrollView in a layout.

public class CardScrollActivity extends Activity {
private List<Card> mCards;
private CardScrollView mCardScrollView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
createCards();

}

mCardScrollView = new CardScrollView(this);
ExampleCardScrollAdapter adapter = new ExampleCardScrollAdapter();
mCardScrollView.setAdapter(adapter);
mCardScrollView.activate();
setContentView(mCardScrollView);

private void createCards() {
mCards = new ArrayList<Card>();
Card card;
card = new Card(this);
card.setText("This card has a footer.");
card.setInfo("I'm the footer!");
mCards.add(card);

card.setText("This card has a puppy background image.");
card.setInfo("How can you resist?");
card.setFullScreenImages(true);
card.addImage(R.drawable.puppy_bg);
mCards.add(card);
card.setText("This card has a mosaic of puppies.");
card.setInfo("Aren't they precious?");
card.addImage(R.drawable.puppy_small_1);
mCards.add(card);
}

private class ExampleCardScrollAdapter extends CardScrollAdapter {
@Override
public int findIdPosition(Object id) {
return -1;
}
@Override
public int findItemPosition(Object item) {
return mCards.indexOf(item);
}

@Override
public int getCount() {
return mCards.size();
}
@Override
public Object getItem(int position) {
return mCards.get(position);
}
@Override
public View getView(int position, View convertView, ViewGroup parent) {
return mCards.get(position).toView();
}
}

Live Cards
Live cards appear in the present and future section of the timeline and display
information that is relevant at the current time.
You can render live cards with low frequency, which updates the card once every few
seconds, or with high frequency, which updates the card many times a second.

Live card architecture
Live cards require a long running context to own them for the entire time that they
are visible, so manage them in a background service.
You can then publish a live card as soon as the service starts or in response to other
events that the service monitors.

When the live card is no longer relevant, destroy the service to stop rendering.

Low-Frequency Rendering
Low-frequency rendering is limited to a small set of Android views and can only
update the display once every few seconds.
It's a simple way to create live cards with simple content that doesn't require
constant rendering.

High Frequency Rendering
High frequency rendering gives you access to most of the Android rendering options.
It's more involved than low-frequency rendering, but gives you more features.

Creating low-frequency live cards
Low frequency rendering requires a UI supplied by a RemoteView.
that supports the following subset of Android layouts and views:
FrameLayout
LinearLayout
RelativeLayout
GridLayout
AdapterViewFlipper
AnalogClock
Button
Chronometer
GridView
ImageButton
ImageView
ListView
ProgressBar
StackView
TextView
ViewFlipper

Use low frequency rendering when:
You only require the standard Android view APIs and not more advanced rendering.
You only require relatively infrequent updates (a few seconds between refreshes).
Keep in mind:
Live cards must always have a PendingIntent declared with setAction() for the timeline
to publish the card.

To make changes to a card after publishing, call setViews() on the card with the updated
layout before publishing again.

// Cached instance of the LiveCard created by the publishCard() method.
private LiveCard mLiveCard;
private void publishCard(Context context) {
if (mLiveCard == null) {
String cardId = "my_card";
TimelineManager tm = TimelineManager.from(context);
mLiveCard = tm.getLiveCard(cardId);
mLiveCard.setViews(new RemoteViews(context.getPackageName(),
R.layout.card_text));
Intent intent = new Intent(context, EntryActivity.class);
mLiveCard.setAction(PendingIntent.getActivity(context, 0,
intent, 0));
mLiveCard.publish();
} else {
// Card is already published.
return;
}
}
private void unpublishCard(Context context) {
if (mLiveCard != null) {
mLiveCard.unpublish();
mLiveCard = null;
}
}

Creating high-frequency live cards
High frequency rendering lets you draw directly on the backing Surface of the live card.
This rendering is more flexible and lets you use all of Android's graphics options.
Use high frequency rendering when:
You need to update the live card frequently (many times a second).
You need flexibility in what you can render. RemoteView only supports rendering a
layout, but direct rendering let you use any graphics option in the Android framework.
Keep in mind:
You should create a background service to render on the live card's surface.
Use the surfaceCreated() and surfaceDestroyed() methods to start and stop your
rendering logic when the card is displayed or hidden.
The surface holder's callback methods are not invoked on the main UI thread.
Live cards must always have a PendingIntent declared with setAction()

Displaying live cards immediately
By default, Glass publishes live cards to the timeline silently. Users have to navigate to
the active section of the timeline to see it.
If you want Glass to automatically jump to the live card after publishing:
Call LiveCard.setNonSilent(true).
Call LiveCard.publish().
LiveCard liveCard;
// ...
liveCard.setNonSilent(true);
liveCard.publish();
This is often useful when the main user interface is a live card and not an activity.

Creating and displaying a menu
To display a menu for a live card, you create an activity to display the menu for the
card and to handle user selection events.
The activity can then do things such as stop the rendering of the live card or start
other activities or services to do other tasks.

Creating menu resources
Creating menu resources is the same as on the Android platform, but follow these
guidelines for Glass:

For each menu item, provide a 50 × 50 pixel menu item icon. The menu icon must be
white in color on a transparent background. See the Glass menu item icons for an
example or to download them for your own use.
Use a short name that describes the action and is in title case. An imperative verb works
well (for example, Share or Reply all).
Glass does not display live cards without a menu item. At the very least, provide a Stop
menu item, so users can remove the live card from the timeline.
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item
android:id="@+id/menu_item_1"
android:title="@string/Menu_Item_1"

android:icon="@drawable/menu_item_1_icon" /> 
</menu>

Creating an activity to handle menu callbacks
You must define a menu activity that your live card invokes when users tap on it.
Override the following Activity callback methods to properly create, show, and dismiss
menus in your menu activity:
1. onCreateOptionsMenu() inflates the XML menu resource.
2. onResume() shows the menu when the activity is in focus.
3. onPrepareOptionsMenu() shows or hides menu items if required. For example, you
can show different menu items based on what users are doing. For example, you can
show different menu items based on some contextual data.
4. onOptionsItemSelected() handles user selection.
5. onOptionsMenuClosed() to finish the activity, so that it no longer appears over the live
card. You must finish the activity here so it is properly finished when the menu is
closed by a selection or by a swipe down.

Making the menu activity transparent
To have the menu activity overlay over the live card:
Create a res/values/styles.xml file and declare a style that makes the activity's background transparent:
<resources>
<style name="MenuTheme" parent="@android:style/Theme.DeviceDefault">
<item name="android:windowBackground">@android:color/transparent</item>
<item name="android:colorBackgroundCacheHint">@null</item>
<item name="android:windowIsTranslucent">true</item>
<item name="android:windowAnimationStyle">@null</item>
</style>
</resources>
In your AndroidManifest.xml file, assign the theme to the menu activity:
<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
...
<application ... >
...
<activity
android:name=".MenuActivity"
android:theme="@style/MenuTheme"
...>
</activity>
</application>
</manifest>

Displaying the menu

Provide a PendingIntent for the card's action using setAction(). The pending
intent starts the menu activity when users tap on the card:
Intent menuIntent = new Intent(this, MenuActivity.class);
mLiveCard.setAction(PendingIntent.getActivity(this, 0, menuIntent, 0));
mLiveCard.publish();
Menu utilities
A few helper methods are available to modify the look and behavior of menus.
See MenuUtils for more information.

Immersions
Immersions give you more ways to consume user input and create user interfaces. This
allows you to create the most custom experience, but involves the most work.

Creating immersions
•You create immersions using standard Android activities, but keep the following in mind
when writing activities for Glass:
•Design your UIs for a 640 × 360 pixel screen.
•Design interactions that make sense on Glass instead of porting over activities from
other Android devices.
•Don't rely on complex touch gestures or UI patterns.
•Swiping down always goes back in the activity stack until users reach the timeline. It
should function much like the Android back button on smartphones and tablets.
•Create a 50 × 50 pixel icon and specify it for the android:icon attribute of the <activity>
element in your Android manifest. Also specify text for android:label. This allows a voice
or touch menu item that is associated with multiple Glassware to show your Glassware's
name and icon as an option.

Touch Gestures
Accessing raw data from the Glass touchpad is possible with the Android SDK.
However, the GDK provides a gesture detector designed for the Glass touchpad that
automatically detects common gestures on Glass, including tapping, swiping, and
scrolling.

Detecting activity-level gestures
Detecting gestures at the activity level is appropriate when you don't care what part
of your UI has focus. For instance, if you want to bring up a menu whenever a user
taps the touchpad.
The following example:
Creates a GestureDetector that implements listeners to process recognized gestures.
Overrides the activity's onGenericMotionEvent() method to pass the motion events
to the gesture detector's onMotionEvent() method.

When a motion event occurs, the system passes it to the gesture detector. If
recognized, the gesture detector notifies the appropriate listener to process the
event.

Detecting view-level gestures
Detecting gestures at the view level is appropriate when you want to do different things
depending on what view has focus.
The following example:
Creates a custom view that overrides the dispatchGenericFocusedEvent() method. When
a motion event occurs, this method passes the motion event to the gesture detector.
Declares the view to be focusable so that it detects events when it has focus.
Creates a GestureDetector that implements listeners to process recognized gestures.
When the gesture detector recognizes a motion while the view is in focus, the gesture
detector calls the appropriate listener.

Voice Input
Voice is an integral part in a hands-free experience for users. Glass
lets you declare voice triggers to launch your Glassware from the ok
glass voice menu.

Launching Glassware
To add a trigger to the ok glass voice main menu:
Declare a string value in res/values/strings.xml that defines the name of your voice
trigger. Optionally declare a voice prompt to display the speech recognition activity
before launching your Glassware.

<resources>
<string name="glass_voice_trigger">take note</string>
<string name="glass_voice_prompt">tell me what's on your mind</string>
</resources>
Create an XML resource for the voice trigger in res/xml/<my_voice_trigger>.xml that
uses the string value as the keyword.
<trigger keyword="@string/glass_voice_trigger">
<input prompt="@string/glass_voice_prompt" />
</trigger>

Register an intent filter using the com.google.android.glass.action.VOICE_TRIGGER action
in your Android manifest. The intent filter starts your activity if it detects users speaking
your voice trigger.
<application ...>
<activity ...>
<intent-filter>
<action
android:name="com.google.android.glass.action.VOICE_TRIGGER" />
</intent-filter>
<meta-data android:name="com.google.android.glass.VoiceTrigger"
android:resource="@xml/my_voice_trigger" />
</activity>
// ...
</application>

If your voice trigger used a voice prompt and starts an activity, obtain any transcribed text
with the following code (such as in onResume()):
ArrayList<String> voiceResults = getIntent().getExtras()
.getStringArrayList(RecognizerIntent.EXTRA_RESULTS);
If the voice trigger starts a service, the intent extra is available in the
onStartCommand() callback:
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
ArrayList<String> voiceResults = intent.getExtras()
.getStringArrayList(RecognizerIntent.EXTRA_RESULTS);
// ...
}

Setting constraints
If you need one or all of the following features to launch your Glassware, specify
them in the res/xml/<my_voice_trigger>.xml resource. If the features are not
available, Glass disables the voice trigger:
camera
network
microphone

<trigger keyword="@string/glass_voice_trigger">
<constraints
camera="true"
network="true" />
</trigger>

Starting the speech recognition activity
The speech recognition activity waits for users to speak and returns the trascribed
text after they are done.
To start the activity:
Call startActivityForResult() with the ACTION_RECOGNIZE_SPEECH intent. The
following intent extras are supported when starting the activity:
EXTRA_PROMPT
EXTRA_RESULTS_PENDINGINTENT
EXTRA_RESULTS_PENDINGINTENT_BUNDLE
Override the onActivityResult() callback to receive the transcribed text from the
EXTRA_RESULTS intent extra. This callback is called when users finish speaking.
private static final int SPEECH_REQUEST = 0;

private void displaySpeechRecognizer() {
Intent intent = new Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH);
startActivityForResult(intent, SPEECH_REQUEST);
}
@Override
protected void onActivityResult(int requestCode, int resultCode,
Intent data) {
if (requestCode == SPEECH_REQUEST && resultCode == RESULT_OK) {
List<String> results = data.getStringArrayListExtra(
RecognizerIntent.EXTRA_RESULTS);
String spokenText = results.get(0);
// Do something with spokenText.
}
super.onActivityResult(requestCode, resultCode, data);
}

Sensors
The following sensors are supported on Glass:
TYPE_ACCELEROMETER
TYPE_GRAVITY
TYPE_GYROSCOPE
TYPE_LIGHT
TYPE_LINEAR_ACCELERATION
TYPE_MAGNETIC_FIELD
TYPE_ORIENTATION (deprecated)
TYPE_ROTATION_VECTOR
The following sensors are not supported:
TYPE_AMBIENT_TEMPERATURE
TYPE_PRESSURE
TYPE_PROXIMITY
TYPE_RELATIVE_HUMIDITY
TYPE_TEMPERATURE

Here's some tips when using sensors on Glass:
The Glass sensor coordinate system is shown below relative to the Glass display. For
more information, see sensor coordinate system.
The accelerometer, gyroscope, and magnetometer are located on the optics pod of
the Glass device, which users rotate to align the device with their sight. You cannot
measure the angle of the optics pod directly, so be aware of this when using angles
from these sensors for applications such as compass heading.

To preserve battery life, only listen to sensors when you need them. For example, if
your Glassware uses a Service to render a LiveCard and you only need the sensors
when the live card is visible, use the LiveCard surface callback methods to start and
stop listening to the sensors.
Sensor event callbacks run on the UI thread, so process events and return as quickly
as possible. Consider pushing sensor events into a queue and using a background
thread to handle them if your processing takes too long.
50 Hz is often a sufficient sampling rate for tracking head motion.

Camera
You can use the Glass camera to capture images and video and to also display the
camera's preview stream for a variety of different use cases.
Overview
You have two options for capturing images or video:
Calling the built-in camera activity with startActivityForResult(). Use this option
when possible.
Building your own logic with the Android Camera API. Follow these guidelines if
you are using this method:
Take a picture on a camera button click and a video on a long click, just like
Glass does.
Indicate to the user whether a picture was taken or a video was recorded.
Keep the screen on during capture.

Sharing the camera with the Glass system
If your Glassware uses the Android APIs to access the camera, temporarily release the
camera when possible if users press the hardware camera button.
Override the onKeyDown() method in your activity and intercept KEYCODE_CAMERA to
handle camera button presses.
Release the camera and return false to indicate that you did not consume the event so
that the built-in Glass camera starts.
Note: If you return true from onKeyDown(), your activity consumes the event and the
Glass camera doesn't start. Do this only if there is no way to interrupt your activity's use
of the camera (for example, if you are capturing continuous video).

After the image or video capture takes place, Glass returns to your activity, where you
can reclaim the camera in onResume().

@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_CAMERA) {
// Stop the preview and release the camera.
// Execute your logic as quickly as possible
// so the capture happens quickly.
return false;
} else {
return super.onKeyDown(keyCode, event);
}
}
@Override
protected void onResume() {
super.onResume();
// Re-acquire the camera and start the preview.
}

GDK Guide for Building Glass Apps

Recomendados

Recomendados

Mais conteúdo relacionado

Semelhante a GDK Guide for Building Glass Apps

Semelhante a GDK Guide for Building Glass Apps (20)

Mais de Utpal Betai

Mais de Utpal Betai (15)

Último

Último (20)

GDK Guide for Building Glass Apps