Event Listeners – Story Tellers iOS Starter Kit Documentation

Listeners allow you to check values or other conditions and run an unlimited number of Events when the condition is met. And you can listen for multiple conditions in a group, or ALL listeners.

Consider some of the reasons you might want to use EventListeners.

  • A card game similar to Black Jack. If a value is too high, the page is reset. If it’s below a value, you keep playing.
  • The user can’t continue until the keyboard has a value (i.e. not blank). This could be used to make the reader provide a name to include in the story.
  • In a spelling game, the user might have to write a specific words in the keyboard.
  • In a puzzle pairing game, you could listen for a specific number of pieces pairing together.
  • In a drag and drop game, you could listen for specific Elements intersecting with each other. This could be combined with physics games or maze games where the user has to navigate the scene to get to a certain point.
  • A game where the reader has to touch a certain number of Elements (and possibly not touch another Element).
  • You could even check to see if an Element’s texture preference is matching a specific value. This could be useful for a dress up game.
  • The user has to find and collect a certain number of things.

Event Listeners in the Childrens Book iOS9 App

The EventListeners dictionary is setup on a per-page basis. For each listener or group of things to listen for, you’ll create a sub-dictionary of any name you want. For example, Listener1 in the image below….

Event Listeners in the Childrens Book iOS9 App 1

Within this dictionary, you will need to create an Events dictionary to define what will happen when the listening condition is met. Then add a dictionary specifically named either…

  • ListenFor        (equality)
  • ListenFor>     (greater than)
  • ListenFor<      (less than)
  • ListenFor!=       (non-equality)
  • ListenForIntersection      (intersection)
  • ListenForPairing      (intersection meant for pairing)
  • ValueMatch     (checks if two saved values match each other)

In the example image, you can see that the ListenFor dictionary contains a key named Popped with a String value of 10 (even though 10 is a number, set the type to String). The kit will repeatedly check to see if the value of Popped equals 10. If so the Events are run.

You can set Popped using any of the event properties that that deal with setting values.

That’s “listening” at it’s most basic.

 

 

Enabled by Default, but…

As of version 1.05, you can setup listeners that are not running right away by setting the Enabled property to NO within the listener group.

Event Listeners in the Childrens Book iOS9 App 2

Multiple conditions…

You can add another value within the ListenFor dictionary…

Event Listeners in the Childrens Book iOS9 App 3

If Popped is 10 OR MushroomsEaten is 50, then the Events will run. So this is an “either or” condition. Both do not have to be met for the Events to run.

If you want all conditions in the group to be met before performing the Events, then set the MeetAllConditionsInGroup property to YES.

Event Listeners in the Childrens Book iOS9 App 4

Be sure to put this inside the group dictionary, but outside the ListenFor dictionary.

Once a condition is met it is “checked off the list” basically. So once Popped is 10, one condition is true. Then MushroomsEaten just needs to be 50.  Whenever MushroomsEaten is 50, Popped could be greater than 10, and the Events will still run.

You do not need to set this property if you only have condition in the group. In fact, you should not, because each page can only have 5 total MeetAllConditionsInGroup properties running.

Multiple Listeners per group…

Your group can have multiple dictionary conditions. For example, you could have both…

  • ListenFor   (equality)
  • ListenFor!=   (non-equality)

Event Listeners in the Childrens Book iOS9 App 5

 

Now Listener1 is listening for Popped to equal 10 (at some point), MushroomsEaten at 50 (at some point) and UserName to not equal blank.

Meeting All Conditions Across all Listeners…

If you have multiple groups, you can optionally choose to set:

AllListenersMustBeMet to YES 

This property is set inside the EventListeners dictionary and outside of any interior dictionaries. See the image below…

Event Listeners in the Childrens Book iOS9 App 6

 

Now, all conditions in every group must be true for the Events dictionary to run. Ahhhh, but which dictionary is that. Since you won’t necessarily know which condition is satisfied last, your Events dictionary should probably be the same in each group. Unless you want to do something different depending on which condition is done last.

Hmmm… could lead to some interesting decisions.

Re-running the Same Listener 

