AT&T U-verse® Enabled
How to Use the TV UI API in Android TM Apps
Publication Date: October 25th, 2013
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Legal Disclaimer
This document and the information contained herein (collectively, the "Information") is provided to you (both the individual receiving
this document and any legal entity on behalf of which such individual is acting) ("You" and "Your") by AT&T, on behalf of itself and
its affiliates ("AT&T") for informational purposes only. AT&T is providing the Information to You because AT&T believes the
Information may be useful to You. The Information is provided to You solely on the basis that You will be responsible for making
Your own assessments of the Information and are advised to verify all representations, statements and information before using or
relying upon any of the Information. Although AT&T has exercised reasonable care in providing the Information to You, AT&T does
not warrant the accuracy of the Information and is not responsible for any damages arising from Your use of or reliance upon the
Information. You further understand and agree that AT&T in no way represents, and You in no way rely on a belief, that AT&T is
providing the Information in accordance with any standard or service (routine, customary or otherwise) related to the consulting,
services, hardware or software industries.
AT&T DOES NOT WARRANT THAT THE INFORMATION IS ERROR-FREE. AT&T IS PROVIDING THE INFORMATION TO YOU
"AS IS" AND "WITH ALL FAULTS." AT&T DOES NOT WARRANT, BY VIRTUE OF THIS DOCUMENT, OR BY ANY COURSE OF
PERFORMANCE, COURSE OF DEALING, USAGE OF TRADE OR ANY COLLATERAL DOCUMENT HEREUNDER OR
OTHERWISE, AND HEREBY EXPRESSLY DISCLAIMS, ANY REPRESENTATION OR WARRANTY OF ANY KIND WITH
RESPECT TO THE INFORMATION, INCLUDING, WITHOUT LIMITATION, ANY REPRESENTATION OR WARRANTY OF
DESIGN, PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, OR
ANY REPRESENTATION OR WARRANTY THAT THE INFORMATION IS APPLICABLE TO OR INTEROPERABLE WITH ANY
SYSTEM, DATA, HARDWARE OR SOFTWARE OF ANY KIND. AT&T DISCLAIMS AND IN NO EVENT SHALL BE LIABLE FOR
ANY LOSSES OR DAMAGES OF ANY KIND, WHETHER DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE,
SPECIAL OR EXEMPLARY, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF GOODWILL, COVER, TORTIOUS CONDUCT OR OTHER
PECUNIARY LOSS, ARISING OUT OF OR IN ANY WAY RELATED TO THE PROVISION, NON-PROVISION, USE OR NON-USE
OF THE INFORMATION, EVEN IF AT&T HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES.
Android is a trademark of Google Inc.
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
i
Table of Tables
Contents
1
Introduction .......................................................................................................................................... 1
1.1
Additional Resources .................................................................................................................... 1
2
TV UI API................................................................................................................................................ 2
3
Sample Code ......................................................................................................................................... 4
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
ii
Table of Examples
Example 2-1: startTVApplication .................................................................................................................. 2
Example 2-2: displayPage ............................................................................................................................. 3
Example 3-1: Using the TV UI API ................................................................................................................. 6
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
iii
1 Introduction
This document is an introduction to the TV UI API for developers who are writing
U-verse Enabled apps for Android TM. Using this API, you are able to create
interfaces for your app on the screen attached to the U-verse receiver. This
allows a user to interact with your TV UI app on a television connected to a Uverse receiver. This document includes the basics of adding this functionality to
your app and creating a page to display on the television, as well as a code
sample using the API to display an image on the television screen.
1.1 Additional Resources
In addition to this document, you may find the following documents helpful when
developing U-verse Enabled apps for Android.
•
How to Write Your First AT&T U-verse Enabled App for Android
•
How to Setup a U-verse Enabled Project in Eclipse
In addition, you can find more technical information on the AT&T Developer
Program web site at the following location: http://developer.att.com/u-verse
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 1 of 6
2 TV UI API
The TV UI API allows you to display content from your app onto the screen
attached to the U-verse receiver. This allows you to draw content on screen,
such as buttons, images, and text, as well as play audio and visual content.
To add second-screen functionality to your app, you use the
HostModeListenerprotocol. This protocol has four methods:
•
OnSetTopBoxGadgetRequest: This is the callback method that your app
receives each time that the U-verse receiver displays a page of content on
the screen. Use this method to create uvePage/uvePanel objects with
uveGadget, uveAction, uveAnimation and other TV UI API widgets.
•
OnSetTopBoxResourceRequest: This is the callback method that your app
receives each time that a page requests a media file, such as images, audio
and video. Although you create the object and add it to the page using the
onSetTopBoxGadgetRequest method, when the resource is needed the
receiver will call this method, passing the URL of the resource as the name
argument. The app then returns the resource as input stream for network
transmission.
•
OnHostModeStateChange: This method is called when the HostModeserver
changes state to indicate whether the server is ready or not. After calling
startTVApplication(hostModeListener), wait for this callback to return the
HostModeReady state, then the app can display a page on the screen.
•
OnSetTopBoxCustomEventRequest: This method is called when the custom
event (uveActionCustom) is triggered.
After you have implemented the methods in the HostModeListener callback
handler, call startTVApplication on the SetTopBox object that you wish to display
the content.
The following code sample starts the application server on the engaged receiver,
passing the HostModeListener handler object that contains this delegate.
Note: This sample ignores the possibility that getMostRecentlyEngagedSTB()
can return null.
startTVApplication
1
|
uveMgr.getMostRecentlyEngagedSTB().startTVApplication(hostModeLis
tener);
Example 2-1: startTVApplication
After you receive the HostModeReady state in the onHostModeStateChange
callback, you can call the displayPage method on the SetTopBox object on which
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 2 of 6
you started the application server, passing the name of the page that you wish to
display as the argument.
displayPage
1
|
uveMgr.getMostRecentlyEngagedSTB().displayPage(“TvUIAPIStartPage”
);
Example 2-2: displayPage
After you call displayPage, the object that you passed as the argument to the
startTVApplicationmethod will receive the onSetTopBoxGadgetRequest callback.
This callback is received for each page your app displays. You should check the
pageName argument and then display the correct content for the requested
page.
After the call to the onSetTopBoxGadgetRequestcallback returns the page to be
displayed to the SetTopBox, the callback OnSetTopBoxResourceRequest is
called if any resources need to be loaded on the page.
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 3 of 6
3 Sample Code
The example in this section is a basic implementation of the TV UI API that
displays an image on the screen. The following diagram represents the flow of
the host mode listener.
Figure 3-1: Host Mode Listener Flow
This example sends an image to be displayed on the screen that is attached to
the receiver. Using the Android onResume method, this example checks if the
application server has been started and, if not, it calls the startTVApplication
method to start the application server.
Next, in the HostModeReady state in onHostModeStateChange callback, this
example calls the displayPage method to display the page on the screen
attached to the U-verse receiver. The U-verse receiver then calls the
OnSetTopBoxGadgetRequest method. In this example, the method creates and
adds the uveImage object to the page, and then returns the page.
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 4 of 6
Finally, when the U-verse receiver is about to the display the image, it calls the
OnSetTopBoxResourceRequest method. There are two important things to
consider regarding this method. First, the resourceName argument is the URL of
the resource and not the name. Second, this method returns an InputStream
object, so the source must be wrapped in a stream object before it is returned.
TV UI API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
16
17
18
19
20
21
22
23
|
|
|
|
|
|
|
|
24
25
26
27
28
29
30
31
32
33
34
35
publicvoidonResume(){
super.onResume();
uveMgr.updateListener(uvelistener);
stbContainer = UVEDataContainer.instance();
recentSTB = uveMgr.getMostRecentlyEngagedSTB();
if(uveMgr.isHostModeActive()){
recentSTB.displayPage("TvUIAPIStartPage");
} else {
recentSTB.startTVApplication(hostModeListener);
}
hostModeListener = new HostModeListener() {
Public void OnHostModeStateChange(HostModeStatehostModeState,
uveException e) {
switch (hostModeState){
caseHostModeReady:{
recentSTB.displayPage("TvUIAPIStartPage");
caseHostModeNotReady:
Log.d("TV UI", "Error : " + e.getMessage());
}
Public uveGadget OnSetTopBoxGadgetRequest(String requestedPage,
Map<String, String> arg1, Rect arg2) {
| if("TvUIAPIStartPage".equals(requestedPage)){
| uvePage page = newuvePage(requestedPage);
RectimageFrame = new Rect(20,20, 300, 200);
URI imageURI = new URI(“car.jpg”);
| uveImage image=newuveImage("image",imageURI,imageFrame));
|
|
|
|
|
|
|
|
|
page.addGadget(image);
return page;
}
return null;
}
Public void OnSetTopBoxCustomEventRequest(String arg0) {
// To be handled when using custom events.
}
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 5 of 6
36
37
|
|
38
39
40
41
42
|
|
|
|
|
Public InputStream OnSetTopBoxResourceRequest(String requestedResource,
Map<String, String> arg1) {
AssetManager assetManager = getAssets();
returnassetManager.open(requestedResource);
}
}
Example 3-1: Using the TV UI API
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 6 of 6