Introduction

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

Firstly we will create a basic grid, we will then create some simple data and finally we shall demonstrate how to display the data within the grid.

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.

Create a Basic Grid

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-grids-android-quickstart and a suitable Package name (we use com.shinobicontrols.grids.sample.quickstart 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 (shinobigrids supports Android API 14 and above so you can use the default value of API 14)
  5. Click Blank Activity and click Next
  6. Choose an appropriate name for your activity – this guide will assume the main activity is named QuickStartActivity
  7. Click Finish and your project will be created

Now that you have your new project set up follow the Android Studio import instructions to add a dependency to the shinobigrids library from your application. If you are using Eclipse then you can follow the Eclipse import instructions.

Add the ShinobiGridView

In the activity_quick_start.xml file of your application, which can be found in the res/layout folder, replace the TextView element with a ShinobiGridView:

<com.shinobicontrols.grids.core.ShinobiGridView
    android:id="@+id/my_grid"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

In QuickStartActivity.java we are going to obtain a reference to our ShinobiGridView. In the onCreate method add the following code:

ShinobiGridView shinobiGridView = (ShinobiGridView) findViewById(R.id.my_grid);

You will need to import the ShinobiGridView class.

Tip: In Android Studio use Alt+Enter to perform a quick fix such as importing a class

If you are working with the trial library you will have been given a trial license key. You’ll need to set this key on the ShinobiGridView as follows:

shinobiGridView.setTrialLicenseKey("<trial_license_key_here>");

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

Note: If you have purchased a licensed version of the library you will not need to set a trial license key. If you have purchased a license, please ensure you are referencing the licensed, rather than the trial version of the library within your project.

Create Some Data

So far when we run our project we see little more than an empty grid. It’s about time we added some data! Typically this data will be a collection of ‘data objects’ that are used within your application, this could be a collection of emails, contacts, flight details … all sorts of things! For the purposes of this quick-start guide we’ll create some dummy data, using the theme ofPerson objects.

Create a Person Object

Right-click on the package containing QuickStartActivity and select New > Java Class. Type Person as the Name and click OK. Modify Person.java so that it looks like the following:

public class Person {

    public final String name;
    public final int age;

    public Person(String name, int age) {
       this.name = name;
       this.age = age;
    }
}

Create a List of Person Objects

Now we have our Person object we need to instantiate some Persons with real data, and get them into a nice list which our grid can then use.

Back in QuickStartActivity.java, in the onCreate method add the following code:

final List<Person> people = new ArrayList<Person>();
people.add(new Person("Archie", 25));
people.add(new Person("Alexander", 15));
people.add(new Person("Jenny", 42));
people.add(new Person("Madison", 60));
people.add(new Person("Joanna", 32));

As before you will need to import some classes to make it compile.

Note: in the QuickStart sample app we use the PersonGenerator class to generate a longer list of Person objects for us but for brevity we’ve done it manually above!

Create Some Columns

Now we have our nice list of Person objects we need to create some columns in our grid, in order to display our Person data fields. Firstly we need to provide our ShinobiGridViewwith an AdapterSpec instance. The AdapterSpec object tells the grid how many rows it will contain. We then need to tell the ShinobiGridView how many columns we require, and what data they will contain.

Still in our QuickStartActivity.java, in the onCreate method, add the following code:

shinobiGridView.setAdapterSpec(new AdapterSpec() {
    @Override
    public int getRowCount() {
       return people.size();
    }
});

shinobiGridView.addColumn(Column.create(new TextColumnSpec("Name", new PropertyBinder<CharSequence>() {
    @Override
    public CharSequence bind(int rowIndex) {
       Person person = people.get(rowIndex);
       return person.name;
    }
})));

shinobiGridView.addColumn(Column.create(new TextColumnSpec("Age", new PropertyBinder<CharSequence>() {
    @Override
    public CharSequence bind(int rowIndex) {
       Person person = people.get(rowIndex);
       return Integer.toString(person.age);
    }
})));

As before you will need to import some classes to make it compile.

As we know our Person objects currently have two fields, name and age. As such we need to specify a column for each, and request it be added to our grid. In the above code you can see that for both name and age we call the addColumn method on our ShinobiGridView. This method expects a Column to be passed to it. To address this we use the Column class’create factory method.

This method in turn expects a ColumnSpec object. You may provide your own implementation of ColumnSpec when creating a Column, however, here we are using one of the pre-madeColumnSpecs provided by the shinobigrids library: TextColumnSpec. We pass to its constructor a title for the Column and an anonymous instance of a PropertyBinder object. As you can see here we implement the single bind method, in which we obtain and return the appropriate value from our Person.

The ShinobiGridView will, by default, size its rows and columns so that they all fit into the available space, and no space is wasted. In cases where there are many data items to display, their size is scaled down to fit, without the need for scroll bars. Conversely, when there are few data items, their size is increased, to give the appearance of ‘padding’. This avoids any large voids of open space in the ShinobiGridView, in favor of a uniform appearance.

In some cases, this behavior may not be suitable for your needs. As such you may like to tell the ShinobiGridView how you would like your rows and columns to be sized. You can set both a minimum and a default row height and column width. It is important to understand the relationship between the two values. A default row height/column width, if set will be honored, regardless of any minimum row height/column width that has been set. Where a default value has not been set, the ShinobiGridView will attempt to space the rows and columns out evenly, but will not reduce the row height beyond the minimum row height and the column width beyond the minimum column width.

For our quick start example application we wish to set the height of our rows to be 50dp (device independent pixels) and the width of our columns to be a minimum of 500dp. We define these values in an XML file (res/values/dimens.xml):

<resources>
    ...
    <dimen name="column_width">500dp</dimen>
    <dimen name="row_height">50dp</dimen>
</resources>

Setting the height of our rows and width of our columns is really quite simple. To set the default row height you simply provide a value, in pixels, to the setDefaultRowHeight method. By retrieving the row height from the resources, Android will do the dp to px conversion for us. Add the following to the onCreate method of the QuickStartActivity.java file:

int rowHeight = getResources().getDimensionPixelSize(R.dimen.row_height);
shinobiGridView.setDefaultRowHeight(rowHeight);

Setting the column width is very similar:

int columnWidth = getResources().getDimensionPixelSize(R.dimen.column_width);
shinobiGridView.setMinimumColumnWidth(columnWidth);

If you run your application you should have a fully functional ShinobiGridView, looking something similar to that below:

A basic grid