Mobiletuts+

Networking Made Easy With AFNetworking

Bart Jacobs — Wed, 16 May 2012 11:30:42 +0000

Networking is hard. There are various moving parts involved and many factors need to be considered to make it work. Fortunately, a number of open-source libraries have emerged over time to make networking easier. AFNetworking, created and maintained by the people of Gowalla, is one such library. This tutorial will introduce you to the AFNetworking framework while also showing how to query the iTunes Store API!

In this tutorial, I will introduce you to AFNetworking and show you a glimpse of what this library has to offer. After spending a few minutes with this library, you will notice that it was designed with ease of use in mind. It will not only speed up your development, but it will also take care of many painstaking networking tasks. We will build a simple application that queries the iTunes Store for movies that match the search term “harry”. The results of our query will be displayed in a table view.

Project Summary

The application we are about to build queries the iTunes Store Search API. In particular, we search the iTunes Store for movies that match the search term “harry”. If our query is successful, we process the results and display them in a table view. Each row represents a movie with a title, a director, and a thumbnail showing the movie artwork. Ready? Let’s get started.

Project Setup

Before we get our hands dirty with AFNetworking, we need to build a basic foundation. This means setting up our project, creating a table view, and adding an activity indicator view. We will show the activity indicator when our request is being processed by the iTunes Store. This will give the user that valuable extra bit of feedback that is often overlooked.

Create a new project in Xcode by selecting the Single View Application template from the list of templates. Name your application NetworkingIsFun, enter a company identifier, set “iPhone” for the device family, and uncheck “Use Storyboards”. You can leave the rest untouched, but make sure that Use Automatic Reference Counting is checked. Tell Xcode where you want to save your project and hit “Save”.

Adding the Table and Activity Indicator Views

Even though Interface Builder is great, I often build my interfaces programmatically, and that is what we will do in this tutorial as well. It will allow us to just focus on the code without being distracted by Interface Builder. Open ViewController.h and create three instance variables (ivars) as well as properties for these ivars. Since we are going to work with a table view, don’t forget to make your view controller conform to the UITableViewDataSource and UITableViewDelegate protocols. Your view controller’s header file should now look similar to the one below:

#import <UIKit/UIKit.h>

@interface ViewController : UIViewController <UITableViewDataSource, UITableViewDelegate> {
    UITableView *_tableView;
    UIActivityIndicatorView *_activityIndicatorView;
    NSArray *_movies;
}

@property (nonatomic, retain) UITableView *tableView;
@property (nonatomic, retain) UIActivityIndicatorView *activityIndicatorView;
@property (nonatomic, retain) NSArray *movies;

@end

If you are confused by the use of underscores, I recommend that you read about it here. Feel free to omit the underscores if you think it looks ugly or makes you feel uncomfortable. Apart from the underscores, there shouldn’t be any surprises. We declare our UITableView and UIActivityIndicatorView as well as an NSArray, which we will use to store the results that we get back from our search query. Ready? Let’s head over to our view controller’s implementation file.

Since we declared three properties in our header file, we need to synthesize their accessors in ViewController.m. Again, if the underscores confuse you, you can leave them out.

@synthesize tableView = _tableView, activityIndicatorView = _activityIndicatorView, movies = _movies;

In our viewDidLoad method, we set up our table and activity indicator views. The code below should be self-explanatory for the most part. If you have never set up a table view without using Interface Builder, you might see a few lines that are unfamiliar to you. Instead of wiring the table view up in Interface Builder, we take care of this in the viewDidLoad method. After calling the superclass’ viewDidLoad method, we initizalize our table view with a frame and a style, and we set our view controller as the data source and delegate of our table view. When our application launches, we hide our table view since we don’t have anything to show as long as our query hasn’t returned any results. Before adding the table view as a subview to our view controller’s view, we set its autoresizing mask. The autoresizing mask defines how the table view should be resized if the parent view – the view controller’s view to which we add the table view – changes in size. This happens when the device is rotated, for example. Confused? Don’t worry about it. It isn’t important for this application.

- (void)viewDidLoad {
    [super viewDidLoad];

    // Setting Up Table View
    self.tableView = [[UITableView alloc] initWithFrame:CGRectMake(0.0, 0.0, self.view.bounds.size.width, self.view.bounds.size.height) style:UITableViewStylePlain];
    self.tableView.dataSource = self;
    self.tableView.delegate = self;
    self.tableView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    self.tableView.hidden = YES;
    [self.view addSubview:self.tableView];

    // Setting Up Activity Indicator View
    self.activityIndicatorView = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleGray];
    self.activityIndicatorView.hidesWhenStopped = YES;
    self.activityIndicatorView.center = self.view.center;
    [self.view addSubview:self.activityIndicatorView];
    [self.activityIndicatorView startAnimating];

    // Initializing Data Source
    self.movies = [[NSArray alloc] init];
}

Setting up the activity indicator view is just as easy. We initialize the activity indicator view with a pre-defined style, set its hidesWhenStopped property to YES, and position it at the center of its parent view. After adding it to the view controller’s view, we start animating the activity indicator. The activity indicator will automatically display itself since we set its hidesWhenStopped property to YES.

At the end of our viewDidLoad method, we initialize the movies array. We will use it later to store the results of our search query.

Table View Protocols

For this tutorial, we will only implement two methods of the table view data source protocol. Both of these methods are required. This is the minimum implementation required to get our table view up and running. Even though we have set our view controller as the table view’s delegate, we won’t use any of the delegate methods in our application. If you have used a table view before, you won’t find any surprises in the method implementations shown below.

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    if (self.movies && self.movies.count) {
        return self.movies.count;
    } else {
        return 0;
    }
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    static NSString *cellID = @"Cell Identifier";

    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:cellID];

    if (!cell) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:cellID];
    }

    return cell;

}

In tableView:numberOfRowsInSection:, we need to return the number of rows in each section of the table view. In our example, the table view contains only one section (default), which makes everything a bit easier. First we check if our movies variable is not nil and we verify that it contains items. If both of these requirements are met, we return the number of items in the movies array, if not, we return zero.

Our tableView:cellForRowAtIndexPath: method is basic as well. We start by asking our table view whether there is a cell we can reuse. If this is not the case, we create a new cell with a style and reuse identifier. We end our implementation by returning our cell. This will do for now. You can now build and run your application. If you followed the steps correctly, you should see the activity indicator spinning like crazy and the table view should be hidden.

Adding AFNetworking to the Mix

Adding AFNetworking to your project is easy as pie. Start by downloading the library from GitHub and extract the archive. The archive contains a folder named AFNetworking, which contains the source files we need to include in our project. Drag this entire folder into your Xcode project and make sure that you check Copy items into the destination group’s folder (if needed) and add the source files to your target as well.

