tvOS Remote Controls / General Properties
The tvOS version of The Story Tellers Starter Kit 2 is largely the same as the iOS version. Nearly every one of the events and interactions we cooked up for the iOS version works the same. Where things get a little different is how the user interacts with the app, which of course is remote based for the TV version. So keep in mind, the properties listed below are a handful of features specifically for the TV, and you’ll want to read the rest of the documentation for the tvOS version as well.
If you come across properties that might be questionable for a non-handheld device, its probably safe to assume they don’t work as described for the TV (properties that involve two fingers, like rotation gestures, or following the touch location won’t work for the TV).
Easy to setup image selection.
Obviously users can’t just touch the screen, so we have to give them a way to navigate through images using the remote. Using a simple array property (seen below)…
… we define the selection order. This is just a list of the images/buttons in the order they appear from left-to-right in the page. Then in the page’s Settings dictionary, you’ll set a number of Columns (if you have enough buttons to require columns). By setting the Columns value, the kit will know that swiping up would jump from the 5th button to the 2nd, and so on. You can also set a property named WrapAroundSelection to NO or YES which will allow or disallow going from the first button to the 9th if the user swiped up.
So you might be wondering then, how do you tell the kit to select something in the up, down, left or right directions? Well that’s easy! Simply create a dictionary called SwipeUpEvents, SwipeDownEvents, SwipeLeftEvents or SwipeRightEvents, then add ANY events you want to occur when swiping. Keep in mind, in the SwipeUpEvents example below, it simply lists SelectUp (which would select a button in the up direction), but you can put anything in here. Play sounds, swipe to new pages, run animations, anything is possible!
Properties to Navigate among Elements
Following up from the previous example, you have four properties to select an Element to be in-focus.
You’ll most likely run these events Swipes or Taps (documented later), where you can set one for each direction.
Making an Actual Selection
When an Element is selected or in-focus, you can include a TouchEvent dictionary to run Events if the user clicks / hard presses the remote touch pad. On iOS, this same TouchEvent dictionary is used whenever the user actually touches the Element, so in the tvOS world, this is the equivalent.
You might notice above you can also include dictionaries to do events when the item is in focus or left focus (detailed in the next section below).
In Focus and Leaving Focus Events
As of version 1.1, we’ve added event options for whenever an Element is in-focus or left-focus. For example, if the user is swiping between possible Elements to select, you can run events each time the button is in focus (meaning, possibly selectable). And likewise, if the button is no longer in focus, you can run an alternate set of events. This could be useful for a myriad of reasons. When an Element is in focus, you might…
- Change a label to gives details about what happens when the button is actually selected.
- Add it to the PanX or PanY array to begin moving it around the screen.
- Change the appearance of the Element (animate it, enlarge it, etc)
The dictionaries to set up in-focus and out-of-focus events are…
Tap events are setup the same as swipe events. So you have 4 possible dictionaries, TapLeftEvents, TapRightEvents, TapUpEvents and TapDownEvents. Each of these can have an unlimited number of events. In the example, below, we are adding a little force to a physics object to move it around….
You can find this example, in the Starter Kit. Tapping around the remote will push the lady bug around the screen.
And keep in mind, these are gentle taps on the remote’s touch pad, not a full on press down. Those properties are next…
Pressing down on the Remote and pressing the Play/Pause button
The new Apple TV remote has a primary selection button, which involves giving the remote touch pad a good tap/click, and a secondary button, the Play/Pause button, which you can use as an alternate method to select things, or make it do something unique to your game. Apple recommends you program the Play/Pause button to at least “do something”. So if your app doesn’t require it to do something special, then it should mimic whatever pressing the remote touch pad does.
You can add as many event properties as you wish to these two dictionaries….
In the example below, pressing the Remote touch pad, goes back to the Cover page.
Important: If your page includes Elements that can be selected (via the SelectionOrder array), pressing the remote touch pad will also call the TouchEvents dictionary on the Element currently selected (if that Element has a TouchEvents dictionary).
Moving / Panning with the Remote
The iOS version of the kit includes a convenient option for panning (moving images based on the users touch across the screen). We wanted to keep this nice simple option, so its been adapted for the touch remote. Using the same properties as before, you can list items to pan on the x or y axis like so….
In this example, only a LadyBug image is moving, but you can list as many items as you want to pan (switch from String to Array to list more). Now if the user pans their finger around the remote’s surface it will move the LadyBug. If you want to change how much the image moves in relation to the fingers, we’ve added two new properties in the page’s Settings dictionary for that, PanMultiplierX and PanMultiplierY….
Increasing those values moves the images at a faster rated.
The Menu Button
The menu button in tvOS is reserved for stepping backward through your app. So for example, if the user was on Page 10, the menu button should probably take them back to the Cover page, and if they pressed it again, it should back them out to the main menu of the TV. Going back to the main Apple TV menu is what happens by default if you don’t specifically code the menu button to do something. And that is required by Apple, so users can leave your app. So you can set a property called PressingMenuOpensPage, and define the page to back out to. So in the example page Settings below, we are telling the app to go back to the Cover page if the Menu is pressed. But on the Cover page itself, we would not want to include this property.
You can also just exclude this property altogether and let the Menu button always back out to the main menu directly.
If you stumbled onto this article, it is part of our documentation for the Story Tellers iOS Starter Kit 2. The kit enables you to make children’s book apps and games without writing any code! But it is Swift 2 based and compatible with iOS9 (or higher) and Xcode 7 (or higher), so kit buyers can even extend the functionality to fit their needs further. Some of what we cover in the kit documentation may apply to Xcode in general, so this article could be worth a read even if you aren’t a user. You can purchase Lifetime Updates the kit here, or subscribe Yearly to CartoonSmart and get the latest version, plus access to all of our other kits / tutorials.
We’ve also created an iBook to document the very latest properties in the kit, so be sure to download that as well.