Note: This post belongs to a long series whose summary is here and which aims to present you how to use the CCControl library.

In this part we will see how to create and work with potentiometer in Cocos2D thanks to a class named CCControlPotentiometer. A potentiometer is a visual control used to select a single value from a continuous range of values in a circular way.

CCControlPotentiometer

A CCControlPotentiometer is composed of several graphical elements as shown below:

These components are:

A background sprite which represents the global track range
A track bar sprite which show the current slider’s value in a graphical way
A thumb sprite which show the state of the potentiometer

Default Behavior

The simplest way to create a potentiometer is to give the name of each components when you init it:

// Create a potentiometer
CCControlPotentiometer *potentiometer  = [CCControlPotentiometer potentiometerWithBackgroundFile:@"background.png"
                                                                                    progressFile:@"track.png" 
                                                                                       thumbFile:@"thumb.png"];

By default when you create a potentiometer the minimum value of the range is set to 0 and the maximum value to 1. It means that you can only pick values between 0 and 1, e.g. 0.35. Now, we are going to see how retrieve the values of the potentiometer by using methods provides by the CCControl class.

Working with Target-Action pairs

Like with all the CCControl’s components you have the possibility to listening to events with the help of the target-action pairs or with the help of blocks as shown below:

// Listening to changes of values by using the CCControlEventValueChanged event
// First possibility: using a target-action pair
[potentiometer addTarget:self action:@selector(valueChanged:) forControlEvents:CCControlEventValueChanged];
- (void)valueChanged:(CCControlPotentiometer *)sender
{
   NSLog(@"Potentiometer value = %.02f", sender.value);	
}

// Second possibility: using blocks
[slider setBlock:^(CCControlPotentiometer *sender, CCControlEvent event)
 {
    NSLog(@"Potentiometer value = %.02f", sender.value);            
 } forControlEvents:CCControlEventValueChanged];

For the potentiometers you need to listen to the CCControlEventValueChanged event to track its value. But as you can see, with the help of the CCControl API it is very easy.

Now we’ve seen the main functions of the CCControlPotentiometer we are going to talk about its own properties.

Properties

The CCControlPotentiometer is built with a set of properties which are listed below:

minimumValue: defines the minimum value that the potentiometer can have
maximumValue: defines the maximum value that the potentiometer can have
value: contains the current value (you can animating the change of the value by calling the setValue:animated: method anyway)
onThumbTintColor: defines the color used to tint the appearance of the thumb when the potentiometer is pushed:

Where To Go From Here?

To conclude the CCControlPotentiometer is very similar to the CCControlSlider and there is very easy to use. In the future some properties will be added but for the moment it is very basic.

You can find the code source and the examples on github and the API documentation hosted here.

If you have any comments or questions about this article, don’t hesitate to post a comment!