After adding the AFNetworking library to your project, build and run your application and watch as everything falls apart. What happened to our project? Why do we get all these warnings and errors? When we set up our Xcode project, we enabled Automatic Reference Counting (ARC). At the time of writing, the AFNetworking library does not use ARC. Don’t worry, though, we can still use this neat library with very little effort. All we need to do is tell the compiler that all the source files of the AFNetworking library do not use ARC. That’s it.

How do we do this? Select your project in the Project Navigator and select your target. Click the Build Phases tab in the top navigation and open the Compile Sources drawer. This table shows you all the source files the compiler will compile at compile time. The left column shows the names of the files and the right column shows the flags the compiler should know about.

You can see these flags as instructions or messages for the compiler. All you need to do is add a compiler flag to each source file of the AFNetworking library. To do this, select a source file from the list and double click the cell in the right column. A small window will appear in which you can add one or more compiler flags. In our case, simply type -fno-objc-arc and click Done. This flag tells the compiler that the source file does not use ARC. Make sure that you add this flag to all ten source files of the AFNetworking library.

Querying the iTunes Store Search API

AFNetworking is a library that can do a lot for you, but today we are only going to make use of two neat features. Before we can start using the AFNetworking classes, we need to add the following import statement just below the first import statement in your view controller’s implementation file.

#import "AFNetworking.h"

This import statement will give us access to all the AFNetworking classes. Head back to our view controller’s viewDidLoad method and add the following snippet immediately after the initialization of the movies array.

NSURL *url = [[NSURL alloc] initWithString:@"http://itunes.apple.com/search?term=harry&country=us&entity=movie"];
NSURLRequest *request = [[NSURLRequest alloc] initWithURL:url];

AFJSONRequestOperation *operation = [AFJSONRequestOperation JSONRequestOperationWithRequest:request success:^(NSURLRequest *request, NSHTTPURLResponse *response, id JSON) {
    NSLog(@"JSON");

} failure:^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error, id JSON) {
    NSLog(@"Request Failed with Error: %@, %@", error, error.userInfo);
}];

[operation start];

Let me explain what is going on. In the first line, we create the NSURL for our request. The string we use in the initialization conforms to the format that the iTunes Store Search API expects. The syntax of the Search API is fairly straightforward: The term we are searching for is “harry”, we restrict our search to the US iTunes Store, and we are looking only for movies. Easy, Right?

Next, we initialize a NSURLRequest and pass in the NSURL we just created. Then AFNetworking kicks in. AFNetworking contains a few very specialized classes that make our job very easy. The one we use here is AFJSONRequestOperation. This is a class that is designed to fetch and parse JSON data in the background. As the name implies, this class is a subclass of NSOperation or, to be more precise, one of the superclasses of this class inherits from NSOperation. The class lets you fetch the requested data and it also parses the JSON response. This means that we don’t have to deal with raw JSON. The data it returns is ready to use in your application. AFNetworking uses the built-in JSON parser on iOS 5 and falls back to its own JSON parser for older iOS versions.

Using AFJSONRequestOperation is easy since it has only one class method. This class method accepts three arguments: (1) a NSURLRequest, (2) a success block, executed when the request succeeds, and (3) a failure block, executed when the request fails. If blocks are new to you or you are not comfortable using them, then I recommend reading the tutorial by Collin Ruffenach about blocks and enumeration on Mobiletuts+. The success block takes three arguments: (1) our NSURLRequest, (2) the NSHTTPURLResponse of our request, and (3) a parsed JSON object. The failure block is almost identical. The only difference is that it takes an additional argument, an NSError that contains more information about what went wrong in case our request fails.

For testing purposes, we log the parsed JSON object to see what the iTunes Store Search API sends back to us. In addition, we also log the error in the failure block in case our request happens to fail. Before building and running our application once again, we need to start the operation by calling start on our operation object. Build and run your application and take a look at the output in the console.

If all went well, you will see the results of our request logged to the console. The parsed JSON object is a dictionary with two keys: (1) resultCount, which contains the number of results returned and (2) the actual results as an array of dictionaries. We not only logged the response to the console to see if our request was successful, we can now see the keys for each item in the results array. We will need these keys to display some information in our table view.

Populating the Table View

We are now ready to show the results in our table view. Replace the log statement in the success block with the snippet shown below. We start by assigning the results array of the response object to the movies array. The only thing left to do is hide the activity indicator by stopping it, showing the table view, and reloading the table view with the new data stored in the movies array.

self.movies = [JSON objectForKey:@"results"];
[self.activityIndicatorView stopAnimating];
[self.tableView setHidden:NO];
[self.tableView reloadData];

Next we amend the tableView:cellForRowAtIndexPath: method. Adjust your implementation to reflect the one below. After obtaining a reference to a cell, we query the movies array for the correct item, and update the labels of the cell with the title and director of the movie. Build and run your application.

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    static NSString *cellID = @"Cell Identifier";

    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:cellID];

    if (!cell) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:cellID];
    }

    NSDictionary *movie = [self.movies objectAtIndex:indexPath.row];
    cell.textLabel.text = [movie objectForKey:@"trackName"];
    cell.detailTextLabel.text = [movie objectForKey:@"artistName"];

    return cell;
}

You may have noticed that there are no thumbnails to be seen. Let’s fix that by adding three extra lines to our tableView:cellForRowAtIndexPath: method. Build and run your application.

NSURL *url = [[NSURL alloc] initWithString:[movie objectForKey:@"artworkUrl100"]];
NSData *data = [NSData dataWithContentsOfURL:url];
cell.imageView.image = [[UIImage alloc] initWithData:data];

Did you notice that our table view does not scroll smoothly. Why is that? As I mentioned in a previous tutorial, you always have to make sure that the main thread of your application remains responsive. In the current implementation of our tableView:cellForRowAtIndexPath: method, we are downloading the thumbnails on the main thread. This means the user interface cannot be updated until a request for a thumbnail is finished. Our thumbnails are tiny so the requests don’t take too long to complete, but imagine taking the same approach for larger assets. The user experience would be terrible. Even for our simple application, the user experience is unacceptable. However, we can remedy this with a very useful feature of the AFNetworking library.

AFNetworking to the Rescue

The creators of AFNetworking saw the need for downloading assets in the background as well. They therefore created a category for UIImageView. This category allows you to download images in the background with only two lines of code. This category is a true life saver. Have a look at the snippet below.

NSURL *url = [[NSURL alloc] initWithString:[movie objectForKey:@"artworkUrl100"]];
[cell.imageView setImageWithURL:url placeholderImage:[UIImage imageNamed:@"placeholder"]];

