Event Listeners

Story Tellers iOS Starter Kit 2 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.

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….

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.

Multiple conditions…

You can add another value within the ListenFor dictionary…

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.

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)

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…

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.

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”. 

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…

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.

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.