Quick Start Guide – Objective C

Introduction

The following guide will get you up-and-running with the SEssentialsCarousel component as quickly as possible. In this guide, we will introduce you to the key features of the Carousel, including initial project setup and adding items to the Carousel with a datasource. It may help to follow along with our related code sample: CarouselGettingStarted.xcodeproj.

Start up Xcode and create a new project (File / New / Single View Application).

Within your newly created project, add a reference to the ShinobiEssentials framework, and the bundle which contains its resources. Instructions for doing this can be found in the first section of the EssentialsUserGuide.

Firstly, add an instance variable for the Carousel, keeping things simple for now by using the Linear 2D Carousel. Import the header in ViewController.h, and define the variable as follows:

#import <UIKit/UIKit.h>
#import <ShinobiEssentials/ShinobiEssentials.h>

@interface ViewController : UIViewController
{
    SEssentialsCarouselLinear2D *carousel;
}

@end

In ViewController.m, create a new Carousel instance as follows:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    carousel = [[SEssentialsCarouselLinear2D alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:carousel];
}

Using the Datasource

Now that your Carousel has been created, you can start adding some items. The number of items within the Carousel and the items themselves are provided via the datasource. For simplicity we will use the view controller as the datasource.

Start by adopting the SEssentialsCarouselDataSource protocol in ViewController.h:

@interface ViewController : UIViewController < SEssentialsCarouselDataSource >

This protocol has two required methods; numberOfItemsInCarousel:, and carousel:itemAtIndex:. The first method tells the Carousel the total number of items in your datasource, while the second method is called from the Carousel when it needs an item. Most applications will need to keep a reference to the items passed to the Carousel, so we will too.

Firstly, add an items array to the view controller, and populate it with some dummy UIView instances.

@interface ViewController ()
{
    NSMutableArray *items;
}
@end

@implementation ViewController

...

-(void)createViews
{
    items = [[NSMutableArray alloc] init];

    for (int i = 0; i < 20; i++)
    {
        UILabel *item = [[UILabel alloc] initWithFrame:CGRectMake(0, 0, 100, 100)];
        item.backgroundColor = [UIColor grayColor];
        item.text = [NSString stringWithFormat:@"%d", i];
        item.textAlignment = NSTextAlignmentCenter;
        [items addObject:item];
    }
}
@end

Update viewDidLoad to make use of this newly added method, and set the Carousel dataSource property to the view controller:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    [self createViews];
    carousel = [[SEssentialsCarouselLinear2D alloc] initWithFrame:_placeholder.bounds];
    carousel.dataSource = self;
    [_placeholder addSubview:carousel];
}

Finally, implement the methods in the SEssentialsCarouselDataSource protocol;

-(int)numberOfItemsInCarousel:(SEssentialsCarousel *)carousel
{
    return [items count];
}

-(UIView *)carousel:(SEssentialsCarousel *)carousel itemAtIndex:(int)index
{
    return [items objectAtIndex:index];
}

At this point, you can run the application, see your items displayed in a row, and pan back and forth through them.

Carousel

If you got stuck at any point, take a look at our related code sample: CarouselGettingStarted.xcodeproj