The first line of code stays the same. In the second line, we tell the image view where the thumbnail is located by passing an NSURL and we pass in a placeholder image, which is shown as long as our request has not returned a response. How cool is that? All we need to do is add a placeholder image to our project. This can be any image you want, but you can find the image I’ve used as a placeholder in the download file attached to this tutorial. Once you’ve added the placeholder image, build and run your application and test for yourself how smooth the table view scrolls!

Conclusion

Note that our application is very basic in its execution as it doesn’t do any caching and we can only search the iTunes Store for the term “harry” in the movies section. However, with very little effort you can make a neat application to search the iTunes Store in a more dynamic way.

I hope this tutorial has convinced you that the AFNetworking library is a great tool to have in your arsenal. It can do a lot more than what I showed you in this post, but the main goal of this tutorial is to get you up and running with AFNetworking and ready to use it in a real world scenario.

Corona SDK: Create a Balloon Game

Carlos Yanez — Tue, 15 May 2012 17:19:12 +0000

In this tutorial series, you’ll learn how to create a Bloons Inspired game. The objective of the game is to shoot at the balloons to pop them all…Read on!

Step 1: Application Overview

Using pre-made graphics we will code an entertaining game with Lua and the Corona SDK API’s.

The player will be able to shoot an acorn at the balloons by touching the screen to charge and releasing to shoot. You can modify the parameters in the code to customize the game.

Step 2: Target Device

The first thing we have to do is select the platform we want to run our app within. By doing so, we’ll be able to choose the size for the images we will use.

The iOS platform has these characteristics:

iPad: 1024x768px, 132 ppi
iPhone/iPod Touch: 320x480px, 163 ppi
iPhone 4: 960x640px, 326 ppi

Because Android is an open platform, there are many different devices and resolutions. A few of the more common screen characteristics are:

Google Nexus One: 480x800px, 254 ppi
Motorola Droid X: 854x480px, 228 ppi
HTC Evo: 480x800px, 217 ppi

In this tutorial, we’ll be focusing on the iOS platform with the graphic design, specifically developing for distribution to an iPhone/iPod touch, but the code presented here should apply to Android development with the Corona SDK as well.

Step 3: Interface

A simple and friendly interface will be used. This involves multiple shapes, buttons, bitmaps and more.

The interface graphic resources necessary for this tutorial can be found in the attached download.

Step 4: Export Graphics

Depending on the device you have selected, you may need to export the graphics in the recommended PPI. You can do that with your favorite image editor.

I used the Adjust Size… function in the Preview app on Mac OS X.

Remember to give the images a descriptive name and save them in your project folder.

Step 5: Sound

We’ll use Sound Effects to enhance the feeling of the game, you can find the sound used in this example in Soungle.com using the keyword pop.

Step 6: App Configuration

The config.lua file will be used to make the application go fullscreen across all devices. This file shows the original screen size and the method used to scale that content in case the app is run in a different resolution.

application =
{
    content =
    {
        width = 320,
        height = 480,
        scale = "letterbox"
    },
}

Step 7: Main.lua

Let’s write the application!

Open your prefered Lua editor (any Text Editor will work, but you won’t have syntax highlighting) and prepare to write your awesome app. Remember to save the file as main.lua in your project folder.

Step 8: Code Structure

We’ll structure our code as if it were a Class. If you know ActionScript or Java, you should find the structure familiar.

Necesary Classes

Variables and Constants

Declare Functions

    contructor (Main function)

    class methods (other functions)

call Main function

Step 9: Hide Status Bar

display.setStatusBar(display.HiddenStatusBar)

This code hides the status bar. The status bar is the bar on top of the device screen that shows the time, signal, and other indicators.

Step 10: Import Physics

We’ll use the Physics library to handle collisions. Use this code to import it:

local physics = require('physics')
physics.start()

Step 11: Game Background

A simple graphic is used as the background for the application interface, the next line of code stores it.

-- Graphics

-- [Background]

local bg = display.newImage('gameBg.png')

Step 12: Title View

This is the Title View, it will be the first interactive screen to appear in our game and these variables will store its components.

-- [Title View]

local titleBg
local playBtn
local creditsBtn
local titleView

Step 13: Credits View

This view will show the credits, version, and copyright of the game. This variable will be used to store it.

-- [CreditsView]

local creditsView

Step 14: Game View

The game view is composed by the TextFields that store the score, targets, and available acorns. It also displays the balloons, a restart button, and the squirrel that shoots the acorns. Add the following lines to your code to handle these elements. The squirrel and acorn graphics are from openclipart.org.

-- [Game View]

local gCircle
local squirrel
local infoBar
local restartBtn

-- [TextFields]

local scoreTF
local targetTF
local acornsTF

Step 15: Variables

These are the variables we’ll use. Read the comments in the code to know more about them, some of their names are self-explanatory so there will be no comment there.

local titleView
local credits
local acorns = display.newGroup() -- stores the acorns thrown
local balloons = {} -- stores the balloons in stage
local impulse = 0 -- used shot the acorn
local dir = 3 -- default direction of the acorn

Step 16: Code Review

Here is the full code written in this tutorial alongside with comments to help you identify each part:

-- Balloons Physics Game
-- Developed by Carlos Yanez

-- Hide Status Bar

display.setStatusBar(display.HiddenStatusBar)

-- Physics

local physics = require('physics')
physics.start()

-- Graphics

-- [Background]

local bg = display.newImage('gameBg.png')

-- [Title View]

local titleBg
local playBtn
local creditsBtn
local titleView

-- [Credits]

local creditsView

-- [Game View]

local gCircle
local squirrel
local infoBar
local restartBtn

-- [TextFields]

local scoreTF
local targetTF
local acornsTF

-- Load Sound

local pop = audio.loadSound('pop.mp3')

-- Variables

local titleView
local credits
local world
local acorns = display.newGroup()
local contacts
local balloons = {}
local impulse = 0
local dir = 3

Next Time…

In this part of the series you’ve learned about the interface and the basic setup of the game. Stay tuned for part two, where we will handle the logic of the application, buttons behavior, and more. See you next time!

iOS SDK: UIView Animations

C.A. Beninati — Mon, 14 May 2012 18:30:10 +0000

This iOS Quick Tip will teach you how to easily animate objects with UIKit. Whether you need sliding menus or flying monkeys, it’s easy to get it done, and this tip will show you how!

Animation in mobile applications can be a very important feature. From a practical, UX standpoint, it can let the user know that something has been changed or moved. From a more entertaining standpoint, it can move game sprites or tile maps around the screen, pulling the user into a fully interactive experience.

