Quick Start Guide – Java

Introduction

This is a brief introduction to using the ShinobiCharts component. We will take you through a series of simple steps introducing the key features of the charting library.

Firstly we will look at getting a line chart onto a page and then follow on by looking at how to apply basic styling to the chart elements. The end result of this little tutorial will be a chart that looks something like this:

quickstart-final

For this guide we will assume that you are using the Android Studio IDE. If you wish to use the Eclipse IDE, the process is very similar, and the required code will be the same. It is simply attributes such as where menu items are located within the IDE, which will differ.

We recommend running the Quick Start project, and the other sample projects, on a physical Android device. This way you will be able to get a better feel of all the touch-based interactions. That said, it is possible to run the samples on the Android Emulator.

shinobicharts uses OpenGL ES2; support for this in the Android Emulator is currently experimental so be alert for incompatibilities and errors. Simply ticking the Use Host GPU box in the configuration of your Android Virtual Device may be all that is needed. More information is available on the Android Developer site: http://developer.android.com/tools/devices/emulator.html. In particular, the Configuring Graphics Acceleration and Configuring Virtual Machine Acceleration sections may provide some helpful guidance.

Draw a Simple Chart

Start by creating a new Android Application project:

  1. From the Welcome screen click New Project (if you have a project already open click File > New > New Project…)
  2. Give the application an Application name: shinobi-charts-quickstart and a suitable Package name (we use com.example.shinobiquickstart but you should use your own)
  3. Choose a suitable location for the project and click Next
  4. Click Next again to choose the default form factor (Phone and Tablet) and Minimum SDK (shinobicharts supports down to Android API 9, however to keep things simple and avoid needing the Android Support Library we’ll use API 12)
  5. Click Blank Activity and click Next
  6. Choose an appropriate name for your activity – this guide will assume the main activity is named ShinobiQuickStartActivity
  7. Click Finish and your project will be created

Import the ShinobiCharts for Android Library

Android Studio

To use the shinobicharts library you’ll need to declare a dependency on it from your application. This section covers both the process of importing the library from a locally stored .aar file and importing the library from a private repository.

From a locally stored .aar file

Open up Android Studio and make sure you’ve unzipped the download bundle. This guide assumes that you have already created a project for your application within Android Studio.

  1. With your project open within Android Studio, click File > New > New Module…. In the Create New Module window that appears, in the lower panel click on Import .JAR or .AAR Package. With Import .JAR or .AAR Package highlighted, click Next.
  2. Click the ellipsis button (…) and browse to the directory in which you unzipped the download bundle. Locate the shinobicontrols-android-charts-<edition>-java-1.9.0-3.aar. Click Finish.
  3. You should now see a new module within your project which represents the imported shinobicharts Library. You must now include a reference to the library in your project’s dependencies.
  4. Click File > Project Structure…. In the Project Stucture window, on the left hand side click on your application module (usually called app). With this selected, click the Dependencies tab.
  5. Click the plus (+) symbol at the right side of the window and choose Module Dependency. From the drop down list select the entry for the new library module which you created in the previous steps and click OK.
  6. Click OK again to close the Project Structure window. This should automatically trigger a Gradle build of your project.
  7. You should now be able to reference the shinobicharts library within your application project.

If you are using the SupportChartFragment you will also need to add a dependency on the Android Support Library from your app. Back in the Project Structure window:

  1. Select your app module in the list of modules on the left hand side.
  2. Click the plus (+) symbol again but this time choose Library Dependency.
  3. Select the entry that says support-v4 (com.android.support:support-v4:24.0.0) and click OK.

From a private repository

This section of the guide assumes that you have already created a project for your application within Android Studio. It also assumes that you have declared the repository (where the shinobicharts library will reside) within your project’s master gradle.build file.

When installing/deploying the .aar file to a Maven repository you can use the provided pom.xml file (also in the ‘lib’ folder of the download bundle). This will declare a dependency on the Android Support Library, which the SupportChartFragmentmakes use of. It will also set the following:

  • groupId: com.shinobicontrols.android.charts
  • artifactId: shinobicontrols-android-charts-<edition>-java
  • version: 1.9.0-3
  • packaging: aar

