AT&T U verse® Enabled · 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

© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.

AT&T U-verse® Enabled

How to Respond to On-screen User Events

Publication Date: November 1st, 2013

Legal Disclaimer


i

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.

Table of Contents


ii

Contents

1 Introduction .......................................................................................................................................... 1

1.1 Additional Resources .................................................................................................................... 1

2 Responding to on-screen user events ................................................................................................... 2

3 Send Notification Example .................................................................................................................... 3

Table of Examples


iii

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


Page 1 of 8

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.

https://developer.att.com/developer/forward.jsp?passedItemId=14100154


Page 2 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.


Page 3 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 | - (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil

2 | {

3 | self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];

4 | if (self) {

5 | UverseConnectedManager *uvcMgr = [UverseConnectedManager sharedManager];

6 | _associatedSTB = uvcMgr.mostRecentlyEngagedSetTopBox;

7 |

8 | if (uvcMgr.appServerState != AppServerStarted){

9 | [self setupListenCommands];

10 | [_associatedSTB startTVApplicationWithDelegate:self];

11 | }

12 | else {

13 | [_associatedSTB displayPageWithName:@"test"];

14 | }

15 | }

16 | return self;

17 | }

Example 3-1: Obtaining a reference to the receiver.


Page 4 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 | -(void)setupListenCommands

2 | {

3 | // setup a listen command to send a notification to the device

4 | // with the red button is pressed on screen

5 | uveListenCommand *redListen = [[uveListenCommand alloc] initWithEvent:@"urn:red" expiryDate:nil];

6 | [selfassociatedSTB sendSetTopBoxCommand:redListen];

7 | [redListen release];

8 |

9 | // setup a listen command to send a notification to the device

10 | // with the blue button is pressed on screen

11 | uveListenCommand *blueListen = [[uveListenCommand alloc] initWithEvent:@"urn:blue" expiryDate:nil];

12 | [self.associatedSTB sendSetTopBoxCommand:blueListen];

13 | [blueListen release];

14 |

15 // setup a listen command to send a notification to the device

16 // with the green button is pressed on screen

17 uveListenCommand *greenListen = [[uveListenCommand alloc] initWithEvent:@"urn:green" expiryDate:nil];

18 [self.associatedSTB sendSetTopBoxCommand:greenListen];

19 [greenListen release];

20 | }

21 | }

Example 3-2: setupListenCommands method


Page 5 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 | -(void)registerForNotifications

2 | {

3 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uveSTBCustomEvent:) name:uveSetTopBoxCustomEventOccurred object:nil];

4 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uveSTBCommandSucceeded:) name:uveSetTopBoxCommandDidSucceed object:nil];

5 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uveSTBCommandFailed:) name:uveSetTopBoxCommandDidFail object:nil];

6 | }

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 | -(void)uveSTBCustomEvent:(NSNotification *)note

2 | {

3 | NSLog(@"CUSTOM: %@", note);

4 | id userInfo = [note valueForKey:@"userInfo"];

5 | if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"] isEqualToString: @"urn:red"])

6 | {

7 | self.view.backgroundColor = [UIColor redColor];

8 | }

9 | else if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"] isEqualToString: @"urn:blue"])

10 | {

11 | self.view.backgroundColor = [UIColor blueColor];

12 | }

13 | else if ([[userInfo valueForKey:@"uveSetTopBoxCustomEventKey"] isEqualToString: @"urn:green"])

14 | {

15 | elf.view.backgroundColor = [UIColor greenColor];

16 | }

17 | }

Example 3-4: uveSetTopBoxCustomEventOccurred callback


Page 6 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.


Page 7 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 | -(uvePage *)pageForName:(NSString *)pageName

withParams:(NSMutableDictionary *)params forFrame:(CGRect)tvFrame

2 | {

3 | if ([pageName isEqualToString:@"test"]){

4 | NSLog(@"START pageForName:%@", pageName);

5 | self.page = [[uvePage alloc] initPageWithName:@"test"];

6 | if (tvFrame.size.width > 640){

7 | self.page.frame = CGRectMake(0,0,854,480);

8 | }

9 |

10 | self.page.alpha = 1.0;

11 | //self.page.backgroundColor = [UIColor whiteColor];

12 |

13 | uveButton *redButton = [[uveButton alloc] initButtonWithName:@"redButton" text:@"Red" frame:CGRectMake(220, 200, 100, 50)];

14 | redButton.backgroundColor = [UIColor redColor];

15 | redButton.focusBackgroundColor = [UIColor redColor];

16 | [self.page addGadget:redButton];

17 | uveActionCustom *redCustomAction = [[uveActionCustom alloc] initActionWithName:@"redCustomAction" customEventName:@"urn:red" data:nil];

18 | [self.page addAction:redCustomAction];

19 | redButton.onClick = redCustomAction;

20 | [redButton release];

21 | [redCustomAction release];

22 |

23 | uveButton *blueButton = [[uveButton alloc] initButtonWithName:@"blueButton" text:@"Blue" frame:CGRectMake(370, 200, 100, 50)];

24 | blueButton.backgroundColor = [UIColor blueColor];

25 | blueButton.focusBackgroundColor = [UIColor blueColor];

26 | [self.page addGadget:blueButton];

27 | uveActionCustom *blueCustomAction = [[uveActionCustom alloc] initActionWithName:@"blueCustomAction" customEventName:@"urn:blue" data:nil];

28 | [self.page addAction:blueCustomAction];

29 | blueButton.onClick = blueCustomAction;

30 | [blueButton release];

31 | [blueCustomAction release];


Page 8 of 8

32 |

33 | uveButton *greenButton = [[uveButton alloc] initButtonWithName:@"greenButton" text:@"Green" frame:CGRectMake(520, 200, 100, 50)];

34 | greenButton.backgroundColor = [UIColor greenColor];

35 | greenButton.focusBackgroundColor = [UIColor greenColor];

36 | [self.page addGadget:greenButton];

37 | uveActionCustom *greenCustomAction = [[uveActionCustom alloc] initActionWithName:@"greenCustomAction" customEventName:@"urn:green" data:nil];

38 | [self.page addAction:greenCustomAction];

39 | greenButton.onClick = greenCustomAction;

40 | [greenButton release];

41 | [greenCustomAction release];

42 | return self.page;

43 | }

44 | else {

45 | return nil;

46 | }

47 | }

Example 3-5: PageForName method

Documents

AT&T U verse® Enabled · 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