Fortunately, it’s very easy to get UIView objects moving around in your iOS apps, and you don’t even have to worry about calculating cryptic geometric equations or other such voodoo!

UIView Background

Before we get into the actual animation, we need to be familiar with the basic animation properties of UIView objects. The following is a list of all such properties as of iOS 5.1:

center (position on screen)
frame (position on screen, size, stretching…)
bounds (size, stretching)
alpha (transparency)
transform (rotation, scaling, basically any changes to the UIView)
backgroundColor

We don’t have enough space in this quick tip to go over all of these properties, but we will look at a few of the most common ones: center, alpha, and transform.

Moving UIViews

[UIView animateWithDuration:(NSTimeInterval) animations:^(void)animations]

In its most basic form, the above is all you need to animate a UIView. It’s pretty straightforward- pass a duration (how long the animation will last), and then the properties to be animated (the values that you want the UIView’s properties to have at the end of the animation).

For a quick example, if we have a UIView called “theView”, and we want to make it fade away until it’s invisible within a .5 second duration, we would call:

[UIView animateWithDuration:0.5f
                            animations:^{
		                    [theView setAlpha:0.0f];
                            }
];

And we’re done! The duration of the animation is set by the animateWithDuration: parameter, and an Objective-C block of specific animation actions is supplied to the animations: parameter. It’s just that easy!

Post-Animation Actions

Often, we’ll want to do something after the animation finishes. We’ll take a game for example. Let’s say we want to show a player that they’ve successfully completed an action. We’ll do this by making a star fly up into the left corner of the screen, and then a point will be added to their score. There are two things we’ll want to do once the star is finished flying:

Remove the star from the screen (we only want one star visible per point).
Add a point to the score.

To do this, we’ll call our animation method with a completion block, like this:

[UIView animateWithDuration:(NSTimeInterval)
                            animations:^(void)animations
                           completion:^(BOOL finished)completion
];

For example, if we have a UIImageView (i.e. a subclass of UIView) called “starImageView”, with an image of a star, and some numeric variable called “points”, we would call:

[UIView animateWithDuration:0.7f
                animations:^
                {
                        [starView setCenter:CGPointMake(0, 0)];
                }
                completion:^(BOOL finished)
                {
                        [starView removeFromSuperView];
                        points++;
                }
];

It’s worth noting that we’ll need to re-add our “starView” as a subview of our UIView if we want to run this animation again. You can see this in the sample code provided as an attachment to this Mobiletuts+ tutorial.

Going Beyond

Finally, there is a method that will let us define even greater detail on our animation process, including a delay before the animation runs, and setting the type of “easing” for our animation. These “easing” types can be found (and described) in the UIView.h header file as enums:

typedef enum {
    UIViewAnimationCurveEaseInOut,         // slow at beginning and end
    UIViewAnimationCurveEaseIn,            // slow at beginning
    UIViewAnimationCurveEaseOut,           // slow at end
    UIViewAnimationCurveLinear
} UIViewAnimationCurve;

I would encourage you to play around with those, by putting them into the “options” parameter of the following animation method:

[UIView animateWithDuration:(NSTimeInterval) delay:(NSTimeInterval) options:(UIViewAnimationOptions)animations:^(void)animations completion:^(BOOL finished)completion];

And once again, using our previous examples combined, we’ll delay our animation by 0.1 seconds, then begin moving it (slowly at first, then speeding up, and then going slowly again at the end). Also, while we’re moving our image, we’ll fade it out to 0% opacity. Finally, after our animation finishes, we’ll add a point to our score, and remove the image from our UIView.

[UIView animateWithDuration:0.6f
            delay:0.1f
            options:UIViewAnimationCurveEaseInOut
            animations:^{
          	        [starView setCenter:CGPointMake(0, 0)];
           	        [starView setAlpha:0.0f];
            }
            completion:^(BOOL finished){
                        [starView removeFromSuperview];
                        points++;
            }
];

Conclusion

As you can see, it’s super easy to get your UIViews animated, so take some time to play around with the different animatable UIView properties, and see what new things you can discover!

For extra practice, use the following command to rotate your image:

[starView setTransform:CGAffineTransformRotate(starView.transform, 90.0f)];

Now, see what other things are possible with animations for UIViews! And remember, there are several subclasses of UIView that can be animated with these same methods and properties, such as (but not limited to):

UIButton
UIImageView
UIButton
UILabel
UITableView
UIScrollView

Resources

The star image used in this tutorial was released with a GNU/GPL license from FindIcons

Working With CorePlot – Tuts+ Premium

Aron Bury — Sat, 12 May 2012 02:20:47 +0000

When working with data intensive applications, a developer must often do more than just show lists of data records in a table view. The CorePlot library will allow you to add stunning data visualizations to your applications. Find out how in this Tuts+ Premium series!

Tutorial Teaser

Today we will look at how to make the graph more useful to the user by specifying axis increments and how to format the increment labels. We’re going to look at different ways we can customize the look and feel of the graph. Finally, we’re going to discuss how to work with different plots on a single graph. Let’s get started!

Step 1: Setting Axis Increments

To modify the properties of an X and Y axis we work with the ‘CPTXYAxisSet’ and ‘CPTXAxis’ objects. Open the STLineGraphViewController.m file and go to the viewDidLoad method. Just below where we work with the plot Space enter the following code:

[[graph plotAreaFrame] setPaddingLeft:20.0f];
[[graph plotAreaFrame] setPaddingTop:10.0f];
[[graph plotAreaFrame] setPaddingBottom:20.0f];
[[graph plotAreaFrame] setPaddingRight:10.0f];
[[graph plotAreaFrame] setBorderLineStyle:nil];

NSNumberFormatter *axisFormatter = [[NSNumberFormatter alloc] init];
[axisFormatter setMinimumIntegerDigits:1];
[axisFormatter setMaximumFractionDigits:0];

CPTMutableTextStyle *textStyle = [CPTMutableTextStyle textStyle];
[textStyle setFontSize:12.0f];

CPTXYAxisSet *axisSet = (CPTXYAxisSet *)[graph axisSet];

CPTXYAxis *xAxis = [axisSet xAxis];
[xAxis setMajorIntervalLength:CPTDecimalFromInt(1)];
[xAxis setMinorTickLineStyle:nil];
[xAxis setLabelingPolicy:CPTAxisLabelingPolicyFixedInterval];
[xAxis setLabelTextStyle:textStyle];
[xAxis setLabelFormatter:axisFormatter];

CPTXYAxis *yAxis = [axisSet yAxis];
[yAxis setMajorIntervalLength:CPTDecimalFromInt(1)];
[yAxis setMinorTickLineStyle:nil];
[yAxis setLabelingPolicy:CPTAxisLabelingPolicyFixedInterval];
[yAxis setLabelTextStyle:textStyle];
[yAxis setLabelFormatter:axisFormatter];