To add a dependency to your application on the shinobicharts library, which resides in your repository:

  1. Open the build.gradle file of your application’s module
  2. In the dependencies section, add a dependency to shinobicharts for the compile configuration using the groupIdartifactId and version that you set when installing the .aar file. If you used the provided pom.xml file you would do the following:
    dependencies {
        compile 'com.shinobicontrols.android.charts:shinobicontrols-android-charts-<edition>-java:1.9.0-3'
    }
  3. Sync your project with the Gradle files by clicking on the Sync Now link or on the Sync Project with Gradle Files button
  4. You should now be able to reference the shinobicharts library within your application project.

Important: if you did not use the provided pom.xml file when installing the shinobicharts library into your repository, you will also need to add a dependency on the Android Support Library to your application’s build.gradle file:

dependencies {
    compile 'com.shinobicontrols.android.charts:shinobicontrols-android-charts-<edition>-java:1.9.0-3'
    compile 'com.android.support:support-v4:24.0.0'
}

Eclipse

shinobicharts is designed to be used with the Android Studio IDE. That said, it is possible to import the library into the Eclipse IDE, following the instructions below.

To use the shinobicharts library you’ll need to import it into Eclipse as an Android Library Project and then reference it from your own application. Open up Eclipse and make sure you’ve unzipped the download bundle.

  1. Unzip the .aar file (included in the shinobicharts download bundle) into a temporary directory.
  2. Create an empty directory (not in the Eclipse workspace) that will be the home for the Android library project. For the rest of these steps, we will refer to this as the output directory.
  3. Copy the AndroidManifest.xml and proguard.txt files, and the res/ directory from the unzipped .aar file into the output directory.
  4. Create a libs/ directory in the output directory. Copy into libs/ the classes.jar from the root of the unzipped .aar file, plus anything in jni/ in the .aar file.
  5. Import the resulting project into Eclipse. Tick Is a Library within the Android project settings menu as usual.

You can now reference this project in any Android Application projects you create in your workspace.

Hardware Acceleration

In order to display a chart, some devices need to be explicitly told that the application requires hardware acceleration. To do this simple add android:hardwareAccelerated="true" to the application element of your app’s AndroidManifest.xml file.

Add the ShinobiChart

In the XML layout file for your Activity (named activity_shinobi_quick_start.xml), which can be found in the res/layout/ folder, click on the tab along the bottom called Text to show the raw XML. Replace the TextView with a ChartFragment:

<fragment
    class="com.shinobicontrols.charts.ChartFragment"
    android:id="@+id/chart"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Here the ChartFragment is being told to match the dimensions of its parent and is being given an id which makes it easier to retrieve in code.

Now open up ShinobiQuickStartActivity.java. You’ll see Android Studio has already added some code to your Activity. You only want to set up your chart the first time the Activity is created so add the following to the end of the onCreate()method:

if (savedInstanceState == null) {

}

In Android, configuration changes such as rotating your device cause Activities to be destroyed and re-created. You can tell if the Activity is being created for the first time by checking to see if savedInstanceState == null. Normally Fragments within an Activity will be destroyed and re-created as well. However, by default, a ChartFragment is retained across Activity re-creation so you only need to do the setup once.

Add the following inside the if statement you just added:

ChartFragment chartFragment =
                (ChartFragment) getFragmentManager().findFragmentById(R.id.chart);

ShinobiChart shinobiChart = chartFragment.getShinobiChart();
shinobiChart.setTitle("My First Chart");

Using the id you gave the ChartFragment in the XML, and the Activity’s FragmentManager, you can get a reference to it in code. From the ChartFragment you obtain the ShinobiChart and give it a title.

Tip: You can use the Alt+Enter keyboard shortcut in Android Studio to add the necessary import statements.

If you have downloaded a trial version of shinobicharts you will have been issued with a trial license key. You will need to give this key to the chart in order for it to be displayed. You can do this as follows:

shinobiChart.setLicenseKey("<license_key_here>");

Make sure you change <license_key_here> to the trial license key you were given!

The main parts of a chart can be configured via some key properties on the ShinobiChart object. For example, you’ll need to add the axes and series. In this example, you’re making a chart with three columns on linear numeric scales. For now, add the axes and we’ll come back to the series a little bit later. Still inside the if statement add:

NumberAxis xAxis = new NumberAxis();
shinobiChart.setXAxis(xAxis);

NumberAxis yAxis = new NumberAxis();
shinobiChart.setYAxis(yAxis);

Here you’re creating both the X axis and Y axis as a NumberAxis and then setting them on the chart.

So with the exception of the data, the chart is set up.

