Events for Setting Saved Values
Setting/saving values are one of the most important aspects to interaction with the kit. Technically they are saved as String objects in the NSUserDefaults, and can persist throughout the lifespan of the app. So if you prompted the user to enter their name using the keyboard, that name would appear as long as the app was installed (assuming the value was not reset to something else by a property).
Values could also be used with event listeners to check if a page (or game level) has been passed. Perhaps, the reader has to pop 20 balloons before they can turn the page. When the page opens, you would set a BalloonCount value to 0. Increment it every time a balloon has been touched, and listen for it to equal 20.
Don’t forget to make use of SetValuesIfNil when you need it. Sometimes you only need to set a value if the value doesn’t already exist.
Note: setting or changing a value will automatically update any label using that value.
Here are the event properties to set values….
- SetValues – the contents of this dictionary will be key and value pairs for example, BalloonCount could equal 10. This gives you a way to reset values or set them. You might set Clock to 30, in preparation for a countdown clock.
- SetValuesIfNil – Just like SetValues but it will only set these values if they don’t already exist. This is the best option for setting initial defaults at the beginning of the book.
- SetRandomValues – A dictionary which sets a value to a random item in a Pool dictionary. This is useful for starting a new page with a random value, for example, a word to spell. You can have multiple items in this dictionary.
- SetRandomNumberValues – A dictionary which sets a value to a random number. This is useful for starting a new page with a random value to accomplish a task. The number you set will be the max value (1 will be the minimum). In the screenshot below, notice the type is set to String, thats perfectly fine. You don’t have to set this to Number since all these values ultimately end up being saved as String objects in the Defaults.
- SetValuesFromPool – This is a really handy property that lets you cycle through the values in a Pool in order. The pool is an array of string values you’ve set up equaling whatever you want. It could be random word values, random numbers (just be sure if you use numbers they are in String format in the pool array), or it could be a list of image textures. So for example, you could do something like this…
This would cycle through the pool and set a texture equaling that value. Keep in mind, the kit will always remember this value (unless you clear it) so the next time the app loads, the texture could still be that value (as long as you use the SetTextureFromPreference property on it initially)
- SetValuesFromPoolReverse – exactly like SetValuesFromPool but will step through the pool values in reverse.
- ClearValue or ClearValues – Enter the saved value as a String or Array of values, This is a quick way of setting values to nothing. This doesn’t actually set it to nil.
- ZeroValue or ZeroValues – Enter the saved value as a String or Array of values, This is a quick way of setting values back to 0.
- Increment-1 through Increment10 – For example if the key was Increment-1 and the value was be BalloonCount, then calling this would subtract 1 from BalloonCount. Or if the key was Increment10, then that would add 10. This is a fast way of adding or subtracting values.
- AddToValues – A dictionary containing the saved value as a key and a number as the value. Whatever current amount the key is, it will have the value added to it. So for example, if Coins was already 999 and we added 1,000, Coins would be 1,999 after this event. This is an important setting for Consumable In-App Purchases.
- AddStringValues – A new dictionary property as of Build 1.12, allowing you to add String characters to a saved value. For example below, the saved value is named PasswordAttempt and the character to append is E. If this event was triggered from a button, the reader could press it 4 times and their password would be “EEEE”.
- SubtractFromValues – A dictionary containing the saved value as a key and a number as the value. Whatever current amount the key is, it will have the value subtracted from it. So for example, if Coins was already 30 and we subtracted 10, Coins would be 20 after this event.
- MultiplyValues – A dictionary containing the saved value as a key and a number as the value. Whatever current amount the key is, it will be multiplied by the value. In the example below, whatever Coins currently equaled, it would be multiplied by 10.
- DivideValues – A dictionary containing the saved value as a key and a number as the value. Whatever current amount the key is, it will be multiplied by the value. In the example below, whatever Coins currently equaled, it would be divided by 3.
- FlushSavedValues – CAUTION this will remove all values in the NSUserDefaults, essentially resetting the app, including any saved defaults for purchases. Not recommended if you have in-app purchases.
- OpenKeyboard – enter the value you want to set or edit. For example, the reader’s name.
- Output – enter any text you want to see in the Output window. This is just for debugging purposes. Your end user would never see these messages, but before submitting your app it’s best to remove these.
- OutputValue – enter the name of a saved value you want to see in the Output window. This is just for debugging purposes. Your end user would never see these messages, but before submitting your app it’s best to remove these.
If you set a value for Language there are some related properties you can use based on that value.
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.