Let’s go over everything above. First, we are working with a property of the graph called the ‘plotAreaFrame’. With this we are able to set the padding of the area where the graph is actually drawn and it allows us to see the axis labels (which were previously hidden). We then set the Border line style to nil to get rid of the border around the graph.

We then create an NSNumber formatter which we use to format the axis labels. We also create something called a ‘CPTMutableTextStyle’. When formatting lines, fill section and text for CorePlot objects we use objects such as CPTMutableTextStyle to do it. For now we only set the font size but we can set the font type and color as well.

We then get a CPTXYAxisSet object from our graph. This axisSet contains an xAxis and a yAxis (both objects of type ‘CPTXYAxis’). We then set a variety of properties on each axis. The major interval length sets what the interval at each main tick will be. We also want to get rid of the minor ticks so we set the line style to nil. We set the labellingPolicy to fixed intervals. We then set the text style for the CPTMutableTextStyle object we created earlier and the label formatter to the NSNumberFormatter we created.

Now try going to the student view and adding a student. Afterward you can go back to the graph and you should see it change. However, it still looks a bit bland…

Get the Full Series!

This tutorial series is available to Tuts+ Premium members only. Read a preview of this tutorial on the Tuts+ Premium web site or login to Tuts+ Premium to access the full content.

Joining Tuts+ Premium. . .

For those unfamiliar, the family of Tuts+ sites runs a premium membership service called Tuts+ Premium. For $19 per month, you gain access to exclusive premium tutorials, screencasts, and freebies from Mobiletuts+, Nettuts+, Aetuts+, Audiotuts+, Vectortuts+, and CgTuts+. You’ll learn from some of the best minds in the business. Become a premium member to access this tutorial, as well as hundreds of other advanced tutorials and screencasts.

Objective-C Categories

Aaron Crabtree — Thu, 10 May 2012 14:24:41 +0000

Categories provide the ability to add functionality to an object without subclassing or changing the actual object. A handy tool, they are often used to add methods to existing classes, such as NSString or your own custom objects.

Step 1: Set Up Your Project

Launch Xcode and click File > New > Project. Choose an iOS Single View Application from the window and click "Next." Name your product "Categories" and enter a name for your Company Identifier, such as "com.companyName.categories." Choose the iPhone device family and click "Next." Choose a location to store your project and click "Create."

Step 2: Create the Category

Now that your project is set up, let's create a category that adds additional functionality to the NSString class. Click File > New > File and choose a Cocoa Touch Objective-C category from the window. Click "Next." Name your category "RemoveNums" and select NSString from the "Category on" drop down menu (you may need to type this in manually). Click "Next" followed by "Create."

Declare the Category Method

Back in your Xcode project, click "NSString+RemoveNums.h" to view the new category's header file. Add the following code to the interface to declare the method.

@interface NSString (RemoveNums)
- (NSString *)removeNumbersFromString:(NSString *)string;
@end

Implement the Category Method

Click "NSString+RemoveNums.m" to view the category's implementation file. Add the following code to create a method that will remove all the numbers from an NSString. First we define an NSCharacterSet of the numbers zero through nine which we'll use as a reference to compare against the original input string. In this case, the original string "ABC 123" will have the numbers "123" removed from the string because the category method uses the NSString method stringByTrimmingCharactersInSet:.

- (NSString *)removeNumbersFromString:(NSString *)string
{
    NSString *trimmedString = nil;
    NSCharacterSet *numbersSet = [NSCharacterSet characterSetWithCharactersInString:@"0123456789"];
    trimmedString = [string stringByTrimmingCharactersInSet:numbersSet];
    return trimmedString;
}

Step 3: Import the Category

Click "ViewController.h" and import the category by adding the following code.

#import "NSString+RemoveNums.h"

Step 4: Test the Category

Click "ViewController.m" and add the following code to the viewDidLoad method. The local variable stringWithNums contains a combination of letters and numbers. The next line takes the string variable and runs it through the category method removeNumbersFromString. Finally, NSLog outputs the returned value of the newly trimmed string without any numbers.

NSString *stringWithNums = @"ABC 123";
NSLog(@"stringWithNums         --> %@",stringWithNums);
stringWithNums = [stringWithNums removeNumbersFromString:stringWithNums];
NSLog(@"trimmed stringWithNums --> %@",stringWithNums);

Step 5: Use the Category Method

Click Product > Run, or click the "Run" arrow in the top left corner, to test the code. Notice the console shows the original input string, "ABC 123," as well as the string after it has been altered by the category method and the numbers have been removed.

Conclusion

Subclassing is one way to add functionality to an object, but avoiding unnecessary subclassing by using a category will help reduce the amount of code and keep your projects more organized. There are a number of scenarios where using a category is beneficial. Share your category scenarios in the comments below.

Which Tuts+ Site Should We Launch Next?

David Appleyard — Thu, 10 May 2012 11:30:57 +0000

We’re planning our next few Tuts+ sites, and would love your opinion and advice on which topics you think we should cover next! We’d be really grateful if you could take a minute to answer our quick poll and share your thoughts…

Have Your Say

We’ve been considering lots of different ideas for our next Tuts+ sites over the past few weeks, and wanted to also ask the opinion of our awesome community!

A selection of different concepts are included in the poll to the right, along with the option for you to submit your own ideas as well.

The important thing to note is that these are just ideas. Some of these are close to making our final cut, and others aren’t… We’d love to hear what you think, to help guide our decision.

Thanks for taking the time to offer your suggestion — I can’t wait to see what you have to say!

Win a 6-Month Tuts+ Premium Membership

Our poll will be running for the next couple of weeks, and we’ll be choosing one respondent at random to receive a six-month Tuts+ Premium membership!

To be entered into the giveaway, just leave a comment on this post to go into a bit more detail about your site suggestion. We’ll choose one comment at random to win the Tuts+ Premium membership when the poll ends.

Best of luck!

Analyzing Android Network Traffic

Maria Garcia Cerdeno — Wed, 09 May 2012 13:54:02 +0000

Network traffic analysis can be a vital part of the software debugging and testing process. This tutorial will teach you how to monitor all incoming and outgoing traffic on an Android device in order to better debug your applications!

As a developer, one often has to build software that performs HTTP requests, sends messages, or grabs information from incoming or outgoing requests over the network. When these network transactions work from the very beginning, all is good; we are receiving exactly what is expected and what we are sending is proper formatted and with the correct values.

However, this frequently does not happen, and one needs to understand exactly what is being sent and received over the network in order to determine what has gone wrong. Who knows, maybe the request is not even being made and we are not aware of it! This is a circumstance in which knowing how to capture and analyze the network traffic becomes crucial.