Tip: To support devices down to API 9: Android 2.3 (Gingerbread) you will need to use SupportChartFragment instead of ChartFragment (in both the XML and the Java source). Additionally, you will need to change the ShinobiQuickStartActivity to extend FragmentActivity instead of Activity and use the getSupportFragmentManager() method instead of getFragmentManager(). Your project will need to reference the Android Support Library to do this.

Adding a Series

Now you have your chart it’s time to add some data. Adding data to a ShinobiChart is as simple as creating a DataAdapter, adding data to it and handing it to a series on the chart. For this app you’ll have 2 series, each with its own data adapter. Still inside the if statement add:

SimpleDataAdapter<Double, Double> dataAdapter1 = new SimpleDataAdapter<Double, Double>();
SimpleDataAdapter<Double, Double> dataAdapter2 = new SimpleDataAdapter<Double, Double>();

This creates a new SimpleDataAdapter – it notifies the chart every time a data point/set of data points is added or removed, and is supplied out the box.

Now, add some data to it – sine waves

for (int i = 0; i < 100; i++) {
    double radians = i * Math.PI / 25.0;
    dataAdapter1.add(new DataPoint<Double, Double>(radians, Math.sin(radians)));
    dataAdapter2.add(new DataPoint<Double, Double>(radians, Math.cos(radians)));
}

DataPoint has an X and a Y value and is parametrized by the types of those X and Y values. Like SimpleDataAdapter it’s supplied out the box for when you just need a simple data point representation. You can instead create your own data points by implementing the Data interface. Here you are using Double, but the types should be appropriate for their intended axes. NumberAxis is compatible with any numeric data which is representable using java.lang.Number or its subclasses, and will accept Data objects parametrized to those types.

Next, create 2 line series and give the data adapters to them. Finally, give them to the chart.

LineSeries series1 = new LineSeries();
series1.setDataAdapter(dataAdapter1);
shinobiChart.addSeries(series1);

LineSeries series2 = new LineSeries();
series2.setDataAdapter(dataAdapter2);
shinobiChart.addSeries(series2);

Excellent, you now have your first ShinobiChart complete with data. But don’t go anywhere just yet, you still need to style the chart a bit to make it a little bit more exciting.

Tip: Some devices have to be told that the application requires hardware acceleration in order to display a chart. Simply add android:hardwareAccelerated="true" to the application element of the AndroidManifest.xml file in the ShinobiQuickStart project.

Basic Styling

The chart in its current state is a little plain. This section will build on the simple chart that you have and add some styling to it. So at this point your app should look a little something like this:

quickstart-nostyle

Not exactly thrilling! Let’s spruce it up a bit by adding a bit more color to the graph. To make it stand out a bit more we’ll give it a gradient fill that goes from a partially transparent color to a solid one. The first thing you’ll want to do is get hold of the series’ style object. Then set the fill style and the colors.

LineSeriesStyle style1 = series1.getStyle();
style1.setFillStyle(FillStyle.GRADIENT);
style1.setAreaColor(Color.argb(179, 94, 51, 95));
style1.setAreaColorGradient(Color.argb(255, 94, 51, 95));

LineSeriesStyle style2 = series2.getStyle();
style2.setFillStyle(FillStyle.GRADIENT);
style2.setAreaColor(Color.argb(179, 26, 96, 164));
style2.setAreaColorGradient(Color.argb(255, 26, 96, 164));

Tip: Here, for brevity, the Color class is being used to create a color int from the alpha, red, blue and green values supplied. A more Android-like approach would be to define the values in a resources file. See http://developer.android.com/guide/topics/resources/index.html for more information about resources and how to use them.

The sine waves come right up to the top and bottom of the chart. You can tell the Y axis to give itself a little more space with this:

yAxis.setDefaultRange(new NumberRange(-1.05, 1.05));

Finally, because you’ve made some styling changes, tell the chart to redraw itself:

shinobiChart.redrawChart();

Tip: As the above changes are being done effectively while the chart is being initialized, in the onCreate() method, it’s not strictly necessary to call redrawChart(). However, if you were to change some style values later on in the chart’s lifecycle those changes would not take effect until redrawChart() is called.

The styling changes you have made here are very basic. However, it is possible to radically change the way the chart looks through the use of advanced styling techniques.

Conclusion

So, there you have it, a quick guide to getting started with shinobicharts. By this point, you should have a chart that looks something like the screenshot below. If not, take a look at the shinobi-charts-quickstart project in the samples folder of the download bundle.

End result