Quick Start Guide – Objective C

Introduction

The following guide will get you up-and-running with the SEssentialsProgressIndicator and SEssentialsActivityIndicator components as quickly as possible. In this guide, we will introduce you to the key features of the two Indicators, including initial project setup, the different implementations of the two components, and using callbacks effectively. You can follow along with the related code sample: IndicatorsGettingStarted.xcodeproj.

Creating an Indicator

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.

Open up ViewController.xib and add a new UIView component, as a subview of the ViewController’s main view. Bring up the Assistant Editor window, and drag from your new view into ViewController.h, adding an IBOutletproperty called placeholder. Import the SEssentialsActivityIndicator.h header as follows:

Open up ViewController.h, and import in the Activity Indicator header;

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

@interface ViewController : UIViewController
@property (strong, nonatomic) IBOutlet UIView *placeholder;
@end

Then in ViewController.m, create an Activity indicator, and add it to our placeholder in viewDidLoad;

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    SEssentialsActivityIndicator *actIndicator = [SEssentialsActivityIndicator
                                                    activityIndicatorOfType:SEssentialsIndicatorTypeRadialContinuous
                                                                  withFrame:_placeholder.bounds];
    [_placeholder addSubview:actIndicator];
}

The Activity Indicator

Now we have an activity indicator to display, we need to link it up to do something useful. We will add a button which runs a task, but takes a few seconds to do so, so we will show an Activity Indicator while the user waits. To do this, we need to add a UIButton in ViewController.xib, next to the placeholder. Open the Assistance Editor and drag the button from the xib file into the .h file, to create an Action on “Touch Up Inside” called activityTask. This should add the following to your ViewController.h;

@interface ViewController : UIViewController
- (IBAction)activityTask:(id)sender;
@property (strong, nonatomic) IBOutlet UIView *placeholder;
@end

We only want the Activity Indicator to appear while the user is waiting, so remove the viewDidLoad method completely. Instead, we will handle creating the Activity Indicator in activityTask, and remove it on a callback to a function called finishIndicator

-(void) finishIndicator:(SEssentialsProgressIndicator*)indicator
{
    /*
     * Code to finish up the Indicator's task goes here
     */
    [indicator removeFromSuperview];
    indicator = nil;
}

- (IBAction)activityTask:(id)sender
{
    //If we already have an indicator, don't create another one
    if ([self.placeholder.subviews count] > 0)
        return;

    //Create our indicator inside the placeholder
    SEssentialsActivityIndicator *actIndicator = [SEssentialsActivityIndicator
                                                  activityIndicatorOfType:SEssentialsIndicatorTypeRadialContinuous
                                                  withFrame:self.placeholder.bounds];
    actIndicator.style.trackColor = [UIColor colorWithWhite:0.1 alpha:1];
    [self.placeholder addSubview:actIndicator];

    //Set up our callback using threads
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
        /*
         * Put your long-running, more-exciting-than-sleeping-for-3-seconds task here!
         */
        [NSThread sleepForTimeInterval:3.0f];
        [self performSelectorOnMainThread:@selector(finishIndicator:) withObject:actIndicator waitUntilDone:NO];
    });
}

This method may see daunting a first, so we will take it step by step;

  • We first check if we already have an Activity Indicator, to stop ourselves creating lots of them
  • We then create the Activity Indicator, as we did in viewDidLoad before.
  • We then run our command on a different thread, demonstrating the real power of the Indicators. In our example, we just sleep for 3 seconds, but we could do anything at this stage.
  • Finally, we call back to the finishIndicator: method, which removes the indicator.

Running the app, you will have a button which spools for 3 seconds when pressed, before dismissing the indicator.

activity

The Progress Indicator

Activity Indicators can just run by themselves, but to use Progress Indicators, we need to do a little more work. The progress value of a Progress Indicator will not update automatically, so we need to set it. As before, add anotherUIButton and UIView in ViewController.xib, and use the Assistant Editor to link them both to ViewController.h to an Action called progressTask, and an Outlet called progressPlaceholder. You should have the following when you finish;

@interface ViewController : UIViewController
- (IBAction)progressTask:(id)sender;
- (IBAction)activityTask:(id)sender;
@property (strong, nonatomic) IBOutlet UIView *placeholder;
@property (strong, nonatomic) IBOutlet UIView *progressPlaceholder;
@end

In ViewController.h, we will implement the Progress Indicator much the same as before;

- (IBAction)progressTask:(id)sender
{
    //If we already have an indicator, don't create another one
    if ([self.progressPlaceholder.subviews count] > 0)
        return;

    //Create our indicator inside the placeholder
    SEssentialsProgressIndicator *progIndicator = [SEssentialsProgressIndicator
                                                   progressIndicatorOfType:SEssentialsIndicatorTypeLinearContinuous
                                                                 withFrame:self.progressPlaceholder.bounds];
    progIndicator.style.trackColor = [UIColor colorWithWhite:0.1 alpha:1];
    [self.progressPlaceholder addSubview:progIndicator];

    //Set up our callback using threads
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
        /*
         * Your long-running progressive task goes here, instead of what's between the //------// blocks
         */
        //--------------------------------------------------------------------//
        for (NSUInteger i = 0; i < 100; ++i)  {
            [NSThread sleepForTimeInterval:0.02f];

            [self performSelectorOnMainThread:@selector(updateProgressByStep:) withObject:progIndicator waitUntilDone:YES];
        }
        //--------------------------------------------------------------------//
        [self performSelectorOnMainThread:@selector(finishIndicator:) withObject:progIndicator waitUntilDone:NO];
    });
}

- (void)updateProgressByStep:(SEssentialsProgressIndicator*)progIndicator
{
    progIndicator.progress += 0.01f;
}

The only real difference from before is what we do inside the dispatch_async block. This time, we call to another function updateProgressByStep to update the progress of our Progress Indicator 1% per 0.02 seconds. When it reaches 100%, the for loop will finish, and we call finishIndicator as before, to make it disappear.

Progress

If you got stuck at any point, you can look at our related sample code: IndicatorsGettingStarted.xcodeproj.