AT&T U-verse® Enabled
How to Respond to On-screen User Events
Publication Date: November 1st, 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.
IOS is a trademark or registered trademark of Cisco in the U.S. and other countries.
© 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 Contents
Contents
1
Introduction .......................................................................................................................................... 1
1.1
Additional Resources .................................................................................................................... 1
2
Responding to on-screen user events................................................................................................... 2
3
Send Notification Example .................................................................................................................... 3
© 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 3-1: Obtaining a reference to the receiver..................................................................................... 3
Example 3-2: setupListenCommands method .............................................................................................. 4
Example 3-3: registerForNotifications .......................................................................................................... 5
Example 3-4: uveSetTopBoxCustomEventOccurred ..................................................................................... 5
Example 3-5: PageForName .......................................................................................................................... 8
© 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 intended for developers who need a host-mode application that
can send notifications to a device application when an event occurs on the TV
screen. For example, if the user presses a button on the screen, you could
update the UI on the device so that it could respond to the event.
This document contains an example that sends notifications when one of three
buttons (Red, Blue, and Green) is pressed.
1.1 Additional Resources
In addition to this document, you may find the following documents helpful when
developing U-verse Enabled iOS apps.

How to Write Your First AT&T U-verse Enabled iOS App

How to Setup a U-verse Enabled Project in Xcode
In addition, you can find more technical information on the AT&T Developer
Program web site. See Develop AT&T U-verse ® Enabled Apps and select the
development platform that you are interested in.
© 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 8
2 Responding to on-screen user events
The uveListenCommand and uveActionCustom objects are needed for event
notifications.
The uveListenCommand object is used to set up a device so that it can listen for
an event. This set up is required before an object can receive a notification. The
uveListenCommand object has the following properties:

Event: This property specifies the name of the event (NSString) and has to
be prefixed with urn:. For example, for an event named myEvent, the
parameter value would be: urn:myEvent

ExpiryDate: This property specifies the date and time (NSDate) for time
limited notifications. If you do not wish to have time limited notifications, set
this parameter to nil.
The uveActionCustom object is a uveAction that you set up to be triggered by an
event in the host-mode application. The example in this document attaches an
instance of the uveActionCustom to the onClick property of an on-screen button
so that each time the button is clicked this action is invoked.
The uveActionCustom object has the following properties:

name: This property is inherited from uveAction. It specifies the name of the
action that can be used to reference the object from other uveGadgets at
runtime.

customEventName: This property specifies the name of the event and must
match the event property of the uveListenCommand object. The value of the
customEventName property must be prefixed with urn:. For example, for an
event named myEvent the parameter value will be urn:myEvent.