Capturing network traffic for later analysis is good, but it’s even better if we are able to perform this analysis at the same time the capture is taking place. By doing so, one can know which request or response corresponds to each use case, thus making the analysis much easier. In the following steps, I will show you how to capture real time traffic from an Android device and pipe it to a network analyzer like Wireshark.

Step 1: Installing tcpdump

The first step is to install tcpdump on the device. tcpdump is a command-line utility that captures the traffic on a particular network device and dumps it to the filesystem. tcpdump can be downloaded from here.

Once the tcpdump binary has been downloaded, all we need to do is use adb to push the file onto the device. To be able to do so, your handset needs to be connected to and properly identified by your computer.

First things first, it is important that you update your path adding Android’s SDK platform-tools directory to it if you haven’t yet. In case you have never done it, there are clear instructions on how to do so on the android developers page. Ready? Open a terminal and type the following:

adb devices

The connected device should show up in a list. If this is not the case, make sure that it is correctly connected and that you have all the drivers needed for that specific handset.

See the device on the list? Great! We are now ready to push the tcpdump file onto it:

adb push /home/tcpdump /data/local

To perform the next few steps we need to gain root privileges on the device and make sure that tcpdump is executable:

adb shell
cd data/local
su
chmod 777 tcpdump

Step 2: Saving the Traffic Dump to File

Tcpdump can now be started from the same adb shell and the output saved to a file:

./tcpdump -s 0 -v -w out.pcap

The complete list of tcpdump options can be found in the man page of tcpdump.

Once the dump is completed, we can stop capturing the data. In order to do so, you simply need to press Ctrl+C. The resulting file can be pulled out of the device and saved locally, so that it can get analyzed using Wireshark.

adb pull /data/local/out.pcap /home/out.pcap

But this is not exactly what we wanted, is it? What we want is to be able to pipe it to Wireshark in real time! Relax, we are getting there.

Step 3: Piping Network Traffic to a Port

The process of capturing the network packets is basically the same in this case. However, instead of writing the datagrams to a file, we want to write them to the standard output, so that we can then redirect them using netcat to a specific port on the handset.

In order to do so, the tcpdump command has to change slightly:

adb shell "./data/local/tcpdump -n -s 0 -w - | nc -l -p 12345"

The traffic is now being redirected to the port 12345 in the handset.

Step 4: Installing Netcat

Before going any further, lets make sure that you have netcat installed, as we are going to need it. Type nc in a new console, hit enter and look at what happens. Do you get the standard message explaining how to use the command? Awesome, you are good to go. Skip the rest of this section and keep going!

Still reading? Well, I guess that means you do not have netcat installed after all. Do not panic, you can download it from here for Windows.

Step 5: Piping Traffic to Wireshark

Remember what we mentioned earlier regarding updating the path so that adb would be available? You want to do that with netcat and Wireshark as well.

Once this is done, we can use adb‘s forward option, which will forward the packets from the tcp port 12345 in the device to the tcp port 54321 on the PC. We will again use netcat to grab those incoming packets coming in through port 54321, and pipe them to Wireshark.

This is done in the following command, typed in a new console:

adb forward tcp:12345 tcp:54321 && nc 127.0.0.1 54321 | wireshark -k -S -i -

Note that the number of the port chosen is irrelevant. The only reason why different numbers have been chosen is to show how the different commands connect to each other. The same port number could have been used for both commands (or different numbers from the above, as long as the ports are not being used!) and then they would work just the same.

You need to make sure that Wireshark runs with the correct permissions. Otherwise, even when Wireshark gets opened, a popup will show up informing you of an exception.

Step 6: Making Life Easier

Once the different utilities have been set up, the process of capturing the network traffic and piping it into Wireshark is done through two commands, simultaneously running in two different terminals:

adb shell "./data/local/tcpdump -n -s 0 -w - | nc -l -p 12345"
adb forward tcp:12345 tcp:54321 && nc 127.0.0.1 54321 | wireshark -k -S -i -

Now, this process is still pretty manual. One has to manually open two terminals and type all those instructions, making sure nothing is left behind for this to work. This is a nuisance. Well, that problem is easily solved by putting these instructions onto a script, so that it does all the work for us.

Windows users can automate the process using the script in the download file attached to this post.

start adb shell "./data/local/tcpdump -n -s 0 -w - | nc -l -p 12345"
adb forward tcp:12345 tcp:54321 && nc 127.0.0.1 54321 | wireshark -k -S -i -

Notes for Mac Users

If you’ve been following this tutorial on a Mac, you are probably scratching your head, thinking why the above process does not really seem to be working for you. There are a couple of reasons why this might be the case. Let’s try to fix that.

First of all, make sure that you are using the right path of Wireshark! This might seem trivial, but is is not. You do not want to use the path to the app, but the whole path to the actual Wireshark executable (e.g. “/Applications/Wireshark.app/Contents/Resources/bin/wireshark”).

Fixed? Good! Just a couple more things to go. When invoking Wireshark through the command line, we are using a minus sign at the end. This represents the standard input and in Windows it will work just fine. However, this will not work on a Mac. Luckily, this can be substituted with the name of a pipe. You want to specify 2 (corresponding to lo0) as the pipe to use. Besides, you might need to grant super user permissions in order to be able to execute Wireshark. This is the resulting command that you want to use:

adb forward tcp:12345 tcp:54321 && nc 127.0.0.1 54321 | sudo wireshark -k -S -i 2

This is the perl script that will work for Mac users (it is also attached as a download to this post):


#!/usr/bin/perl

# Perform adb command on shell
# to check if the device is attached
$netstat = `adb shell 'netstat' 2>&1`;
if($netstat =~ m/error: device not found/)
{
die("Plug in your phone!\n");
}

# Gain root priviledges
open(SUDO, "|sudo echo ''");
close(SUDO);

# Redirect STDERR output to STDOUT
open STDERR, '>&STDOUT';

# Perform tcpdump and nc in background
open(COMMAND1, "(adb shell \"data/local/tcpdump -n -s 0 -w - | nc -l -p 12345\") |");

# Perform piping to wireshark
open(COMMAND2, "((adb forward tcp:12345 tcp:54321 && nc 127.0.0.1 54321 | sudo wireshark -k -S -i 2) &) 2>&1 > /dev/null |");

# Make sure the exit message appears after wireshark has been launched (hacky)
sleep(5);
print("Press ctrl-c to exit...");
<STDIN>;

Working With CorePlot – Tuts+ Premium

Aron Bury — Tue, 08 May 2012 04:12:26 +0000

