Using Core Plot in an iPhone Application

The need to display a graph of some kind comes up surprisingly often when developing applications. Because of this, for almost every language and framework under the sun, there is some sort of graphing/plotting library (and sometimes a lot more than just one). While there is no built in library for graphing for iPhone applications, there is an open source library called Core Plot. This library is under active development and can be used to create a number of different types of graphs - if you want, you can check our their example page here.

Today we are going to be taking a look at how to get this library into your iPhone application, as well as how to use it to create a simple plot. But before we can do anything, first you have to go get the source for Core Plot. Because the library is still relatively new and under quick active development, there are no packages available - you have to get the source code straight from Core Plot's repository. So as a first step, you probably need to install Mercurial. Once you have that, getting the source is a simple matter of the following command:

That last argument (in our case here core-plot) is the directory you want to check the code out to. Ok, now that we have the code, what do we do? Well, let's get an iPhone Xcode project going! For this tutorial, our project is going to be named "SOTC-CorePlotTest". The first thing to do after you get an Xcode project off the ground is drag the CorePlot-CocoaTouch.xcodeproj file from the core-plot/framework directory into your new project. When you do that, you will get the following dialog:

The defaults are fine - most of the time we don't want to copy the entire library into your project - we just want a reference to wherever you checked our core-plot. So leave "Copy items into destination group's folder" unchecked. One you click "Add" on this dialog, an entry for CorePlot-CocoaTouch.xcodeproj will show up the "Groups & Files" tree for your project:

Because the iPhone core-plot is a static library, it needs to be linked with your application. To do this, you need to grab the entry libCorePlot-CocoaTouch.a from the "Groups & Files" (it is a child of the CorePlot-CocoaTouch.xcodeproj entry) and drag it to "Link Binaries with Libraries" node in your application's target:

Now we have to tell Xcode that our application is dependent on the core plot library - that way the library gets built when we build our app. This is done in the settings window for the application target. Under the "General" tab, you can add CorePlot-CocoaTouch as a direct dependency:

But don't think we are done yet! Now we have to modify some build settings. You do this by going to the "Build" tab of the project settings (not the build tab of the settings widow you were just in - those were build settings for the target). In here there are two properties that we have to modify: "Header Search Paths" and "Other Linker Flags". There are a lot of properties, but fortunately Apple gives us a little filter box to find the properties that we want. So first, "Header Search Paths". Here we need to add the full path to the core-plot/framework directory:

Then we need to add the -ObjC linker flag, which causes the linker to "Loads all members of static archive libraries that define an Objective C class or a category". We need this flag because Core Plot uses Objective C categories on existing classes, and when compiling against it as a static library, the code for the categories is not linked into the final executable. This flag forces that code to be included.

Ok, we are almost done with all this configuration - just one more step. We have to add the built in Core Animation library to our project, because Core Plot is built on top of Core Animation. To do this, you add the QuartzCore framework to the project. Right click on the Frameworks folder in the "Groups & Files" tree and choose Add->Existing Framework and browse for QuartzCore:

Whew! We are finally set to actually start using Core Plot. If you created a simple window project when you started, you probably have an AppDelegate and a ViewController class in your classes folder (mine here are "CorePlotTestAppDelegate" and "CorePlotTestViewController"). We aren't going to worry about the AppDelegate class today - all the code we are going to write will be in the ViewController. So start off by pulling up the .h file for your controller (in my case "CorePlotTestViewController.h"). It probably looks something like this at the moment:

Not much will change in this file, but there are a few things we are going to need to add:

First off, we need to reference the Core Plot libraries with an import statement. Since this is an iPhone application, we pull in the "CocoaTouch" version of the header file. Now that we have that, we can make the other two changes - an instance variable (to hold our graph) and a protocol. The variable is self explanatory, but the protocol probably needs some explanation. In this case, this view controller is going to be the data source for our graph, and so it has to implement the protocol CPPlotDataSource. This protocol is defined in Core Plot and consists of two functions:

Well, four functions actually, but you only have to implement two of them. The first one is a getter for the number of data points on the plot (numberOfRecords), and the last three (of which you need to implement one) are functions for getting the specific value for a particular data point.

Ok, that is it for talking about our ViewController header file - but before we move on to the actual implementation, we have to do one other thing. A core plot graph cannot be hosted in just any UIView - it has to be hosted in a CPLayerHostingView. To get this to happen we have to change the base type of our view. So pull open the xib file for the view for this view controller, and change the base type of the view to CPLayerHostingView in the Identity Inspector:

Finally, some implementation code! We will start off with the implementation of the protocol you saw above. In our case we will actually be drawing two plots on one graph - one being the function x^2, and the other being 1/x:

For these plots, I am explicitly returning 51 data points spread over the x range -5 to 5. In a real application the data would probably be coming from somewhere, like a file or user input, but here we are just graphing functions. When numberForPlot is called, I take the data point index passed in and transform it to an x value between -5 and 5. If the function was called asking for the X value (when fieldEnum is CPScatterPlotFieldX), I just return it. Otherwise, depending on the the identifier of the plot, I return the value either squared or inverted.

So that takes care of generating data for the graph. Now we need to take care of the creation of the graph itself:

If you remember from the header file, graph is a instance variable, and here we are finally populating it. Here we are creating a CPXYGraph (currently the only type of graph Core Plot offers), and then setting it as the hosted layer in our view (which is actually a CPLayerHostingView thanks to the change in the xib file earlier). We also set some padding here to give the graph some space on the screen.

A Core Plot graph can have many PlotSpaces. A PlotSpace is where individual plots live - but all plots in a plot space share the same range. In this case, we only need one PlotSpace, so we grab the default one. Here we are setting the x and y range of the plot space - one thing to note is that range is set in terms of position and length, not minimum and maximum values.

In this large chunk of code, we are setting up various axes properties (all of which are pretty much self explanatory). There are already a huge number of properties that you can set on axes, and that number is only going to grow as Core Plot continues to improve.

Finally, let's add some plots:

In both cases we are creating scatter plots (CPScatterPlot), although there are other XY plot types (such as CPBarPlot). The key thing here is the setting of the dataSource property - you have to set that property to whatever object is going to provide data for that plot (i.e., the one that implemented the CPPlotDataSource protocol). In this case, it is the controller itself, so we just put self. For the inverse plot, all we do is color the line blue, but for the squared plot we do a little bit extra. The scatter plot allows for markers to be put at data points, and so in this case we have a small green circle at every point.

Well, that is it! You want to see what all this work looks like? If you were coding along, you could just hit "Go", but for those that weren't, here is a screenshot:

Because that viewDidLoad function is spread across a couple code blocks and probably hard to just read (or copy), here is the CorePlotTestViewController.m file in one block:

Hope you found this intro to Core Plot useful! While it is still quite young as a plotting framework, it has a lot of potential (especially since it is the first one for the iPhone). You can grab a zip file below that holds the Xcode project we built today, if you want to try it out for yourself (although you will have to grab the core plot source separately - I did not include them). If you have any questions or comments, please leave them below.