data: This property specifies data that you can provide to the event that is
called.
In Example 3-1, the uveListenCommand object is set up when the
uveAppliationDelegate is set up, and the uveActionCustom objects are attached
to the onClick properties of the uveButtons object.
© 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 8
3 Send Notification Example
In the following example the uveListenCommand object is set up when the
uveAppliationDelegate is set up, and the uveActionCustom objects are attached
to the onClick properties of the uveButtons.
In the default initializer, a reference to the receiver that is in use is obtained and
then a check is made to see whether the application server is started.
If the application server is not started, this example starts the application server
and sets this class as the delegate. In addition, the listen commands are set up in
a method that is called from here.
If the application server is already started, the page is displayed.
Obtain Reference to Receiver
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| - (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle
*)nibBundleOrNil
| {
|
self = [super initWithNibName:nibNameOrNil
bundle:nibBundleOrNil];
|
if (self) {
|
UverseConnectedManager *uvcMgr = [UverseConnectedManager
sharedManager];
|
_associatedSTB = uvcMgr.mostRecentlyEngagedSetTopBox;
|
|
if (uvcMgr.appServerState != AppServerStarted){
|
[self setupListenCommands];
|
[_associatedSTB startTVApplicationWithDelegate:self];
|
}
|
else {
|
[_associatedSTB displayPageWithName:@"test"];
|
}
|
}
|
return self;
| }
Example 3-1: Obtaining a reference to the receiver.
© 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 8
In the setupListenCommands method (see Example 3-2) each listen command is
implemented. The commands then notify the device, when the event matching
the name of the event argument occurs on the receiver. (Note that event names
need to be prefixed with “urn:”.) After the command is created it is sent to the
receiver.
setupListenCommands Method
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| -(void)setupListenCommands
| {
|
// setup a listen command to send a notification to the device
|
// with the red button is pressed on screen
|
uveListenCommand *redListen = [[uveListenCommand alloc]
initWithEvent:@"urn:red" expiryDate:nil];
|
[selfassociatedSTB sendSetTopBoxCommand:redListen];
|
[redListen release];
|
|
// setup a listen command to send a notification to the device
|
// with the blue button is pressed on screen
|
uveListenCommand *blueListen = [[uveListenCommand alloc]
initWithEvent:@"urn:blue" expiryDate:nil];
|
[self.associatedSTB sendSetTopBoxCommand:blueListen];
|
[blueListen release];
|
// setup a listen command to send a notification to the device
// with the green button is pressed on screen
uveListenCommand *greenListen = [[uveListenCommand alloc]
initWithEvent:@"urn:green" expiryDate:nil];
[self.associatedSTB sendSetTopBoxCommand:greenListen];
[greenListen release];
|
}
| }
Example 3-2: setupListenCommands method
© 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 8
In the registerForNotifications class, along with other notifications, this example
adds this class as an observer for the uveSetTopBoxCustomEventOccurred
notification, which will set the uveSTBCustomEvent as the callback.
registerForNotifications Class
1
2
3
4
5
6
| -(void)registerForNotifications
| {
|
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(uveSTBCustomEvent:)
name:uveSetTopBoxCustomEventOccurred object:nil];
|
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(uveSTBCommandSucceeded:)
name:uveSetTopBoxCommandDidSucceed object:nil];
|
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(uveSTBCommandFailed:)
name:uveSetTopBoxCommandDidFail object:nil];
| }
Example 3-3: registerForNotifications class
In the uveSetTopBoxCustomEventOccurred callback method, this example
checks the value of the uveSetTopBoxCustomEventKey property and then sets
the background color of the device’s view to match the color of the button that is
pressed.
uveSetTopBoxCustomEventOccurred Callback
1
|
2
3
4
5
| {
|
NSLog(@"CUSTOM: %@", note);
|
id userInfo = [note valueForKey:@"userInfo"];
|
if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"]
isEqualToString: @"urn:red"])
|
{
|
self.view.backgroundColor = [UIColor redColor];
|
}
|
else if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"]
isEqualToString: @"urn:blue"])
|
{
|
self.view.backgroundColor = [UIColor blueColor];
|
}
|
else if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"]
isEqualToString: @"urn:green"])
|
{
|
elf.view.backgroundColor = [UIColor greenColor];
|
}
| }
6
7
8
9
10
11
12
13
14
15
16
17
-(void)uveSTBCustomEvent:(NSNotification *)note
Example 3-4: uveSetTopBoxCustomEventOccurred callback
© 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 8
The device is now set up to receive the custom event notifications and to
respond to each event. The next part will be to create the page that is displayed
on the receiver, along with the actions that are attached to the on-screen buttons
and that cause the custom event notification to be sent when these actions are
invoked. This will all be done in the PageForName method.
The first part of this method is a check to determine whether the screen is
widescreen formatted. If the screen is widescreen, this example then sets the
screen to be the widescreen size for standard definition. It is generally
recommended to use this screen size when possible as it reduces the texture
memory footprint of your application and the receiver will scale the content to
high definition when a high definition screen is attached to the receiver.
In the rest of the pageForName method, this example creates three buttons to
display on the screen. When creating buttons, this includes specifying the name
of the button, the text to be displayed on the button, and the frame of the button
in the screen.
This example then sets the background color and the focusBackgroundColor
property to the color of the button, and then adds the button to the page. The
focusBackgroundColor property should always be set to the same color as the
button. When you set this property, the button will be highlighted when it has the
on-screen focus, but it will not use the default highlight color which might not
integrate with your color scheme.
© 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 8
This example then create the custom action. The important argument here is the
argument for the customEventName property. This name must be the same as
the name that you set up in the uveListenCommand and it must be prefixed with
“urn:”. The example then adds the action to the page and sets the action to be
the onClick handler for the button. This is repeated for the red, green, and blue
buttons.
PageForName Method
1
|
2
3
4
5
6
7
8
9
10
11
12
13
| {
|
if ([pageName isEqualToString:@"test"]){
|
NSLog(@"START pageForName:%@", pageName);
|
self.page = [[uvePage alloc] initPageWithName:@"test"];
|
if (tvFrame.size.width > 640){
|
self.page.frame = CGRectMake(0,0,854,480);
|
}
|
|
self.page.alpha = 1.0;
|
//self.page.backgroundColor = [UIColor whiteColor];
|
|
uveButton *redButton = [[uveButton alloc]
initButtonWithName:@"redButton" text:@"Red" frame:CGRectMake(220,
200, 100, 50)];
|
redButton.backgroundColor = [UIColor redColor];
|
redButton.focusBackgroundColor = [UIColor redColor];
|
[self.page addGadget:redButton];
|
uveActionCustom *redCustomAction = [[uveActionCustom alloc]
initActionWithName:@"redCustomAction" customEventName:@"urn:red"
data:nil];
|
[self.page addAction:redCustomAction];
|
redButton.onClick = redCustomAction;
|
[redButton release];
|
[redCustomAction release];
|
|
uveButton *blueButton = [[uveButton alloc]
initButtonWithName:@"blueButton" text:@"Blue"
frame:CGRectMake(370, 200, 100, 50)];
|
blueButton.backgroundColor = [UIColor blueColor];
|
blueButton.focusBackgroundColor = [UIColor blueColor];
|
[self.page addGadget:blueButton];
|
uveActionCustom *blueCustomAction = [[uveActionCustom alloc]
initActionWithName:@"blueCustomAction" customEventName:@"urn:blue"
data:nil];
|
[self.page addAction:blueCustomAction];
|
blueButton.onClick = blueCustomAction;
|
[blueButton release];
|
[blueCustomAction release];
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
-(uvePage *)pageForName:(NSString *)pageName
withParams:(NSMutableDictionary *)params forFrame:(CGRect)tvFrame
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 7 of 8
32
33
|
|
34
35
36
37
|
|
|
|
38
39
40
41
42
43
44
45
46
47
|
|
|
|
|
|
|
|
|
|
uveButton *greenButton = [[uveButton alloc]
initButtonWithName:@"greenButton" text:@"Green"
frame:CGRectMake(520, 200, 100, 50)];
greenButton.backgroundColor = [UIColor greenColor];
greenButton.focusBackgroundColor = [UIColor greenColor];
[self.page addGadget:greenButton];
uveActionCustom *greenCustomAction = [[uveActionCustom alloc]
initActionWithName:@"greenCustomAction"
customEventName:@"urn:green" data:nil];
[self.page addAction:greenCustomAction];
greenButton.onClick = greenCustomAction;
[greenButton release];
[greenCustomAction release];
return self.page;
}
else {
return nil;
}
}
Example 3-5: PageForName method
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Page 8 of 8