When working with data intensive applications, a developer must often do more than just show lists of data records in a table view. The CorePlot library will allow you to add stunning data visualisations to your applications. Find out how in this Tuts+ Premium series!

Tutorial Teaser

Where We Left Off

Last time we introduced the CorePlot framework and discussed what it can do and how we can use it to enhance data visualisation in our applications. We also explored the sample application we’re going to create in the series and how to add CorePlot to our Application. For a code snapshot of where we left off last time, download the source code for this tutorial (otherwise feel free to use your existing code base and save yourself the download time!).

Step 1. Setting Things Up

Before we can create a graph we’ll need a view to do it in. We’re going to allow the user to click on a UIBarButtonItem in the ‘Students’ tab that will bring up an action sheet containing a list of graphs for the user to choose. Once a selection is made a modal view will display a graph with the relevant data on it.

We’re going to create a new group called ‘Graphing’ underneath the ‘StudentTracker’ group. Create a ‘Views’ and ‘Controllers’ group underneath this like in the ‘Student Listing’ and ‘Subject Listing’.

Create a new class called ‘STLineGraphViewController’ (subclassing UIViewController) in the ‘View Controllers’ group. When choosing where to add the files the best place to put them is the ‘Classes/Graphing/View Controllers’ folder (You will have to create the ‘Graphing/View Controllers’ directory).

We are going to come back and work on customizing this later. Right now we’re going to implement that code that allows the user to select a graph to look at.

First open up STStudentListViewController.h and add the ‘UIActionSheetDelegate’ and ‘STLineGraphViewControllerDelegate’ protocol declarations. This protocol doesn’t exist yet but we will create it later (Also make sure you import the ‘STLineGraphViewController.h’ file).

@interface STStudentListViewController : UIViewController <UITableViewDelegate, UITableViewDataSource, AddStudentViewControllerDelegate, UIActionSheetDelegate, STLineGraphViewControllerDelegate>

Next, open the .m file and implement the ‘actionSheet: clickedButtonAtIndex:’ method with the following code:

- (void)actionSheet:(UIActionSheet *)actionSheet clickedButtonAtIndex:(NSInteger)buttonIndex
{
    if (buttonIndex == 0)
    {
        STLineGraphViewController *lineGraphVC = [[STLineGraphViewController alloc] init];
        [lineGraphVC setModalTransitionStyle:UIModalTransitionStyleFlipHorizontal];
        [lineGraphVC setDelegate:self];
        [lineGraphVC setManagedObjectContext:[self managedObjectContext]];

        [self presentModalViewController:lineGraphVC animated:YES];
        [lineGraphVC release];
    }
}

This code shouldn’t need too much explaining. We are simply creating a LineGraph View Controller and presenting it modally. We set ourselves as the delegate so that we know when to dismiss the modal view. We also give the view controller a managed object context to work with so it can interface with core data. These last two methods will create a warning (or error if using ARC) because the properties don’t exist yet, but we will be creating them later.

Next we’ll create a method to call the action sheet and add a UITabBarItem to call it from. Add a method declaration in the .m interface called ‘graphButtonWasSelected:’:

@interface STStudentListViewController ()
@property (nonatomic, strong) NSArray *studentArray;

- (void)addStudent:(id)sender;
- (void)graphButtonWasSelected:(id)sender;
@end

Next, add the method implementation:

- (void)graphButtonWasSelected:(id)sender
{
UIActionSheet *graphSelectionActionSheet = [[[UIActionSheet alloc] initWithTitle:@"Choose a graph" delegate:self cancelButtonTitle:@"Cancel" destructiveButtonTitle:nil otherButtonTitles:@"Enrolment over time", nil] autorelease];

	[graphSelectionActionSheet showInView:[[UIApplication sharedApplication] keyWindow]];
}

Next we need to add a UIBarButtonItem for the user to select when they want to view the graph. We’ll do this in the viewDidLoad method underneath where we create the right bar button item:

[[self navigationItem] setLeftBarButtonItem:[[[UIBarButtonItem alloc] initWithTitle:@"Graphs" style:UIBarButtonItemStylePlain target:self action:@selector(graphButtonWasSelected:)] autorelease] animated:NO];

Finally, we need to implement a STLineGraphViewController protocol method that will tell the controller to dismiss the modal view when the user is done looking at the graph:

- (void)doneButtonWasTapped:(id)sender
{
    [self dismissModalViewControllerAnimated:YES];
}

Now we’re ready to start creating the graph!

Get the Full Series!

This tutorial series is available to Tuts+ Premium members only. Read a preview of this tutorial on the Tuts+ Premium web site or login to Tuts+ Premium to access the full content.

Joining Tuts+ Premium. . .

iOS SDK: NSNotification

Aaron Crabtree — Mon, 07 May 2012 14:47:27 +0000

In today’s quick tip, you’ll learn about the NSNotification class while building a demo project to monitor changes in the device orientation. Let’s get started!

Ordering from a food cart is a lot like working with an NSNotification. You walk up to the counter, place your order, get a number, and wait for your number to be called. You usually stand around with five other people who are waiting for their number to be called, too. And when the chef is finished preparing your meal, the person behind the counter calls your number, and you sit down to eat. With NSNotification, you become an observer for "your number," and when the object posting the notification is done "making your food," NSNotificationCenter calls your number so you can come get your "food". In this tutorial, instead of waiting for food, we're going to wait for the device to rotate and then send the current orientation to the observer. We'll talk about how to register to receive a notification, post a notification, and pass a string object along with the notification using userInfo.

Step 1: Set Up Your Project

Launch Xcode and click File > New > Project. Select an iOS Single View Application and click "Next". Name your product "Notifications" and enter a name for your Company Identifier, such as "com.companyName.notifications." Choose the iPhone device family and click "Next." Choose a location to store your project and click "Create."

Step 2: Register to Receive a Notification

Declare the methods used to post and receive the notification by typing the following code in the "ViewController.m" file.

@interface ViewController ()
    - (void)postNotificationWithString:(NSString *)orientation;
    - (void)useNotificationWithString:(NSNotification*)notification;
@end

Receiving the Notification

Now we can register the ViewController object to receive notifications. Type the following code into the viewDidLoad method.

NSString *notificationName = @"MTPostNotificationTut";

[[NSNotificationCenter defaultCenter]
    addObserver:self
    selector:@selector(useNotificationWithString:)
    name:notificationName
    object:nil];

There are four important parts of the NSNotificationCenter method addObserver:selector:name:object:. The argument for addObserver: is the object that wants to know when a certain notification happens. The argument for selector: is the method that gets called when the notification happens. The argument for name: is the title of the notification the observer wants to know about; it must be unique. The final piece of the method is object:. Its argument is the object attached to the notification and is often nil depending on the context of the notification.

