PowerPlotPercolation logo

PowerPlot: A step-by-step tutorial

This article is a step-by-step tutorial about the PowerPlot library. It is intended for beginning PowerPlot developers. Starting from a simple data set, all steps needed to include and use the library are presented.

Table of contents:

Overview
Setting up the app in Xcode
Setting up the data model
Setting up the PowerPlot chart
Using the app

Overview

In the following I assume that you are familiar with development in Xcode for iOS apps. The code is written in Objective-C and uses the PowerPlot library which needs to be downloaded separately.

First, the project is set up and PowerPlot is installed. Then, the data model is instantiated, followed by the PowerPlot view. Finally, links for downloading the complete project (without the PowerPlot library itself) are given at the end of this article.

This article has been updated for Xcode 4.2 and iOS 5.0.

Setting up the app in Xcode

Create a new view-based app in Xcode. This is done easily by typing Command-Shift-N and then picking “Single View Application” in the “iOS”/“Application” tab. Type in your app and company identifier (I use “PP-Test” and “de.nua-schroers”). Pick “iPhone” for the “Device Family” and make sure that “Use Storyboard” and “Use Automatic Reference Counting” are not selected. Typically, I use a class prefix of “WS”, but this is a matter of taste here.

Before proceeding, the PowerPlot library sources need to be included. Download the file PowerPlot_lib.tgz from the PowerPlot homepage, unpack it and right click on the source code folder in Xcode. Selecting “Add files to PP-Test” opens a file dialog. Select the folder “lib” inside the main folder “PowerPlot_lib” and verify that the box “Copy items to destination group's folder” is checked. Confirm and verify that the folder “lib” has now appeared in the list of project files.

Believe it or not, but we are already done with the installation and can use the library from this point on!

Let's do it! First edit the file WSViewController.h and add an #import-statement and the following IBOutlets and IBAction to the @interface section:

    #import <UIKit/UIKit.h>
    #import "PowerPlot.h"

    @interface WSViewController : UIViewController

    @property (retain, nonatomic) IBOutlet WSChart *aView;
    @property (retain, nonatomic) IBOutlet UISegmentedControl *aControl;

    - (IBAction)toggleControl;

    @end

We also need to add the corresponding @synthesize-statements for the properties to WSViewController.m, but this can be done a little later.

Now add the user interface in the .xib-file. In older versions of Xcode 3.x this is done by double-clicking WSViewController.xib (which launches Interface Builder, a separate application), whereas in Xcode 4.x the UI is edited directly in place. The snap-shots below are taken in Xcode 4.x.

Add a UISegmentedControl at the bottom and a WSChart view at the top. To add the WSChart view, first add a UIView and then change its class to WSChart in the inspector. The segmented control has two buttons, call the first “Bars” and the second “Lines”. Connect the former to the aControl outlet and the latter to the aView outlet. To do this, control-click on the “File's Owner”, drag the mouse pointer to the controls and finally select the corresponding outlet. Then set the action of the segmented control to toggleControl. This is again done by control-dragging, but this time from the control to the “File's Owner”. At the end, the user interface should look like this:

UI design in Xcode 4

Save all files, and go back to the Xcode code section.

Setting up the data model

Now let's add the data model. First, add a property of class WSData to WSViewController.h:

    @property (nonatomic, retain) WSData *allData;

Then add the @synthesize-statement to WSViewController.m. As the view is loaded from a .xib-file, place the initialization code into the viewDidLoad method and the clean-up code into viewDidUnload. At this point, we simply assume that the data is provided in the form of a C-array of floats and that the X-values are simply the indices. Extended this to data downloaded from a webservice is straightforward – simply construct the WSData object from an NSArray of NSNumber directly or assemble it using addDatum: methods from a parser.

Furthermore, now is also the time to add all @synthesize-instructions for the properties to WSViewController.m. The toggleControl method will get done in the next step.

Current code of WSViewController.m:

    #import "WSViewController.h"

    @implementation WSViewController

    @synthesize aView;
    @synthesize aControl;
    @synthesize allData;
 
    - (void)dealloc {
        self.aView = nil;
        self.aControl = nil;
        self.allData = nil;
        [super dealloc];
    }

    - (void)viewDidLoad {
        [super viewDidLoad];

        float sourceData[10] = { 5, -2, 3, 7, 0, 1, -1, 3, 3, 5 };

        self.allData = [WSData dataWithValues:[WSData arrayWithFloat:sourceData
                                                                 len:10]
                                      valuesX:[WSData arrayOfZerosWithLen:10]];
        self.allData = [self.allData indexedData];
        [self toggleControl];
    }

    - (void)viewDidUnload {
        [super viewDidUnload];
        self.aView = nil;
        self.aControl = nil;
    }

    - (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation {
        return (interfaceOrientation == UIInterfaceOrientationPortrait);
    }

    - (IBAction)toggleControl {
        // pass
    }

    @end

At this point, the app can already be compiled! All that remains to be done is display the data in the view.

Setting up the PowerPlot chart

We want to display the data in two ways: either as a line chart or as a bar chart, depending on the user's choice with the UISegmentedControl.

For setting up these charts, we can simply use the factory methods of WSChart. All we need to do is add the appropriate code to the toggleControl method:

    - (IBAction)toggleControl {
        WSChart *tmp;
        switch ([self.aControl selectedSegmentIndex]) {
            case 0:
                tmp = [WSChart barPlotWithFrame:[aView frame]
                                           data:self.allData
                                          style:kChartBarPlain
                                    colorScheme:kColorLight];
                [self.aView removeAllPlots];
                [self.aView addPlotsFromChart:tmp];
                break;
            case 1:
                tmp = [WSChart linePlotWithFrame:[aView frame]
                                            data:self.allData
                                           style:kChartLineGradient
                                       axisStyle:kCSArrows
                                     colorScheme:kColorGray
                                          labelX:@""
                                          labelY:@""];
                [self.aView removeAllPlots];
                [self.aView addPlotsFromChart:tmp];
                break;
            default:
                break;
        }
        [aView setNeedsDisplay];
    }

Believe it or not: The app is finished and working!

Using the app

With very little coding – essentially two lines for setting up the data and four lines each for setting up the view – the app is already displaying data in one of two different styles:

Demo app with bar chart Demo app with line chart

The entire project (excluding the PowerPlot library itself which must be downloaded separately) can be downloaded from this link. Please note that the license is GPLv3. For other licensing options, please contact NuAS directly.