Difference between revisions of "OptionsCycler"

Revision as of 21:28, 15 April 2013

This script allows an object to cycle though child objects, activating only one of them at a time. The options cycler was originally designed be used in a GUI or menu system, but really could be used for anything that requires only one child object to be active at a time.

This script provides hooks in the form of delegate functions (events), so that when the options are updated, corresponding settings for the game may be updated as well. See the section on events for more information.

Public Variables

options : GameObject[]

These are the options that are controlled. Only one of these will be activated at a time. This may be left blank if useChildrenAsOptions is set to true, although it's not guaranteed what order they will be in if the list is empty and populated at runtime, so the recommended way to use this is to always set the objects that are to be used as options in the editor.

useChildrenAsOptions : bool

If this is true, and the options list is empty, the GameObjects that are direct children of the object this script is attached to will be used as the options for the cycler.

currentOption : int

This is the index of the current option. It may be set to define what the starting option is. Valid values for this are 0 to options.Length - 1.

This is actually a private variable that is serialized so it may be set in the editor. To set this at runtime, use SetCurrent instead.

Events

In order to use these events, you must write a script that requires the OptionsCycler, and register functions to be called on these events. When the events are called it passes in the option being activated. At that point you can use whatever data is associated with that object to change settings for your game. Usually this means you can just look at the name of the option to change a setting, but if you wanted to get more sophisticated, you could create a cycler data class and use GetComponent to read the data for the current option.

Option Updated Events

The following events use this function prototype:

  public delegate void OptionUpdated (GameObject option);

The option that is being activated is passed in as the parameter to the function.

event OptionUpdated OnNextOption

Called to notify any listeners of the script that it's switching to the next option.

event OptionUpdated OnPreviousOption

Called to notify any listeners of the script that it's switching to the previous option.

event OptionUpdated OnSnapToOption

Called to notify any listeners of the script that it's switching to a specific option.

Option Enabled Events

The following event uses this function prototype:

  public delegate void OptionsCyclerEnabled ();

event OptionsCyclerEnabled UpdateCurrentOnEnable

This is used to allow listeners attached to this script to update the option to the correct setting. It is called when the option cycler is enabled.

Check if option is allowed

If there is a listener script attached to the options cycler, it may restrict certain options based on the current settings of the game. It uses a function with this prototype to determine if an option is allowed:

  public delegate void CheckIsValid (GameObject option, out bool result);

event CheckIsValid IsOptionValid

This is called every time NextOption or PreviousOption needs to check an option in the list. The option whose validity is in question is passed in. The function should set the boolean true or false depending if the option is a valid choice or not.

Public Functions

void HideAllButCurrent ()

This ensures all of the options are deactivated except for the current one.

void SetCurrent (string name)

This activates an option by name. No validity checking is done when using this function.

void SetCurrent (int idx)

This activates an option by index. No validity checking is done when using this function.

void NextOption ()

The cycles forwards through the options list. If not valid options are found, a warning is printed to the console.

void PreviousOption ()

The cycles backwards through the options list. If not valid options are found, a warning is printed to the console.

GameObject GetCurrentOption ()

This returns the current option.