Step 3: Post a Notification

Next we'll generate the logic for posting a notification. Type the following code in the "ViewController.m" file. The custom method postNotificationWithString: that was declared earlier takes one argument that represents the orientation of the device.

- (void)postNotificationWithString:(NSString *)orientation //post notification method and logic
{
    NSString *notificationName = @"MTPostNotificationTut";
    NSString *key = @"OrientationStringValue";
    NSDictionary *dictionary = [NSDictionary dictionaryWithObject:orientation forKey:key];
    [[NSNotificationCenter defaultCenter] postNotificationName:notificationName object:nil userInfo:dictionary];
}

There are three important parts of the NSNotificationCenter method postNotificationName:object:userInfo:. The argument for postNotificationName: is the title of the notification that was registered in the previous addObserver:selector:name:object: method. The argument for object:, again, is the object posting the notification and in this case is nil. The argument for userInfo is an NSDictionary that can be used to send additional information with the notification. userInfo can be nil, but in this instance we want to know the orientation of the device. In order to send it with the notification the information is packaged inside a dictionary.

Getting the Device's Orientation

In order to get the device's orientation, override the UIViewController method willAnimateRotationToInterfaceOrientation:duration: by typing the following code inside the braces. Each time the device is rotated, the method postNotificationWithString: is called and passes in either "Portrait" or "Landscape" depending on the device's orientation.

- (void)willAnimateRotationToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation duration:(NSTimeInterval)duration
{
    if (interfaceOrientation == UIInterfaceOrientationPortrait) {
        [self postNotificationWithString:@"Portrait"];
    }
    else {
        [self postNotificationWithString:@"Landscape"];
    }
}

Using the Notification

The custom method useNotificationWithString: was declared earlier and registered as the selector to be called when the notification happens. Type the following code which gets the device orientation string from userInfo. By using NSLog to display its value, each orientation change logs that another notification has been posted.

- (void)useNotificationWithString:(NSNotification *)notification //use notification method and logic
{
    NSString *key = @"OrientationStringValue";
    NSDictionary *dictionary = [notification userInfo];
    NSString *stringValueToUse = [dictionary valueForKey:key];
    NSLog(@"Device orientation --> %@",stringValueToUse);
}

Memory Management

Lastly, the observer must be removed when the object is deallocated. Type the following code in the dealloc method:

- (void)dealloc {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}

If you are not using ARC, you’ll need to explicitly call [super dealloc] as well, like so:

- (void)dealloc {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
    [super dealloc];
}

Step 4: Run the Project

Click Product > Run, or click the "Run" arrow in the top left corner. If you are using the iOS Simulator, click Hardware > Rotate Left to simulate device rotation. Notice that "Device orientation –> Landscape" is logged to the console.

Conclusion

Triggering methods in disconnected objects would require some hefty coding without notifications and the NSNotificationCenter. By adding observers to listen for specific posts to the notification center, your objects can communicate and pass data easily.

Corona SDK: Create an Alphabet Soup Game – Final Steps

Carlos Yanez — Thu, 03 May 2012 18:04:03 +0000

This entry is part 3 of 3 in the series Create an Alphabet Soup Game

Welcome to the final tutorial in our Alphabet Soup game series! In this tutorial, we’ll handle word selection and the steps necessary to build the final app.

Step 1: Hit Test Objects Function

We’ll use an excellent and useful function for collision detection without physics. You can find the original example and source at the Ansca Code Exchange website.

-- by jhocking
function hitTestObjects(obj1, obj2)
        local left = obj1.contentBounds.xMin <= obj2.contentBounds.xMin and obj1.contentBounds.xMax >= obj2.contentBounds.xMin
        local right = obj1.contentBounds.xMin >= obj2.contentBounds.xMin and obj1.contentBounds.xMin <= obj2.contentBounds.xMax
        local up = obj1.contentBounds.yMin <= obj2.contentBounds.yMin and obj1.contentBounds.yMax >= obj2.contentBounds.yMin
        local down = obj1.contentBounds.yMin >= obj2.contentBounds.yMin and obj1.contentBounds.yMin <= obj2.contentBounds.yMax
        return (left or right) and (up or down)
end

Step 2: Detect Letters

The next function will run when the user lifts the finger used to select the word. It will calculate the selected letters using the function created in the previous step.

function detectLetters:touch(e)
	-- Code...
end

Step 3: Get Selected Letters

A string variable is created to store the letters highlighted by the line.

	-- Get selected letters

		local selectedWord = ''

		for i = 1, tfs.numChildren do
			if(hitTestObjects(lines[lines.numChildren], tfs[i])) then
				selectedWord = selectedWord .. tfs[i].text
			end
		end

Step 4: Check If Word is On List

This code checks the generated string and compares it to the elements in the words table. If the word is found a sound is played and the counter rises.

-- Check if word is on list 

		for j = 0, 5 do
			if(selectedWord == L1[j]) then
				audio.play(bell)
				currentWords.text = currentWords.text .. ' ' .. selectedWord
				currentWords:setReferencePoint(display.TopLeftReferencePoint)
				currentWords.x = 5
				correct = correct + 1
			end
		end
	end

Step 5: Check for Game Over

When the counter reaches the same amount of words in the table an alert is called.

	if(correct == #L1) then
		alert()
	end

Step 6: Alert

The alert function stops the game, removes the listeners, and displays a game status message.

function alert()
	gameListeners('rm')

	alert = display.newImage('alert.png')
end

Step 7: Call Main Function

In order to initially start the game, the Main function needs to be called. With the above code in place, we’ll do that here:

Main()

Step 8: Loading Screen

The Default.png file is an image that will be displayed right when you start the application while iOS loads the basic data to show the Main Screen. Add this image to your project source folder, it will be automatically added by the Corona compiler.

Step 9: Icon

Using the graphics you created before you can now create a nice and good looking icon. The icon size for the non-retina iPhone icon is 57x57px, but the retina version is 114x114px and the iTunes store requires a 512x512px version. I suggest creating the 512×512 version first and then scaling down for the other sizes.

It doesn’t need to have the rounded corners or the transparent glare, iTunes and the iPhone will do that for you.

Step 10: Testing in Simulator

It’s time to do the final test. Open the Corona Simulator, browse to your project folder, and then click open. If everything works as expected, you are ready for the final step!

Step 11: Build

In the Corona Simulator go to File > Build and select your target device. Fill the required data and click build. Wait a few seconds and your app will be ready for device testing and/or submission for distribution!

Conclusion

Experiment with the final result and try to make your custom version of the game!

I hope you liked this tutorial series and find it helpful. Thank you for reading!