You can use the AlwaysListen property to re-run the same listener over and over again. Notice in the screenshot below, we’ve removed the MeetAllConditionsInGroup property and replace it with AlwaysListen. Now every time we do something like drop Quarter into the Quarter_Hole, it will run the Events.

Event Listeners in the Childrens Book iOS9 App 7

 

Greater than and Less than Listener

If you set either of these two listening conditions….

  • ListenFor>     (greater than)
  • ListenFor<      (less than)

…the code will convert the string values to actual numeric values then see if the condition is truly less than or greater than. This might be necessary if for example, you want to see if a value like Popped is at least 10, but it could potentially by more if something in the page increments it’s value directly from 8 to 11 by adding 3. In a scenario like that, Popped would never have equalled 10 exactly, and a straight ListenFor (equality condition) wouldn’t be satisfied. So this is why you might want to use the ListenFor> or ListenFor< options.

Value Match

If you set….

  • ValueMatch

…the code will check to see if two saved values match each other. In the example below, PasswordAttempt and RandomPassword are both saved values. Technically speaking, the code is not checking to see if “PasswordAttempt” equals “RandomPassword” (as that would always fail), it is checking to see if the NSUserDefault with a key of “PasswordAttempt” equals the NSUserDefault with a key “RandomPassword”. 

Check if values match in xcode

Intersection and Puzzle Pairing Conditions

Two important listeners for puzzle games or matching type games are…

  • ListenForIntersection      (intersection)
  • ListenForPairing      (intersection meant for pairing)

These two conditions are nearly identical code-wise, the difference is what happens to the Elements that are detected intersecting.

First take a look at the Listener2 group in the following image…

Event Listeners in the Childrens Book iOS9 App 8

Inside the ListenForPairing dictionary we have entries for each PuzzlePiece(1 through 4) intersecting each PuzzleBase(1 through 4).  The MeetAllConditionsInGroup property is set to YES, so all 4 pieces have to be paired before the Events are run. Note you can include as many pieces and bases as you want.

The setup for ListenForPairing and ListenForIntersection is identical, but when a “pairing” occurs the key element moves to the exact same location as the value element (e.g. the PuzzlePiece goes to PuzzleBase’s position). Then the element acting as the PuzzlePiece has it’s TouchEvents removed and is no longer set to follow the user’s touch. In other words the piece can’t be moved once paired.

Notice too, the Events dictionary in this example, actually removes all the PuzzleBases and PuzzlePieces, then sets a different Element named PuzzleCompleted to Show itself. For extra fun, gravity was enabled on PuzzleCompleted so it floats around the scene.

Event Listeners in the Childrens Book iOS9 App 9

As of Build 1.11, if you use ListenForIntersection, and the Element specified as the value is named “Trash”, the kit will remove whatever Element intersected with it. So for example, if your app was a dress-up type game this would be an easy way to have users move items to the trash and get rid of them.

Trashing items in the iOS9 Starter Kit

Related Properties in a Page's Settings Dictionary

  • PairingSensitivity – A number value (either 0, 1, 2, or 3) to set how sensitive the kit is in detecting puzzle style pairing (only applies if there is an Event Listener for pairing setup). 0 uses the entire width and height of the image, assume puzzle piece, when checking the intersection of the puzzle and base position. 3 only uses a fraction of the width and height making the puzzle pairing more exact.
  • IntersectionSensitivity –  A number value (either 0, 1, 2, or 3) to set how sensitive the kit is in detecting intersections (only applies if there is an  Event Listeners setup). 0 uses the entire width and height of the image  when checking the intersection of the other element’s position. 3 only uses a fraction of the width and height making the intersection detection more exact.
  • ListenerSpeed – A number value for how fast you want listeners in the scene to run. The default is 0.25 or every quarter-second. Raise or lower to your liking. All Listeners fire once immediately, then begin using this speed afterwards. The lowest you should set this value is 0.02, but thats probably overkill.

Events for Starting and Stopping Listeners

As of version 1.05, you can start and stop listeners from an event.

The event properties are…

StartListener – the value will be the listener group name to start. See the image below. Note, this is the Listener group name. All listener conditions in the group will be stopped.

StopListener – the value will be the listener group name to stop.

Event Listeners in the Childrens Book iOS9 App 10

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.