Mobiletuts+

iOS SDK: Advanced UIImage Techniques

Akiel Khan — Thu, 23 May 2013 15:04:50 +0000

In this tutorial, we’ll look at some of the advanced features and usage patterns of the humble UIImage class in iOS. By the end of this tutorial, you will have learned the following: how to make images in code, how to create resizable images for UI elements like callouts, and how to create animated images.

Theoretical Overview

If you’ve ever had to display an image in your iOS app, you’re probably familiar with UIImage. It’s the class that allows you to represent images on iOS. This is by far the most common way of using UIImage and is quite straightforward: you have an image file in one of several standard image formats (PNG, JPEG, BMP, etc.) and you wish to display it in your app’s interface. You instantiate a new UIImage instance by sending the class message imageNamed:. If you have an instance of UIImageView, you can set its image property to the UIImage instance, and then you can stick in the image view into your interface by setting it as a subview to your onscreen view:

 UIImage *img = [UIImage imageNamed:filename];
 UIImageView *imgView = [[UIImageView alloc] initWithImage:img];
 // Set frame, etc. ...
 [self.view addSubview:imgView];

You can also carry out the equivalent of the above procedure directly in Interface Builder.

There are some other ways of instantiating an image, such as from a URL, or from an archived image that was stored as an NSData type, but we won’t focus on those aspects in this tutorial.

Before we talk about creating images in code, recall that at the most primitive level, we know what a 2D image really is: a two-dimensional array of pixel values. The region of memory representing the pixel array for an image is often referred to as its bitmap store. This is sometimes useful to keep in mind when making memory considerations. However, it is important to realize that a UIImage is really a higher level abstraction of an image than that of a pixel array, and one that has been optimized according to the demands and usage scenarios of a mobile platform. While it is theoretically possible to create an image by populating an entire pixel array with values, or to reach into an existing image’s bitmap and read or modify the value of an individual pixel, it is rather inconvenient to do so on iOS and is not really facilitated by the API. However since the majority of app developers seldom find real need to mess with images at the pixel level, it’s usually not an issue.

What UIImage (or more generally, UIKit and Core Graphics) does facilitate the developer to do is to create a new image by compositing existing images in interesting ways, or to generate an image by rasterizing a vector drawing constructed using UIKit‘s UIBezierPath class (or Core graphic’s CGPath... functions). If you want to write an app that lets the user create a collage of their pictures, it’s easy to do with UIKit and UIImage. If you’ve developed, say, a freehand drawing app and you want to let the user save his creation, then the simplest approach would involve extracting a UIImage from the drawing context. In the first section of this tutorial, you’ll learn exactly how both of these ideas can be accomplished!

It is important to keep in mind that a UIImage constructed this way is no different than an image obtained by opening a picture from the photo album, or downloading from the Internet: it can be saved to the archive or uploaded to the photo album or displayed in a UIImageView.

Image resizing is an important type of image manipulation. Obviously you’d like to avoid enlarging an image, because that causes the image’s quality and sharpness to suffer. However, there are certain scenarios in which resizable images are needed and there actually are sensible ways to do so that don’t degrade the quality of the image. UIImage caters for this situation by permitting images that have an inner resizable area and “edge insets” on the image borders that resize in a particular direction, or don’t resize at all. Furthermore, the resizing can be carried out either by tiling or stretching the resizable portions for two somewhat different effects that can be useful in different situations.

The second part section of the implementation will show a concrete implementation of this idea. We’ll write a nifty little class that can display any amount of text inside a resizable image!

Finally, we’ll talk a bit about animating images with UIImage. As you can probably guess, this means “playing” a series of images in succession, giving rise to the illusion of animation (much like the animated GIFs that you see on the Internet). While this might seem a bit limited, in simple situations UIImage‘s animated image support might be just what you need, and all it takes is a couple of lines of code to get up and running. That’s what we’ll look at in the third and final section of this tutorial! Time to roll up our sleeves and get to work!

1. Starting a New Project

Create a new iOS project in Xcode, with the “Empty Application” template. Call it “UIImageFun”. Check the option for Automatic Reference Counting, but uncheck the options for Core Data and Unit Tests.

Creating a new Xcode project

A small note, before we proceed: this tutorial uses several sets of images, and to obtain these you’ll need to click where it says “Download Source Files” at the top of this page. After downloading and unzipping the archive, drag the folder named “Images” into the Project Navigator – the leftmost tab in the lefthand pane in Xcode. If the left pane isn’t visible, then press the key combination ⌘ + 0 to make it visible and ensure the leftmost tab – whose icon looks like a folder – is selected.

Drag and drop the Images folder into your project

Ensure that the “Copy items into destination group’s folder (if needed)” option in the dialog box is checked”.

Ensure that the files get copied to your project folder

The downloaded file also contains the complete Xcode project with the images already added to the project, in case you get stuck somewhere.

2. Creating an Image in Code

Create a new file for an Objective-C class, call it ViewController and make it a subclass of UIViewController. Ensure that the options related to iPad and XIB are left unchecked.

Make a new view controller

Replace all the code in ViewController.m with the following:

#import "ViewController.h"
@interface ViewController ()
{
    UIImage *img;
    UIImageView *iv;
    NSMutableArray *ivs;
}
@end
@implementation ViewController
- (void)viewDidLoad
{
    [super viewDidLoad];
    // (1) Creating a bitmap context, filling it with yellow as "background" color:
    CGSize size = CGSizeMake(self.view.bounds.size.width, self.view.bounds.size.height);
    UIGraphicsBeginImageContextWithOptions(CGSizeMake(size.width, size.height), YES, 0.0);
    [[UIColor yellowColor] setFill];
    UIRectFill(CGRectMake(0, 0, size.width, size.height));
    // (2) Create a circle via a bezier path and stroking+filling it in the bitmap context:
    UIBezierPath *bezierPath = [UIBezierPath bezierPathWithArcCenter:CGPointMake(size.width/2, size.height/2) radius:140 startAngle:0 endAngle:2 * M_PI clockwise:YES];
    [[UIColor blackColor] setStroke];
    bezierPath.lineWidth = 5.0;
    [bezierPath stroke];
    [[UIColor redColor] setFill];
    [bezierPath fill];
    // (3) Creating an array of images:
    NSArray *rocks = @[[UIImage imageNamed:@"rock1"],
                       [UIImage imageNamed:@"rock2"],
                       [UIImage imageNamed:@"rock3"],
                       [UIImage imageNamed:@"rock4"],
                       [UIImage imageNamed:@"rock5"],
                       [UIImage imageNamed:@"rock6"],
                       [UIImage imageNamed:@"rock7"],
                       [UIImage imageNamed:@"rock8"],
                       [UIImage imageNamed:@"rock9"]];
    // (4) Drawing rocks in a loop, each chosen randomly from the image set and drawn at a random position in a circular pattern:
    for ( int i = 0; i < 100; i++)
    {
        int idx = arc4random() % rocks.count;
        NSLog(@"idx = %d", idx);
        int radius = 100;
        int revolution = 360;
        float r = (float)(arc4random() % radius);
        float angle = (float)(arc4random() % revolution);
        float x = size.width/2 + r * cosf(angle * M_PI/180.0);
        float y = size.height/2 + r * sinf(angle * M_PI/180.0);
        CGSize rockSize = ((UIImage *)rocks[idx]).size;
        [rocks[idx] drawAtPoint:CGPointMake(x-rockSize.width/2, y-rockSize.height/2)];
    }
    // (5) Deriving a new UIImage instance from the bitmap context:
    UIImage *fImg = UIGraphicsGetImageFromCurrentImageContext();
    // (6) Closing the context:
    UIGraphicsEndImageContext();
    // (7) Setting the image view's image property to the created image, and displaying
    iv = [[UIImageView alloc] initWithImage:fImg];
    [self.view addSubview:iv];
}
@end

Configure the App Delegate to use an instance of ViewController as the root view controller by replacing the code in AppDelegate.m with the following:

#import "AppDelegate.h"
#import "ViewController.h"
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.window.rootViewController = [[ViewController alloc] init];
    self.window.backgroundColor = [UIColor whiteColor];
    [self.window makeKeyAndVisible];
    return YES;
}
@end

Let’s examine the code for viewDidLoad: where all the action happens. Referring to the numbers in the code comments:

We want to start by drawing an image, which means we need a “canvas”. In proper terminology, this is called an image context (or bitmap context). We create one by calling the UIGraphicsBeginImageContextWithOptions() function. This function takes as arguments a CGSize (which we’ve set to the size of our view controller’s view, meaning the entire screen), a BOOL saying whether the context is opaque or not. (An opaque context is more efficient, but you can’t “see through” it. Since there’s nothing of interest underneath our context, we set it to YES), A scale factor, which is a float that we set to 0.0 (a value that ensures device-specific scale). Depending on whether or not the device has a Retina display, the scale factor will be set to 2.0 or 1.0 respectively. I’ll talk a bit more about the scale factor shortly, but for a comprehensive discussion, I’ll refer you to the official documentation (specifically, the “Points vs. Pixels” section in the “Drawing and Printing Guide for iOS”).
Once we create an image context this way, it becomes the current context. This is important because to draw with UIKit, we must have a current drawing context where all the (implicit) drawing happens. We now set a fill color (for the current context) and fill in a rectangle (the size of the entire context).
We now create a UIBezierPath instance in the shape of a circle, which we stroke with a thick outline and fill with a different color. This concludes the drawing portion of our image creation.
We create an array of images, with each image instantiated via the imageNamed: initializer of UIImage. It’s important to observe here that we have two sets of rock images: rock1.png, rock2.png,… and rock1@2x.png, rock2@2x.png, the latter being twice the resolution of the former. One of the great features of UIImage is that at runtime the imageNamed: method automatically looks for an image with suffix @2x (presumed to be of double resolution) on a Retina device. If one is available, it is used! If the suffixed image is absent or if the device is non-Retina, than the standard image is used. Note that we don’t specify the suffix of the image in the initializer. The use of single- and double-resolution images in conjunction with the device-dependent scale (as a result of setting scale to 0.0) ensures the actual size of the objects on screen will be the same. Naturally, the Retina images will be more crisp because of the higher pixel density.

Normally the two sets of images would be the same (apart from the resolution).

We compose our image in a loop by placing a randomly chosen rock from our picture set at a random point (constrained to lie in a circle) in each iteration. The UIImage method drawAtPoint: draws the chosen rock image at the specified point into the current image context.
We now extract a new UIImage object from the contents of the current image context, by calling UIGraphicsGetImageFromCurrentImageContext().
The call to UIGraphicsEndImageContext() ends the current image context and cleans up memory.
Finally, we set the image we created as the image property of our UIImageView and display it on screen.

Build and run. The output should look like the following, only randomized differently:

UIImage created by drawing and composition

By testing on both Retina and non-Retina devices or by changing the device type in the Simulator under the menu, you can ensure that the rocks are flipped with one in respect to the other. I reiterate that I only did this so we could easily confirm that the right set of images was being picked at runtime – normally, there’s no reason for you to do this!

To recap – at the risk of belaboring the point – we created a new image (a UIImage object) by compositing together images we already have on top of a drawing we drew.

On to the next part of the implementation!

3. Resizable Images

Consider the figure below.

A callout (left), deconstructed to show how the image might be resized sensibly (right)

The left image shows a callout (“speech bubble”) similar to the one seen in many messaging apps. Obviously, we would like the callout to expand or shrink according to the amount of text in it. Also, we’d like to use a single image from which we can generate callouts of any size. If we magnify the entire callout equally in all directions, the entire image gets pixellated or blurred (depending on the resizing algorithm being used). However, notice that the way the callout image has been designed, it can be expanded in certain directions without loss of quality, by simply replicating (tiling) pixels as we go along. The corner shapes can’t be resized without changing image quality, but on the other hand, the middle is just a block of pixels of uniform colour that can be made any size we like. The top and bottom sides can be stretched horizontally without losing quality, and the left and right sides vertically. All this is shown in the image on the right hand side.

Luckily for us, UIImage has a couple of methods for creating resizable images of this sort. The one we’re going to use is resizableImageWithCapInsets:. Here the “cap insets” represent the dimensions of the non-stretchable corners of the image (starting from the top margin and moving counterclockwise) and are encapsulated in a struct of type UIEdgeInsets composed of four floats:

typedef struct {
 float top, left, bottom, right;
 } UIEdgeInsets;

The figure below should clarify what these numbers represent:

Let’s exploit resizable UIImages to create a simple class that lets us enclose any amount of text in a resizable image!

Create a NSObject subclass called Note and enter the following code into Note.h and Note.m respectively:

 #import <Foundation/Foundation.h>
@interface Note : NSObject
@property (nonatomic, readonly) NSString *text;
@property (nonatomic, readonly) UIImageView *noteView;
- (id)initWithText:(NSString *)text fontSize:(float)fontSize noteChrome:(UIImage *)img edgeInsets:(UIEdgeInsets)insets maximumWidth:(CGFloat)width topLeftCorner:(CGPoint)corner;
@end

#import "Note.h"
@implementation Note
- (id)initWithText:(NSString *)text fontSize:(float)fontSize noteChrome:(UIImage *)img edgeInsets:(UIEdgeInsets)insets  maximumWidth:(CGFloat)width topLeftCorner:(CGPoint)corner
{
    if (self = [super init])
    {
#define LARGE_NUMBER 10000 // just a large (but arbitrary) number because we don't want to impose any vertical constraint on our note size
        _text = [NSString stringWithString:text];
        CGSize computedSize = [text sizeWithFont:[UIFont systemFontOfSize:fontSize] constrainedToSize:CGSizeMake(width, LARGE_NUMBER) lineBreakMode:NSLineBreakByWordWrapping];
        UILabel *textLabel = [[UILabel alloc] init];
        textLabel.font = [UIFont systemFontOfSize:fontSize];
        textLabel.text = self.text;
        textLabel.numberOfLines = 0; // unlimited number of lines
        textLabel.lineBreakMode = NSLineBreakByWordWrapping;
        textLabel.frame = CGRectMake(insets.left, insets.top, computedSize.width , computedSize.height);
        _noteView = [[UIImageView alloc] initWithFrame:CGRectMake(corner.x, corner.y, textLabel.bounds.size.width+insets.left+insets.right, textLabel.bounds.size.height+insets.top+insets.bottom)];
        _noteView.image = [img resizableImageWithCapInsets:insets];
        [_noteView addSubview:textLabel];
    }
    return self;
}
@end

The initializer method for Note, -initWithText:fontSize: noteChrome:edgeInsets:maximumWidth:topLeftCorner: takes several parameters: the text string to be displayed, the font size, the note “chrome” (which is the resizable UIImage that will surround the text), its cap insets, the maximum width the note’s image view may have, and the top-left corner of the note’s frame.

Once initialised, the Note class’ noteView property (of type UIImageView) is the user interface element that we’ll display on the screen.

The implementation is quite simple: we exploit a very useful method from the NSString‘s category on UIKit, sizeWithFont:constrainedToSize:lineBreakMode:, that computes the size that a block of text will occupy on the screen, given certain parameters. Once we’ve done that, we construct a text label (UILabel) and populate it with the provided text. By taking into account the inset sizes and the calculated text size, we assign the label an appropriate frame, as well as make our noteView‘s image large enough (using the resizableImageWithCapInsets method) so that the label fits comfortably on top of the interior (resizable) area of the the image.

In the figure below, the image on the left represents what a typical note containing a few lines worth of text in it would look like.

Using the smallest possible image for constructing a resizable image

Note that the interior has nothing of interest. We can actually “pare” the image to its bare minimum (as shown on the right) by getting rid of all the pixels in the interior with image editing software. In fact, in the documentation Apple recommends that for best performance, the interior area should be tiled 1 x 1 pixels. That’s what the funny little image on the right represents, and that’s the one we’re going to be passing to our Note initializer. Make sure that it got added to your project as squeezednote.png when you dragged the Images folder to your project.

In ViewController.m, enter the #import "Note.h" statement at the top. Comment out the previous viewDidLoad: form and enter the following:

- (void)viewDidLoad
{
    [super viewDidLoad];
    NSString *text1 = @"Hi!";
    NSString *text2 = @"I size myself according to my content!";
    NSString *text3 = @"Standard boring random text: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.";
    UIImage *noteChrome = [UIImage imageNamed:@"squeezednote"];
    UIEdgeInsets edgeInsets = UIEdgeInsetsMake(37, 12, 12, 12);
    Note *note1 = [[Note alloc] initWithText:text1 fontSize:25.0 noteChrome:noteChrome edgeInsets:edgeInsets maximumWidth:300 topLeftCorner:CGPointMake(10, 10)];
    Note *note2 = [[Note alloc] initWithText:text2 fontSize:30.0 noteChrome:noteChrome edgeInsets:edgeInsets maximumWidth:300 topLeftCorner:CGPointMake(200, 10)];
    Note *note3 = [[Note alloc] initWithText:text3 fontSize:16.0 noteChrome:noteChrome edgeInsets:edgeInsets maximumWidth:300 topLeftCorner:CGPointMake(10, 200)];
    [self.view addSubview:note1.noteView];
    [self.view addSubview:note2.noteView];
    [self.view addSubview:note3.noteView];
}

We’re simply creating Note objects with a different amount of text. Build, run, and observe how nicely the “chrome” around the note resizes to accommodate the text inside its boundaries.

Nicely resizing note

For the sake of comparison, here’s what the output would look like if “squeezednote.png” were configured as a “normal” UIImage (i.e., instantiated with imageNamed:, and that resized equally in all directions).

Badly resizing note

Admittedly, we wouldn’t actually use a “minimal” image like “squeezednote” unless we were using resizable images in the first place, so the effect shown in the previous screenshot is greatly exaggerated. However, the blurring problem would definitely be there.

On to the final part of the tutorial!

4. Animated Images

By an “animated image”, I actually mean a sequence of individual 2D images that are displayed in succession. This is basically just the sprite animation that is used in most 2D games. UIImage has an initializer method animatedImageNamed:duration: to which you pass a string that represents the prefix of the sequence of images to be animated, so if your images are named “robot1.png”, “robot2.png”, …, “robot60.png”, you’d simply pass in the string “robot” to this method. The duration of the animation is also passed in. That’s pretty much it! When the image is added to a UIImageView, it continuously animates on screen. Let’s implement an example.

Comment out the previous version of viewDidLoad: and enter the following version:

 - (void)viewDidLoad
{
    [super viewDidLoad];
    ivs = [NSMutableArray array];
    img = [UIImage animatedImageNamed:@"explosion" duration:2.0];
    UITapGestureRecognizer *tap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(explosion:)];
    [self.view addGestureRecognizer:tap];
}
- (void)explosion:(UITapGestureRecognizer *)t
{
    CGPoint loc = [t locationInView:self.view];
    for (UIImageView *v in ivs)
    {
        if ([v pointInside:[v convertPoint:loc fromView:self.view] withEvent:nil])
        {
            [ivs removeObject:v];
            [v removeFromSuperview];
            return;
        }
    }
    UIImageView *v = [[UIImageView alloc] initWithImage:img];
    v.center = loc;
    [ivs addObject:v];
    [self.view addSubview:v];
}

We added a set of PNG images to our project, explosion1.png through explosion81.png which represent an animated sequence of a fiery explosion. Our code is quite simple: we detect a tap on the screen and either place a new explosion animation at the tap point, or if there was already an explosion going on at that point, we remove it. Note that the essential code consists of just creating an animated image via animatedImageNamed: to which we pass the string @"explosion" and a float value for the duration.

You’ll have to run the app on the simulator or a device yourself in order to enjoy the fireworks display, but here’s an image that captures a single frame of the action, with several explosions going on at the same time:

Animated explosions

Admittedly, if you were developing a high-paced action game such as a shoot ‘em up or a side scrolling platformer, then UIImage‘s support for animated images would seem quite primitive and wouldn’t be your go-to approach for implementing animation. Really, that’s not what the UIImage has been built for, but in other (less demanding) scenarios, it might be just the ticket! Since the animation runs continuously until you remove the animated image or the image view from the interface, you could make the animations stop after a prescribed time interval by sending a delayed message with – performSelector:withObject:afterDelay: or use an NSTimer.

Conclusion

In this tutorial, we looked at some useful but less commonly-known features of the UIImage class that can occasionally come in handy. I suggest you take a look at the UIImage Class Reference because there are more options to some of the features we discussed in this tutorial. For example, images can be composited using one of several blending options. Resizable images can be configured in one of two resizing modes, tiling (which is the one we used implicitly) or stretching. Even animated images can have insets. We didn’t talk about the underlying CGImage opaque type that UIImage wraps around. You need to deal with CGImages if you program at the Core Graphics level, which is the C-based API that sits one level below UIKit in the iOS framework. Core Graphics is more powerful than UIKit to program with – but, on the flip side, not quite as easy. We also didn’t talk about images created with data from a Core Image object, as that would make more sense in a Core Image tutorial.

Hope you found this tutorial useful. Keep coding!

Android SDK: Create a Barcode Reader

Sue Smith — Tue, 21 May 2013 11:30:28 +0000

In this tutorial, we’ll use the ZXing (Zebra Crossing) library to carry out barcode scanning within an Android app. We’ll call on the resources in this open source library within our app, retrieving and processing the returned results.

Since we’re using the ZXing library, we don’t need to worry about users without the barcode scanner installed, because the integration classes provided will take care of this for us. By importing the ZXing integration classes into our app, we can make user scans easier and focus our development efforts on handling the scan results. In a follow-up series coming soon, we’ll develop a book scanning app where we’ll build on the app we created in this tutorial. We’ll also add support for Google Books API so that we can display information about scanned books.

1. Create a New Android Project

Step 1

In Eclipse, create a new Android project. Enter your chosen application, project, and package names. Let Eclipse create a blank activity for you, with the name of your choice for both the activity and its layout.

Step 2

Open your main layout file. With the default settings, Eclipse starts your layout with a Relative Layout object, which you can leave as is. Inside of it, replace the existing content (typically a Text View) with a button.

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
	xmlns:tools="http://schemas.android.com/tools"
	android:layout_width="match_parent"
	android:layout_height="match_parent" >
	<Button android:id="@+id/scan_button"
		android:layout_width="wrap_content"
		android:layout_height="wrap_content"
		android:layout_centerHorizontal="true"
		android:text="@string/scan" />
</RelativeLayout>

After the button, add two Text Views in which we will output scanning information.

<TextView
	android:id="@+id/scan_format"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:textIsSelectable="true"
	android:layout_centerHorizontal="true"
	android:layout_below="@id/scan_button" />
<TextView
	android:id="@+id/scan_content"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:textIsSelectable="true"
	android:layout_centerHorizontal="true"
	android:layout_below="@id/scan_format" />

Add the button text string to your “res/values/strings” XML file.

<string name="scan">Scan</string>

The user will press the button to scan. When the app receives a result from the barcode scanning operation, it will display the scan content data and format name in the two Text Views.

2. Add ZXing to Your Project

Step 1

ZXing is an open source library that provides access to tested and functional barcode scanning on Android. Many users will already have the app installed on their devices, so you can simply launch the scanning Intents and retrieve the results. In this tutorial we are going to use the Scanning via Intent method to make scanning easier. This method involves importing a couple of classes into your app and lets ZXing take care of instances where the user does not have the scanner installed. If the user doesn’t have the barcode scanner installed, they’ll be prompted to download it.

Tip: Since ZXing is open source, you can import the source code into your projects in its entirety. However, this is really only advisable if you need to make changes to its functionality. You can also compile the project and include its JAR file in your own apps if you prefer. For most purposes, using Scanning via Intent is a reliable and easy to implement options, plus your users will have access to the most recent version of the ZXing app.

In Eclipse, add a new package to your project by right-clicking the “src” folder and choosing “New“, then “Package“, and entering “com.google.zxing.integration.android” as the package name.

Step 2

Eclipse offers several ways to import existing code into your projects. For the purposes of this tutorial, you’ll probably find it easiest to simply create the two required classes and copy the code from ZXing. Right-click your new package, choose “New” then “Class” and enter “IntentIntegrator” as the class name. You can leave the other default settings the way they are. Once you’ve created this class, do the same for the other class we’ll be importing, giving it “IntentResult” as its class name.

Copy the code from both classes in the ZXing library and paste it into the class files you created. These are IntentIntegrator and IntentResult. Refer to the source code download if you’re in any doubt about where the various files and folders should be or what should be in them.

You can now import the ZXing classes into your main Activity class.

import com.google.zxing.integration.android.IntentIntegrator;
import com.google.zxing.integration.android.IntentResult;

Go ahead and add the other import statements we’ll use for this tutorial. Bear in mind that Eclipse may have already added some for you.

import android.os.Bundle;
import android.app.Activity;
import android.content.Intent;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.TextView;
import android.widget.Toast;

Feel free to have a look at the content of the two ZXing classes. It’s fairly straightforward, but the details of the barcode scanning processing are carried out elsewhere in the library. These two classes really act as an interface to the scanning functionality.

3. Do Some Scanning

Step 1

Let’s implement scanning when the user clicks the button we added. In your app’s main activity class, the default onCreate method entered by Eclipse should look something like this.

protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
}

Above this method, add the following instance variables to represent the button and two Text Views we created in the layout file.

private Button scanBtn;
private TextView formatTxt, contentTxt;

In onCreate, after the existing code, instantiate these variables using the ID values we specified in the XML.

scanBtn = (Button)findViewById(R.id.scan_button);
formatTxt = (TextView)findViewById(R.id.scan_format);
contentTxt = (TextView)findViewById(R.id.scan_content);

Next, add a listener to the button so that we can handle presses.

scanBtn.setOnClickListener(this);

Extend the opening line of the class declaration to implement the OnClickListener interface.

public class MainActivity extends Activity implements OnClickListener

Step 2

Now we can respond to button clicks by starting the scanning process. Add an onClick method to your activity class.

public void onClick(View v){
//respond to clicks
}

Check whether the scanning button has been pressed inside this method.

if(v.getId()==R.id.scan_button){
//scan
}

Inside this conditional block, create an instance of the Intent Integrator class we imported.

IntentIntegrator scanIntegrator = new IntentIntegrator(this);

Now we can call on the Intent Integrator method to start scanning.

scanIntegrator.initiateScan();

At this point, the scanner will start if it’s installed on the user’s device. If not, they’ll be prompted to download it. The results of the scan will be returned to the main activity where scanning was initiated, so we’ll be able to retrieve it in the onActivityResult method.

Tip: When you call the initiateScan method, you can choose to pass a collection of the barcode types you want to scan. By default, the method will scan for all supported types. These include UPC-A, UPC-E, EAN-8, EAN-13, QR Code, RSS-14, RSS Expanded, Data Matrix, Aztec, PDF 417, Codabar, ITF, Codes 39, 93, and 128. The ZXing library also includes barcode scanning options that we’re not going to cover in this tutorial. You can check the project out at Google Code for more info.

4. Retrieve Scanning Results

Step 1

When the user clicks the scan button, the barcode scanner will launch. When they scan a barcode, it will return the scanned data to the onActivityResult method of the calling activity. Add the method to your main activity class.

public void onActivityResult(int requestCode, int resultCode, Intent intent) {
//retrieve scan result
}

Inside the method, try to parse the result into an instance of the ZXing Intent Result class we imported.

IntentResult scanningResult = IntentIntegrator.parseActivityResult(requestCode, resultCode, intent);

Step 2

As with any data being retrieved from another app, it’s vital to check for null values. Only proceed if we have a valid result.

if (scanningResult != null) {
//we have a result
}

If scan data is not received (for example, if the user cancels the scan by pressing the back button), we can simply output a message.

else{
	Toast toast = Toast.makeText(getApplicationContext(),
		"No scan data received!", Toast.LENGTH_SHORT);
	toast.show();
}

Back in the if block, let’s find out what data the scan returned. The Intent Result object provides methods to retrieve the content of the scan and the format of the data returned from it. Retrieve the content as a string value.

String scanContent = scanningResult.getContents();

Retrieve the format name, also as a string.

String scanFormat = scanningResult.getFormatName();

Step 3

Now your program has the format and content of the scanned data, so you can do whatever you want with it. For the purpose of this tutorial, we’ll just write the values to the Text Views in our layout.

formatTxt.setText("FORMAT: " + scanFormat);
contentTxt.setText("CONTENT: " + scanContent);

Run your app on a device instead of an emulator so that you can see the scan functioning. Try scanning a book or any other barcode you might have.

When the scan is initiated, the user is taken to the ZXing app to scan a barcode.

The scan results are returned to the app.

Conclusion

In this tutorial, we’ve run through the process of facilitating barcode scanning within Android apps using the ZXing library. In your own apps, you might want to carry out further processing on the retrieved scan results, such as loading URLs or looking the data up in a third party data source. In the follow-up to this tutorial, we’ll use the barcode scanning functionality to create a book scanning app that will allow us to retrieve data about scanned books from the Google Books API.

Create a Weather App with Forecast – API Integration

Bart Jacobs — Mon, 20 May 2013 19:42:53 +0000

In the first article of this series, we laid the foundation of the project by setting up the project and creating the application’s structure. In this article, we leverage the AFNetworking library to interact with the Forecast API.

Introduction

In the first installment of this series, we laid the foundation of our weather application. Users can add their current location and switch between locations. In this tutorial, we will use the AFNetworking library to ask the Forecast API for the weather data of the currently selected location.

If you want to follow along, you will need a Forecast API key. You can obtain an API key by registering as a developer at Forecast. Registration is free, so I encourage you to try out the Forecast weather service. You can find your API key at the bottom of your dashboard (figure 1).

Figure 1: Obtaining Your API Key

1. Subclassing `AFHTTPClient`

As I wrote earlier in this article, we will be using the AFNetworking library for communicating with the Forecast API. There are several options when working with AFNetworking, but to make our application future proof, we will opt for the AFHTTPClient class. This class is designed for consuming web services, such as the Forecast API. Even though we will only access one API endpoint, it is still useful to make use of the AFHTTPClient as you will learn in a few moments.

It is recommended to create an AFHTTPClient subclass for each web service. Because we already added AFNetworking to our project in the previous tutorial, we can immediately start subclassing AFHTTPClient.

Step 1: Create the Class

Create a new Objective-C class, name it MTForecastClient, and make it a subclass of AFHTTPClient (figure 2).

Figure 2: Subclassing AFHTTPClient

Step 2: Creating a Singleton Object

We will adopt the singleton pattern to make it easier to use the MTForecastClient class in our project. This means that only one instance of the class is alive at any one time for the lifetime of the application. Chances are that you are already familiar with singleton pattern as it is a common pattern in many object-oriented programming languages. At first glance, the singleton pattern seems very convenient, but there are a number of caveats to watch out for. You can learn more about singletons by reading this excellent article by Matt Gallagher.

Creating a singleton object is pretty straightforward in Objective-C. Start by declaring a class method in MTForecastClient.h to provide public access to the singleton object (see below).

#import "AFHTTPClient.h"
@interface MTForecastClient : AFHTTPClient
#pragma mark -
#pragma mark Shared Client
+ (MTForecastClient *)sharedClient;
@end

The implementation of sharedClient may look daunting at first, but it isn’t that difficult once you understand what’s going on. We first declare two static variables, (1) predicate of type dispatch_once_t and (2) _sharedClient of type MTForecastClient. As its name implies, predicate is a predicate that we use in combination with the dispatch_once function. When working with a variable of type dispatch_once_t, it is important that it is declared statically. The second variable, _sharedClient, will store a reference to the singleton object.

The dispatch_once function takes a pointer to a dispatch_once_t structure, the predicate, and a block. The beauty of dispatch_once is that it will execute the block once for the lifetime of the application, which is exactly what we want. The dispatch_once function doesn’t have many uses, but this is definitely one of them. In the block that we pass to dispatch_once, we create the singleton object and store a reference in _sharedClient. It is safer to invoke alloc and init separately to avoid a race condition that could potentially lead to a deadlock. Euh … what? You can read more about the nitty gritty details on Stack Overflow.

+ (MTForecastClient *)sharedClient {
    static dispatch_once_t predicate;
    static MTForecastClient *_sharedClient = nil;
    dispatch_once(&predicate, ^{
        _sharedClient = [self alloc];
        _sharedClient = [_sharedClient initWithBaseURL:[self baseURL]];
    });
    return _sharedClient;
}

The important thing to understand about the implementation of the sharedClient class method is that the initializer, initWithBaseURL:, is invoked only once. The singleton object is stored in the _sharedClient static variable, which is returned by the sharedClient class method.

Step 3: Configuring the Client

In sharedClient, we invoke initWithBaseURL:, which in turn invokes baseURL, another class method. In initWithBaseURL:, we set a default header, which means that the client adds this header to every request that it sends. This is one of the advantages of working with the AFHTTPClient class. In initWithBaseURL:, we also register an HTTP operation class by invoking registerHTTPOperationClass:. The AFNetworking library provides a number of specialized operations classes. One of these classes is the AFJSONRequestOperation class, which makes interacting with a JSON API very easy. Because the Forecast API returns a JSON response, the AFJSONRequestOperation class is a good choice. The registerHTTPOperationClass: method works similar to how the registerClass:forCellReuseIdentifier: of the UITableView class works. By telling the client what operation class we want to use for interacting with the web service, it will instantiate instances of that class for us under the hood. Why this is useful will become clear in a few moments.

- (id)initWithBaseURL:(NSURL *)url {
    self = [super initWithBaseURL:url];
    if (self) {
        // Accept HTTP Header
        [self setDefaultHeader:@"Accept" value:@"application/json"];
        // Register HTTP Operation Class
        [self registerHTTPOperationClass:[AFJSONRequestOperation class]];
    }
    return self;
}

The implementation of baseURL is nothing more than a convenience method for constructing the client’s base URL. The base URL is the URL that the client uses to reach the web service. It is the URL without any method names or parameters. The base URL for the Forecast API is https://api.forecast.io/forecast//. The API key is part of the URL as you can see. This may seem insecure and it actually is. It isn’t difficult for someone to grab the API key so it is advisable to work with a proxy to mask the API key. Because this approach is a bit more involved, I won’t cover this aspect in this series.

+ (NSURL *)baseURL {
    return [NSURL URLWithString:[NSString stringWithFormat:@"https://api.forecast.io/forecast/%@/", MTForecastAPIKey]];
}

You may have noticed in the implementation of baseURL that I have used another string constant for storing the API key. This might seem unnecessary since we only use the API key in one location. However, it is good practice to store application data in one location or in a property list.

#pragma mark -
#pragma mark Forecast API
extern NSString * const MTForecastAPIKey;

#pragma mark -
#pragma mark Forecast API
NSString * const MTForecastAPIKey = @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

Step 4: Adding a Helper Method

Before we move on, I would like to extend the MTForecastClient class by adding a helper or convenience method that will make it easier to query the Forecast API. This convenience method will accept a location and a completion block. The completion block is executed when the request finishes. To make working with blocks easier, it is recommended to declare a custom block type as shown below. If you still feel uncomfortable using blocks, then I recommend reading this great article by Akiel Khan.

The block takes two arguments, (1) a boolean indicating whether the query was successful and (2) a dictionary with the response from the query. The convenience method, requestWeatherForCoordinate:completion:, takes the coordinates of a location (CLLocationCoordinate2D) and a completion block. By using a completion block, we can avoid creating a custom delegate protocol or fall back to using notifications. Blocks are a perfect fit for this type of scenario.

#import "AFHTTPClient.h"
typedef void (^MTForecastClientCompletionBlock)(BOOL success, NSDictionary *response);
@interface MTForecastClient : AFHTTPClient
#pragma mark -
#pragma mark Shared Client
+ (MTForecastClient *)sharedClient;
#pragma mark -
#pragma mark Instance Methods
- (void)requestWeatherForCoordinate:(CLLocationCoordinate2D)coordinate completion:(MTForecastClientCompletionBlock)completion;
@end

In requestWeatherForCoordinate:completion:, we invoke getPath:success:failure:, a method declared in AFHTTPClient. The first argument is the path that is appended to the base URL that we created earlier. The second and third arguments are blocks that are executed when the request succeeds and fails, respectively. The success and failure blocks are pretty simple. If a completion block was passed to requestWeatherForCoordinate:completion:, we execute the block and pass a boolean value and the response dictionary (or nil in the failure block). In the failure block, we log the error from the failure block to the console to facilitate debugging.

- (void)requestWeatherForCoordinate:(CLLocationCoordinate2D)coordinate completion:(MTForecastClientCompletionBlock)completion {
    NSString *path = [NSString stringWithFormat:@"%f,%f", coordinate.latitude, coordinate.longitude];
    [self getPath:path parameters:nil success:^(AFHTTPRequestOperation *operation, id response) {
        if (completion) {
            completion(YES, response);
        }
    } failure:^(AFHTTPRequestOperation *operation, NSError *error) {
        if (completion) {
            completion(NO, nil);
            NSLog(@"Unable to fetch weather data due to error %@ with user info %@.", error, error.userInfo);
        }
    }];
}

You may be wondering what the response object in the success blocks is or references. Even though the Forecast API returns a JSON response, the response object in the success block is an NSDictionary instance. The benefit of working with the AFJSONHTTPRequestOperation class, which we registered in initWithBaseURL:, is that it accepts the JSON response and automatically creates an object from the response data, a dictionary in this example.

2. Querying the Forecast API

Step 1: Amend `setLocation:`

Armed with the MTForecastClient class, it is time to query the Forecast API and fetch the weather data for the currently selected location. The most suitable place to do this is in the setLocation: method of the MTWeatherViewController class. Amend the setLocation: method as shown below. As you can see, all we do is invoke fetchWeatherData, another helper method.

- (void)setLocation:(NSDictionary *)location {
    if (_location != location) {
        _location = location;
        // Update User Defaults
        NSUserDefaults *ud = [NSUserDefaults standardUserDefaults];
        [ud setObject:location forKey:MTRainUserDefaultsLocation];
        [ud synchronize];
        // Post Notification
        NSNotification *notification1 = [NSNotification notificationWithName:MTRainLocationDidChangeNotification object:self userInfo:location];
        [[NSNotificationCenter defaultCenter] postNotification:notification1];
        // Update View
        [self updateView];
        // Request Location
        [self fetchWeatherData];
    }
}

Have you ever wondered why I use so many helper methods in my code? The reason is simple. By wrapping functionality in helper methods, it is very easy to reuse code in various places of a project. The main benefit, however, is that it helps battle code duplication. Code duplication is something you should always try to avoid as much as possible. Another advantage of using helper methods is that it makes your code much more readable. By creating methods that do one thing and providing a well chosen method name, it is easier to quickly read and process your code.

Step 2: Sending the Request

It is time to put the SVProgressHUD library to use. I really like this library because it is so simple to use without cluttering the project's code base. Take a look at the implementation of fetchWeatherData below. We start by showing the progress HUD and then pass a structure (CLLocationCoordinate2D) to the convenience method we created earlier, requestWeatherForCoordinate:completion:. In the completion block, we hide the progress HUD and log the response to the console.

- (void)fetchWeatherData {
    // Show Progress HUD
    [SVProgressHUD showWithMaskType:SVProgressHUDMaskTypeGradient];
    // Query Forecast API
    double lat = [[_location objectForKey:MTLocationKeyLatitude] doubleValue];
    double lng = [[_location objectForKey:MTLocationKeyLongitude] doubleValue];
    [[MTForecastClient sharedClient] requestWeatherForCoordinate:CLLocationCoordinate2DMake(lat, lng) completion:^(BOOL success, NSDictionary *response) {
        // Dismiss Progress HUD
        [SVProgressHUD dismiss];
        NSLog(@"Response > %@", response);
    }];
}

Before you build and run your application, import the header file of the MTForecastClient class in MTWeatherViewController.m.

#import "MTWeatherViewController.h"
#import "MTForecastClient.h"
@interface MTWeatherViewController () <CLLocationManagerDelegate> {
    BOOL _locationFound;
}
@property (strong, nonatomic) NSDictionary *location;
@property (strong, nonatomic) CLLocationManager *locationManager;
@end

What happens when the device is not connected to the web? Have you thought about that scenario? In terms of user experience, it is good practice to notify the user when the application is unable to request data from the Forecast API. Let me show how to do this with the AFNetworking library.

3. Reachability

There are a number of libraries that provide this functionality, but we will stick with AFNetworking. Apple also provides sample code, but it is a bit outdated and doesn't support ARC.

AFNetworking has truly embraced blocks, which is definitely one of the reasons that this library has become so popular. Monitoring for reachability changes is as simple as passing a block to setReachabilityStatusChangeBlock:, another method of the AFHTTPClient class. The block is executed every time the reachability status changes and it accepts a single argument of type AFNetworkReachabilityStatus. Take a look at the updated initWithBaseURL: method of the MTForecastClient class.

- (id)initWithBaseURL:(NSURL *)url {
    self = [super initWithBaseURL:url];
    if (self) {
        // Accept HTTP Header
        [self setDefaultHeader:@"Accept" value:@"application/json"];
        // Register HTTP Operation Class
        [self registerHTTPOperationClass:[AFJSONRequestOperation class]];
        // Reachability
        __weak typeof(self)weakSelf = self;
        [self setReachabilityStatusChangeBlock:^(AFNetworkReachabilityStatus status) {
            [[NSNotificationCenter defaultCenter] postNotificationName:MTRainReachabilityStatusDidChangeNotification object:weakSelf];
        }];
    }
    return self;
}

To avoid a retain cycle, we pass a weak reference to the singleton object in the block that we pass to setReachabilityStatusChangeBlock:. Even if you use ARC in your projects, you still need to be aware of subtle memory issues like this. The name of the notification that we post is another string constant declared in MTConstants.h/.m.

extern NSString * const MTRainReachabilityStatusDidChangeNotification;

NSString * const MTRainReachabilityStatusDidChangeNotification = @"com.mobileTuts.MTRainReachabilityStatusDidChangeNotification";

The reason for posting a notification in the reachability status change block is to make it easier for other parts of the application to update when the device's reachability changes. To make sure that the MTWeatherViewController class is notified of reachability changes, instances of the class are added as an observer for the notifications sent by the Forecast client as shown below.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Initialize Location Manager
        self.locationManager = [[CLLocationManager alloc] init];
        // Configure Location Manager
        [self.locationManager setDelegate:self];
        [self.locationManager setDesiredAccuracy:kCLLocationAccuracyKilometer];
        // Add Observer
        NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
        [nc addObserver:self selector:@selector(reachabilityStatusDidChange:) name:MTRainReachabilityStatusDidChangeNotification object:nil];
    }
    return self;
}

This also means that we need to remove the instance as an observer in the dealloc method. This is a detail that is often overlooked.

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

The implementation of reachabilityStatusDidChange: is pretty basic at the moment. We will update its implementation once we create the application's user interface.

- (void)reachabilityStatusDidChange:(NSNotification *)notification {
    MTForecastClient *forecastClient = [notification object];
    NSLog(@"Reachability Status > %i", forecastClient.networkReachabilityStatus);
}

4. Refreshing Data

Before we wrap this post up, I want to add two additional features, (1) fetching weather data whenever the application becomes active and (2) adding the ability to manually refresh weather data. We could implement a timer that fetches fresh data every hour or so, but this is not necessary for a weather application in my opinion. Most users will launch the application, take a look at the weather and put the application in the background. It is therefore only necessary to fetch fresh data when the user launches the application. This means that we need to listen for UIApplicationDidBecomeActiveNotification notifications in the MTWeatherViewController class. As we did for monitoring reachability changes, we add instances of the class as observers of notifications of type UIApplicationDidBecomeActiveNotification.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Initialize Location Manager
        self.locationManager = [[CLLocationManager alloc] init];
        // Configure Location Manager
        [self.locationManager setDelegate:self];
        [self.locationManager setDesiredAccuracy:kCLLocationAccuracyKilometer];
        // Add Observer
        NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
        [nc addObserver:self selector:@selector(applicationDidBecomeActive:) name:UIApplicationDidBecomeActiveNotification object:nil];
        [nc addObserver:self selector:@selector(reachabilityStatusDidChange:) name:MTRainReachabilityStatusDidChangeNotification object:nil];
    }
    return self;
}

In applicationDidBecomeActive:, we verify that location is set (not nil) because this won't always be true. If the location is valid, we fetch the weather data.

- (void)applicationDidBecomeActive:(NSNotification *)notification {
    if (self.location) {
        [self fetchWeatherData];
    }
}

I have also amended fetchWeatherData to only query the Forecast API if the device is connected to the web.

- (void)fetchWeatherData {
    if ([[MTForecastClient sharedClient] networkReachabilityStatus] == AFNetworkReachabilityStatusNotReachable) return;
    // Show Progress HUD
    [SVProgressHUD showWithMaskType:SVProgressHUDMaskTypeGradient];
    // Query Forecast API
    double lat = [[_location objectForKey:MTLocationKeyLatitude] doubleValue];
    double lng = [[_location objectForKey:MTLocationKeyLongitude] doubleValue];
    [[MTForecastClient sharedClient] requestWeatherForCoordinate:CLLocationCoordinate2DMake(lat, lng) completion:^(BOOL success, NSDictionary *response) {
        // Dismiss Progress HUD
        [SVProgressHUD dismiss];
        // NSLog(@"Response > %@", response);
    }];
}

Let's add a button to the weather view controller that the user can tap to manually refresh the weather data. Create an outlet in MTWeatherViewController.h and create a refresh: action in MTWeatherViewController.m.

#import <UIKit/UIKit.h>
#import "MTLocationsViewController.h"
@interface MTWeatherViewController : UIViewController <MTLocationsViewControllerDelegate>
@property (weak, nonatomic) IBOutlet UILabel *labelLocation;
@property (weak, nonatomic) IBOutlet UIButton *buttonRefresh;
@end

- (IBAction)refresh:(id)sender {
    if (self.location) {
        [self fetchWeatherData];
    }
}

Open MTWeatherViewController.xib, add a button to the view controller's view with a title of Refresh, and connect the outlet and action with the button (figure 3). The reason for creating an outlet for the button is to be able to disable it when no network connection is available. For this to work, we need to update the reachabilityStatusDidChange: method as shown below.

Figure 3: Adding a Refresh Button

- (void)reachabilityStatusDidChange:(NSNotification *)notification {
    MTForecastClient *forecastClient = [notification object];
    NSLog(@"Reachability Status > %i", forecastClient.networkReachabilityStatus);
    // Update Refresh Button
    self.buttonRefresh.enabled = (forecastClient.networkReachabilityStatus != AFNetworkReachabilityStatusNotReachable);
}

It isn't necessary to temporarily disable the refresh button when a request is being processed in fetchWeatherData because the progress HUD adds a layer on top of the view controller's view that prevents the user from tapping the button more than once. Build and run the application to test everything out.

Bonus: Removing Locations

A reader asked me how to delete locations from the list so I am including it here for the sake of completeness. The first thing that we need to do is tell the table view which rows are editable by implementing tableView:canEditRowAtIndexPath: of the UITableViewDataSource protocol. This method returns YES if the row at indexPath is editable and NO if it is not. The implementation is simple as you can see below. Every row is editable except for the first row and the currently selected location.

- (BOOL)tableView:(UITableView *)tableView canEditRowAtIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.row == 0) {
        return NO;
    }
    // Fetch Location
    NSDictionary *location = [self.locations objectAtIndex:(indexPath.row - 1)];
    return ![self isCurrentLocation:location];
}

To check whether location is the current location, we use another helper method, isCurrentLocation:, in which we fetch the current location and compare the locations coordinates. It would have been better (and easier) if we had assigned a unique identifier to each location stored in the user defaults database. Not only would it make it easier to compare locations, but it would also allow us to store the current location's unique identifier in the user defaults database and look it up in the array of locations. The problem with the current implementation is that locations with the exact same coordinates cannot be distinguished from one another.

- (BOOL)isCurrentLocation:(NSDictionary *)location {
    // Fetch Current Location
    NSDictionary *currentLocation = [[NSUserDefaults standardUserDefaults] objectForKey:MTRainUserDefaultsLocation];
    if ([location[MTLocationKeyLatitude] doubleValue] == [currentLocation[MTLocationKeyLatitude] doubleValue] &&
        [location[MTLocationKeyLongitude] doubleValue] == [currentLocation[MTLocationKeyLongitude] doubleValue]) {
        return YES;
    }
    return NO;
}

When the user taps the delete button of a table view row, the table view data source is sent a tableView:commitEditingStyle:forRowAtIndexPath: message. In this method, we need to (1) update the data source, (2) save the changes to the user defaults database, and (3) update the table view. If editingStyle is equal to UITableViewCellEditingStyleDelete, we remove the location from the locations array and store the updated array in the user defaults database. We also delete the row from the table view to reflect the change in the data source.

- (void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath {
    if (editingStyle == UITableViewCellEditingStyleDelete) {
        // Update Locations
        [self.locations removeObjectAtIndex:(indexPath.row - 1)];
        // Update User Defaults
        [[NSUserDefaults standardUserDefaults] setObject:self.locations forKey:MTRainUserDefaultsLocations];
        // Update Table View
        [tableView deleteRowsAtIndexPaths:@[indexPath] withRowAnimation:UITableViewRowAnimationTop];
    }
}

To toggle the table view's editing style, we need to add an edit button to the user interface. Create an outlet for the button in MTLocationsViewController.h and an action named editLocations: in MTLocationsViewController.m. In editLocations:, we toggle the table view's editing style.

#import <UIKit/UIKit.h>
@protocol MTLocationsViewControllerDelegate;
@interface MTLocationsViewController : UIViewController <UITableViewDataSource, UITableViewDelegate>
@property (weak, nonatomic) id<MTLocationsViewControllerDelegate> delegate;
@property (weak, nonatomic) IBOutlet UITableView *tableView;
@property (weak, nonatomic) IBOutlet UIBarButtonItem *editButton;
@end
@protocol MTLocationsViewControllerDelegate <NSObject>
- (void)controllerShouldAddCurrentLocation:(MTLocationsViewController *)controller;
- (void)controller:(MTLocationsViewController *)controller didSelectLocation:(NSDictionary *)location;
@end

- (IBAction)editLocations:(id)sender {
    [self.tableView setEditing:![self.tableView isEditing] animated:YES];
}

Open MTLocationsViewController.xib, add a navigation bar to the view controller's view, and add an edit button to the navigation bar. Connect the edit button with the outlet and action that we created a moment ago.

Figure 4: Adding an Edit Button

You may be wondering why we created an outlet for the edit button. The reason is that we need to be able to change the title of the edit button from Edit to Done, and vice versa, whenever the editing style of the table view changes. In addition, when the user deletes the last location (except for the current location) in the table view, it would be nice to automatically toggle the table view's editing style. These features are not hard to implement which is why I leave them up to you as an exercise. If you run into problems or have questions, feel free to leave a comment in the comments below this article.

Conclusion

We have successfully integrated the Forecast API in our weather application. In the next tutorial, we will implement focus on the user interface and the design of the application.

Reading NFC Tags with Android

Ralf Wondratschek — Thu, 16 May 2013 17:32:40 +0000

Are you curious about what NFC is and how it can be integrated into your own Android applications? This tutorial will quickly introduce you to the topic before diving in and teaching you how to build a simple NFC reader app!

What is NFC?

NFC is the abbreviation for Near Field Communication. It is the international standard for contactless exchange of data. In contrast to a large range of other technologies, such as wireless LAN and Bluetooth, the maximum distance of two devices is 10cm. The development of the standard started in 2002 by NXP Semiconductors and Sony. The NFC Forum, a consortium of over 170 companies and members, which included Mastercard, NXP, Nokia, Samsung, Intel, and Google, has been designing new specifications since 2004.

There are various possibilities for NFC use with mobile devices; for example, paperless tickets, access controls, cashless payments, and car keys. With the help of NFC tags you can control your phone and change settings. Data can be exchanged simply by holding two devices next to each other.

In this tutorial I want to explain how to implement NFC with the Android SDK, which pitfalls exist, and what to keep in mind. We will create an app step by step, which can read the content of NFC tags supporting NDEF.

NFC Technologies

There are a variety of NFC tags that can be read with a smartphone. The spectrum ranges from simple stickers and key rings to complex cards with integrated cryptographic hardware. Tags also differ in their chip technology. The most important is NDEF, which is supported by most tags. In addidition, Mifare should be mentioned as it is the most used contactless chip technology worldwide. Some tags can be read and written, while others are read-only or encrypted.

Only the NFC Data Exchange Format (NDEF) is discussed in this tutorial.

Adding NFC Support in an App

We start with a new project and a blank activity. It is important to select a minimum SDK version of level 10, because NFC is only supported after Android 2.3.3. Remember to choose your own package name. I’ve chosen net.vrallev.android.nfc.demo, because vrallev.net is the domain of my website and the other part refers to the topic of this application.

	<uses-sdk
		android:minSdkVersion="10"
        android:targetSdkVersion="17" />

The default layout generated by Eclipse is almost sufficient for us. I’ve only added an ID to the TextView and changed the text.

	<TextView
        android:id="@+id/textView_explanation"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/explanation" />

To get access to the NFC hardware, you have to apply for permission in the manifest. If the app won’t work without NFC, you can specify the condition with the uses-feature tag. If NFC is required, the app can’t be installed on devices without it and Google Play will only display your app to users who own a NFC device.

	<uses-permission android:name="android.permission.NFC" />
    <uses-feature
        android:name="android.hardware.nfc"
        android:required="true" />

The MainActivity should only consist of the onCreate() method. You can interact with the hardware via the NfcAdapter class. It is important to find out whether the NfcAdapter is null. In this case, the Android device does not support NFC.

	package net.vrallev.android.nfc.demo;
	import android.app.Activity;
	import android.nfc.NfcAdapter;
	import android.os.Bundle;
	import android.widget.TextView;
	import android.widget.Toast;
	/**
	 * Activity for reading data from an NDEF Tag.
	 *
	 * @author Ralf Wondratschek
	 *
	 */
	public class MainActivity extends Activity {
		public static final String TAG = "NfcDemo";
		private TextView mTextView;
		private NfcAdapter mNfcAdapter;
		@Override
		protected void onCreate(Bundle savedInstanceState) {
			super.onCreate(savedInstanceState);
			setContentView(R.layout.activity_main);
			mTextView = (TextView) findViewById(R.id.textView_explanation);
			mNfcAdapter = NfcAdapter.getDefaultAdapter(this);
			if (mNfcAdapter == null) {
				// Stop here, we definitely need NFC
				Toast.makeText(this, "This device doesn't support NFC.", Toast.LENGTH_LONG).show();
				finish();
				return;
			}
			if (!mNfcAdapter.isEnabled()) {
				mTextView.setText("NFC is disabled.");
			} else {
				mTextView.setText(R.string.explanation);
			}
			handleIntent(getIntent());
		}
		private void handleIntent(Intent intent) {
			// TODO: handle Intent
		}
	}

If we start our app now, we can see the text whether NFC is enabled or disabled.

How to Filter for NFC Tags

We have our sample app and want to receive a notification from the system when we attach an NFC tag to the device. As usual, Android uses its Intent system to deliver tags to the apps. If multiple apps can handle the Intent, the activity chooser gets displayed and the user can decide which app will be opened. Opening URLs or sharing information is handled the same way.

NFC Intent Filter

There are three different filters for tags:

ACTION_NDEF_DISCOVERED
ACTION_TECH_DISCOVERED
ACTION_TAG_DISCOVERED

The list is sorted from the highest to the lowest priority.

Now what happens when a tag is attached to the smartphone? If the system detects a tag with NDEF support, an Intent is triggered. An ACTION_TECH_DISCOVERED Intent is triggered if no Activity from any app is registered for the NDEF Intent or if the tag does not support NDEF. If again no app is found for the Intent or the chip technology could not be detected, then a ACTION_TAG_DISCOVERED Intent is fired. The following graphic shows the process:

In summary this means that each app needs to filter after the Intent with the highest priority. In our case, this is the NDEF Intent. We implement the ACTION_TECH_DISCOVERED Intent first to highlight the difference between priorities.

Tech Discovered Intent

We must specify the technology we are interested in. For this purpose, we create a subfolder called xml in the res folder. In this folder we create the file nfc_tech_filter.xml, in which we specify the technologies.

	<?xml version="1.0" encoding="utf-8"?>
	<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
	    <tech-list>
	        <tech>android.nfc.tech.Ndef</tech>
	        <!-- class name -->
	    </tech-list>
	</resources>
	<!--
	<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
	    <tech-list>
	        <tech>android.nfc.tech.IsoDep</tech>
	        <tech>android.nfc.tech.NfcA</tech>
	        <tech>android.nfc.tech.NfcB</tech>
	        <tech>android.nfc.tech.NfcF</tech>
	        <tech>android.nfc.tech.NfcV</tech>
	        <tech>android.nfc.tech.Ndef</tech>
	        <tech>android.nfc.tech.NdefFormatable</tech>
	        <tech>android.nfc.tech.MifareClassic</tech>
	        <tech>android.nfc.tech.MifareUltralight</tech>
	    </tech-list>
	</resources>
	-->

Now we must create an IntentFilter in the manifest, and the app will be started when we attach a tag.

	<?xml version="1.0" encoding="utf-8"?>
	<activity
		android:name="net.vrallev.android.nfc.demo.MainActivity"
        android:label="@string/app_name" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.nfc.action.TECH_DISCOVERED" />
        </intent-filter>
        <meta-data
            android:name="android.nfc.action.TECH_DISCOVERED"
            android:resource="@xml/nfc_tech_filter" />
    </activity>

If no other app is registered for this Intent, our Activity will start immediately. On my device, however, other apps are installed, so the activity chooser gets displayed.

NDEF Discovered Intent

As I mentioned before, the Tech Discovered Intent has the second highest priority. However, since our app will support only NDEF, we can use the NDEF Discovered Intent instead, which has a higher priority. We can delete the technology list again and replace the IntentFilter with the following one.

	<intent-filter>
		<action android:name="android.nfc.action.NDEF_DISCOVERED" />
		<category android:name="android.intent.category.DEFAULT" />
		<data android:mimeType="text/plain" />
	</intent-filter>

When we attach the tag now, the app will be started like before. There is a difference for me, however. The activity chooser does not appear and the app starts immediately, because the NDEF Intent has a higher priority and the other apps only registered for the lower priorities. That’s exactly what we want.

Foreground Dispatch

Note that one problem remains. When our app is already opened and we attach the tag again, the app is opened a second time instead of delivering the tag directly. This is not our intended behavior. You can bypass the problem by using a Foreground Dispatch.

Instead of the system having distributed the Intent, you can register your Activity to receive the tag directly. This is important for a particular workflow, where it makes no sense to open another app.

I’ve inserted the explanations at the appropriate places in the code.

	package net.vrallev.android.nfc.demo;
	import android.app.Activity;
	import android.app.PendingIntent;
	import android.content.Intent;
	import android.content.IntentFilter;
	import android.content.IntentFilter.MalformedMimeTypeException;
	import android.nfc.NfcAdapter;
	import android.os.Bundle;
	import android.widget.TextView;
	import android.widget.Toast;
	/**
	 * Activity for reading data from an NDEF Tag.
	 *
	 * @author Ralf Wondratschek
	 *
	 */
	public class MainActivity extends Activity {
		public static final String MIME_TEXT_PLAIN = "text/plain";
		public static final String TAG = "NfcDemo";
		private TextView mTextView;
		private NfcAdapter mNfcAdapter;
		@Override
		protected void onCreate(Bundle savedInstanceState) {
			super.onCreate(savedInstanceState);
			setContentView(R.layout.activity_main);
			mTextView = (TextView) findViewById(R.id.textView_explanation);
			mNfcAdapter = NfcAdapter.getDefaultAdapter(this);
			if (mNfcAdapter == null) {
				// Stop here, we definitely need NFC
				Toast.makeText(this, "This device doesn't support NFC.", Toast.LENGTH_LONG).show();
				finish();
				return;
			}
			if (!mNfcAdapter.isEnabled()) {
				mTextView.setText("NFC is disabled.");
			} else {
				mTextView.setText(R.string.explanation);
			}
			handleIntent(getIntent());
		}
		@Override
		protected void onResume() {
			super.onResume();
			/**
			 * It's important, that the activity is in the foreground (resumed). Otherwise
			 * an IllegalStateException is thrown.
			 */
			setupForegroundDispatch(this, mNfcAdapter);
		}
		@Override
		protected void onPause() {
			/**
			 * Call this before onPause, otherwise an IllegalArgumentException is thrown as well.
			 */
			stopForegroundDispatch(this, mNfcAdapter);
			super.onPause();
		}
		@Override
		protected void onNewIntent(Intent intent) {
			/**
			 * This method gets called, when a new Intent gets associated with the current activity instance.
			 * Instead of creating a new activity, onNewIntent will be called. For more information have a look
			 * at the documentation.
			 *
			 * In our case this method gets called, when the user attaches a Tag to the device.
			 */
			handleIntent(intent);
		}
		private void handleIntent(Intent intent) {
			// TODO: handle Intent
		}
		/**
		 * @param activity The corresponding {@link Activity} requesting the foreground dispatch.
		 * @param adapter The {@link NfcAdapter} used for the foreground dispatch.
		 */
		public static void setupForegroundDispatch(final Activity activity, NfcAdapter adapter) {
			final Intent intent = new Intent(activity.getApplicationContext(), activity.getClass());
			intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
			final PendingIntent pendingIntent = PendingIntent.getActivity(activity.getApplicationContext(), 0, intent, 0);
			IntentFilter[] filters = new IntentFilter[1];
			String[][] techList = new String[][]{};
			// Notice that this is the same filter as in our manifest.
			filters[0] = new IntentFilter();
			filters[0].addAction(NfcAdapter.ACTION_NDEF_DISCOVERED);
			filters[0].addCategory(Intent.CATEGORY_DEFAULT);
			try {
				filters[0].addDataType(MIME_TEXT_PLAIN);
			} catch (MalformedMimeTypeException e) {
				throw new RuntimeException("Check your mime type.");
			}
			adapter.enableForegroundDispatch(activity, pendingIntent, filters, techList);
		}
		/**
		 * @param activity The corresponding {@link BaseActivity} requesting to stop the foreground dispatch.
		 * @param adapter The {@link NfcAdapter} used for the foreground dispatch.
		 */
		public static void stopForegroundDispatch(final Activity activity, NfcAdapter adapter) {
			adapter.disableForegroundDispatch(activity);
		}
	}

Now, when you attach a tag and our app is already opened, onNewIntent is called and no new Activity is created.

Reading Data From an NDEF Tag

The last step is to read the data from the tag. The explanations are inserted at the appropriate places in the code once again. The NdefReaderTask is a private inner class.

	package net.vrallev.android.nfc.demo;
	import java.io.UnsupportedEncodingException;
	import java.util.Arrays;
	import android.app.Activity;
	import android.app.PendingIntent;
	import android.content.Intent;
	import android.content.IntentFilter;
	import android.content.IntentFilter.MalformedMimeTypeException;
	import android.nfc.NdefMessage;
	import android.nfc.NdefRecord;
	import android.nfc.NfcAdapter;
	import android.nfc.Tag;
	import android.nfc.tech.Ndef;
	import android.os.AsyncTask;
	import android.os.Bundle;
	import android.util.Log;
	import android.widget.TextView;
	import android.widget.Toast;
	/*
	 * ... other code parts
	 */
	private void handleIntent(Intent intent) {
		String action = intent.getAction();
		if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(action)) {
			String type = intent.getType();
			if (MIME_TEXT_PLAIN.equals(type)) {
				Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
				new NdefReaderTask().execute(tag);
			} else {
				Log.d(TAG, "Wrong mime type: " + type);
			}
		} else if (NfcAdapter.ACTION_TECH_DISCOVERED.equals(action)) {
			// In case we would still use the Tech Discovered Intent
			Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
			String[] techList = tag.getTechList();
			String searchedTech = Ndef.class.getName();
			for (String tech : techList) {
				if (searchedTech.equals(tech)) {
					new NdefReaderTask().execute(tag);
					break;
				}
			}
		}
	}

	/**
	 * Background task for reading the data. Do not block the UI thread while reading.
	 *
	 * @author Ralf Wondratschek
	 *
	 */
	private class NdefReaderTask extends AsyncTask<Tag, Void, String> {
		@Override
		protected String doInBackground(Tag... params) {
			Tag tag = params[0];
			Ndef ndef = Ndef.get(tag);
			if (ndef == null) {
				// NDEF is not supported by this Tag.
				return null;
			}
			NdefMessage ndefMessage = ndef.getCachedNdefMessage();
			NdefRecord[] records = ndefMessage.getRecords();
			for (NdefRecord ndefRecord : records) {
				if (ndefRecord.getTnf() == NdefRecord.TNF_WELL_KNOWN && Arrays.equals(ndefRecord.getType(), NdefRecord.RTD_TEXT)) {
					try {
						return readText(ndefRecord);
					} catch (UnsupportedEncodingException e) {
						Log.e(TAG, "Unsupported Encoding", e);
					}
				}
			}
			return null;
		}
		private String readText(NdefRecord record) throws UnsupportedEncodingException {
			/*
			 * See NFC forum specification for "Text Record Type Definition" at 3.2.1
			 *
			 * http://www.nfc-forum.org/specs/
			 *
			 * bit_7 defines encoding
			 * bit_6 reserved for future use, must be 0
			 * bit_5..0 length of IANA language code
			 */
			byte[] payload = record.getPayload();
			// Get the Text Encoding
			String textEncoding = ((payload[0] & 128) == 0) ? "UTF-8" : "UTF-16";
			// Get the Language Code
			int languageCodeLength = payload[0] & 0063;
			// String languageCode = new String(payload, 1, languageCodeLength, "US-ASCII");
			// e.g. "en"
			// Get the Text
			return new String(payload, languageCodeLength + 1, payload.length - languageCodeLength - 1, textEncoding);
		}
		@Override
		protected void onPostExecute(String result) {
			if (result != null) {
				mTextView.setText("Read content: " + result);
			}
		}
	}

The app now successfully reads the content.

Useful Apps

To check whether data is read and written properly, I personally like to use following apps:

NFC TagInfo by NFC Research Lab for reading data
TagInfo by NXP SEMICONDUCTORS for reading data
TagWriter by NXP SEMICONDUCTORS for writing data

Conclusion

In this tutorial I have shown you how the data from a NDEF tag can be extracted. You could expand the example to other mime types and chip technologies; a feature to write data would be useful as well. The first step to work with NFC was made. However, the Android SDK offers much more possibilities, such as an easy exchange of data (called Android Beam).

About the Author

Ralf Wondratschek is a computer science student from Germany. In addition to his studies, Ralf works as a freelancer in the field of mobile computing. In the last few years he has worked with Java, XML, HTML, JSP, JSF, Eclipse, Google App Engine, and of course Android. He has published two Android apps to date which can be found here.

You can find out more about the author’s work on his homepage vrallev.net.

Sources

http://www.nfc-forum.org/home/n-mark.jpg

http://commons.wikimedia.org/wiki/File%3A%C3%9Cberlagert.jpg

http://developer.android.com/images/nfc_tag_dispatch.png

Connecting to an External Database With NuSOAP

Tomasz Wójcik — Wed, 15 May 2013 17:57:52 +0000

Many mobile applications use external databases that are located remotely on the Internet. In the following tutorial, we will create a simple database, connect to it, and receive or send data from this source. To do this we will use a Windows Phone 7 Silverlight based application and a NuSOAP web service. Let’s begin!

1. Install the Software

Before we start we need to install the following programs:

Windows Phone 7.5 SDK
Silverlight 5 Toolkit
PHP Library to run the web service (NuSOAP)

Obviously, we will also need some sort of web hosting where we can create a database. Most of the free hosting options will be enough for us, but they may have some limitations which I will discuss later on in this tutorial.

We also need an FTP client. In this tutorial I will use a FireFTP add-on to Mozilla Firefox. But you can use anything you want.

When all the programs are installed, we can continue.

2. Creating an External Database

Step 1

To begin, check that the hosting uses phpMyAdmin because I use it in the examples. But if you choose to use something else all the commands should be similar.

First we need to create a simple database, in our case it will contain only one table and three attributes:

ID – this value identifies the record. It must be set as an autoincrement field.
FirstName
LastName

The table name is MyUsers.

To do this just click “create table”:

Step 2

After that, fill in the cells as shown in this screenshot:

The table structure should now look like this:

Step 3

At this step we must note a few important points:

Host address

As I wrote earlier, free hostings have limits, one of these is to possibly connect only from localhost, remember that!

Database user

Our username to log into the database:

Database password
Database name

3. NuSOAP Server – Starting Web Service

Step 1

Starting our web service is very simple:

First, we must copy some files to the ftp server. I recommend a ftp server because it is directly connected to our hosting because of the localhost issue.

Once we’re connected, we need to copy the nusoap.php file which was downloaded earlier. We also require a file that will contain specific functions written by us that is necessary for our application; I called it MyService.php.

Step 2

After we copy the files, our FTP root directory should look like the image below:

Now open the MyService.php file and write into it:

<?php
// Pull in the NuSOAP
code require_once('nusoap.php');
// Create the server instance
$server = new soap_server();
// Initialize WSDL support
(MyService is name of our service)
$server----->configureWSDL('MyService', 'urn:MyService');
        // Character encoding
        $server->soap_defencoding = 'utf-8';
        //-------------------------------------------------
        //Registrations of our functions
        //-------------------------------------------------
        //Our web service functions will be here.
        //-------------------------------------------------
        $HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
        $server->service($HTTP_RAW_POST_DATA);
?>

The most important points are explained in the upper comments to code.

Step 3

From now on our service should work. We can check this by typing in the web browser:

http://www.ourdomain.com/MyService.php

If all went well you should see something like this:

After we successfully started the web service, we can go to the next step.

4. Writing Web Service Functions

In our service we need two functions:

The first function adds data to the online database.
The second function receives data from it.

Step 1

Let’s open MyService.php. We need to register the new function, to do this we should type:

    $server->register(
        'InsertData',   //Name of function
      	array('FirstName' => 'xsd:string', 'LastName' => 'xsd:string'), //Input Values
      	array('return' =>'xsd:boolean'), //Output Values
    	  'urn:MyServicewsdl',  //Namespace
        'urn:MyServicewsdl#InsertData',  //SoapAction
        'rpc',       //style
        'literal',   //can be encoded but it doesn't work with silverlight
        'Some_comments_about_function'
    );

Remember that it needs to be placed before the body function and after the server directives.

Here is some code explanation:

      'FirstName' => 'xsd:string'

“FirstName” is the name of variable, “string” is the type of variable (i.e. it can be int, longint, boolean, etc.).

When the function registers, we need to write the body of it. Below is the code and explanation:

    function InsertData($FirstName, $LastName) {
    	$connect = mysql_pconnect("Host","UserName","UserPassword"));
    	if ($connect) {
    		if(mysql_select_db("DatabaseName", $connect)) {
          mysql_query("INSERT INTO MyUser SET FirstName='$FirstName', LastName='$LastName'");
    			return true;
    		}
    	}
    	return false;
    }

          InsertData($FirstName, $LastName)

Here’s the name of the function and its attributes. They must be the same as in the registration section.

          $connect = mysql_pconnect("Host","UserName","UserPassword");

Here we can insert the data we noticed when we created the database.

          if(mysql_select_db("DatabaseName", $connect)) {

And also here.

After that it is a simple MySQL query that adds data to our database:

          mysql_query("INSERT INTO MyUser SET FistName='$FirstName', LastName='$LastName'");

Step 2

Now it’s time to write the second function. The structure will be similar to the first.

Here is the code of method registration:

      $server->register(
          'GetData',
        	array('ID' => 'xsd:int'),
        	array('return' =>'xsd:string'),
      	  'urn:MyServicewsdl',
          'urn:MyServicewsdl#GetData',
          'rpc',
          'literal',
          'Some comments about function 2'
      );

The main differences are in the Input/Output values section (changed types of variables).

Here’s the body function code:

       function GetData($ID) {
      	$connect = mysql_pconnect("Host","UserName","UserPassword");
      	if ($connect) {
      		if(mysql_select_db("DatabaseName", $connect)) {
            $sql = "SELECT FirstName, LastName FROM MyUser WHERE ID = '$ID'";
      			$result = mysql_fetch_array(mysql_query($sql));
      			return $result['FirstName']."-".$result['LastName'];
      		}
      	}
      	return false;
      }

Here is a little code explanation:

         return $result['FirstName']."-".$result['LastName'];

This line states what must return to the Windows Phone application.

Step 3

After writing all the functions the MyService.php file should look like this:

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the server instance
$server = new soap_server();
// Initialize WSDL support
configureWSDL('MyService', 'urn:MyService');
                // Character encoding
                $server->soap_defencoding = 'utf-8';
                //-------------------------------------------------
                //Register InsertData function
                $server->register(
                        'InsertData',
                      	array('FirstName' => 'xsd:string', 'LastName' => 'xsd:string'),
                      	array('return' =>'xsd:boolean'),
                    	  'urn:MyServicewsdl',
                        'urn:MyServicewsdl#InsertData',
                        'rpc',
                        'literal',
                        'Some comments about function'
                    );
                //Register GetData function
                $server->register(
                        'GetData',
                      	array('ID' => 'xsd:int'),
                      	array('return' =>'xsd:string'),
                    	  'urn:MyServicewsdl',
                        'urn:MyServicewsdl#GetData',
                        'rpc',
                        'literal',
                        'Some comments about function 2'
                    );
                //-------------------------------------------------
                //Body InsterData function
                function InsertData($FirstName, $LastName) {
                	$connect = mysql_pconnect("Host","UserName","UserPassword");
                	if ($connect) {
                		if(mysql_select_db("DatabaseName", $connect)) {
                      mysql_query("INSERT INTO MyUser SET FirstName='$FirstName', LastName='$LastName'");
                			return true;
                		}
                	}
                	return false;
                }
                //Body GetData function
                function GetData($ID) {
                	$connect = mysql_pconnect("Host","UserName","UserPassword");
                	if ($connect) {
                		if(mysql_select_db("DatabaseName", $connect)) {
                      $sql = "SELECT FirstName, LastName FROM MyUser WHERE ID = '$ID'";
                			$result = mysql_fetch_array(mysql_query($sql));
                			return $result['FirstName']."-".$result['LastName'];
                		}
                	}
                	return false;
                }
                //-------------------------------------------------
                $HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
                $server->service($HTTP_RAW_POST_DATA);
        ?>

To validate the functions we can again type http://www.ourdomain.com/MyService.php in the browser. Now the site should look a little bit different, but similar to this:

Now we’re ready to go to next step.

5. Creating a Simple Layout for a Windows Phone Application

Step 1

Firstly, we must create a Windows Phone app. Let’s run Microsoft Visual Studio for Windows Phone 2010. After Visual Studio starts, click “File” then “New Project”. You should see a dialog window like in the screenshot below:

Our app will use Silverlight, so we must check this template. We can also change the project name, like localisations, etc. In my case, the project name is “MyApplication”. After you have done this, click the OK button.

Step 2

At this point we must note what we need in our app. We need:

Two text boxes for sending data to the database (First Name, Last Name)
One text box to receive the data (ID)
Two buttons to approve our actions

Adding objects (such as buttons) to our application is easy, just drag it from “ToolBox” and drop it onto preview of the app. Keep in mind that you have a free hand in setting your own layout.

This is how it looks on my app:

Another important aspect is the names of the elements used in Visual Studio (they’re used later in code).

To change it, just click on element. Then in properties you can see text like “Textbox1″, click on it, and change it to something that you can remember, that is crucial. I used these names for my elements:

“FirstNameBox”, “LastNameBox”, and “IdBox” for text boxes
“SendBTN” and “ReadBTN” for buttons

That’s all we need to do in this step, we can move on.

6. Connecting to Service

To connect to the web service we must right click on “Reference” in “Solution Explorer” dialog and select “Add Service Reference…”

Here how this looks:

After that a new window will appear. In it we must write the address of our web service and the name of namespace.

In our case an address will be created, like on this scheme: http://www.ourdomain.com/MyService.php?wsdl.

After entering an address and clicking “Go” you should see something like this:

If you see the operations called “GetData” and “InsertData” that means the connection was successfully created! Remember to type namespace, in my case it is “MyService”. Now click OK.

7. Writing Windows Phone Functions

We’re almost at the end of this tutorial; we only need to write two simple functions.

Step 1

The first function will be behind the “Send” button, so double click it. Now we must add at the top of the file a “using” directive of our service:

      using MyApplication.MyService;

Let’s look at the send function behind the “Send” button, now it is empty:

        private void SendBTN_Click(object sender, RoutedEventArgs e)
        {
        }

Our complete function should look like this:

        private void SendBTN_Click(object sender, RoutedEventArgs e)
        {
            //Creating new proxy object of our service
            MyServicePortTypeClient send = new MyServicePortTypeClient();
            send.InsertDataCompleted += new EventHandler<InsertDataCompletedEventArgs>(send_InsertDataCompleted);
            //Calling method, as a parameters we type text contained in FirstNameBox and LastNameBox
            //This data will be sent to web service and later to database
            send.InsertDataAsync(FirstNameBox.Text, LastNameBox.Text);
        }
        void send_InsertDataCompleted(object sender, InsertDataCompletedEventArgs e)
        {
            //If our server return true, that means we're added data to database...
            if (e.Result)
                MessageBox.Show("Successfully added!");
            //...if return false we aren't.
            else
                MessageBox.Show("Some problems occured!");
        }

The most important points are explained in the code comments, but we must be aware of the following:

Method “send_InsertDataCompleted” executes when we get an answer from the server. Also this function is not in the “SendBTN” object, it is outside.

Now it’s time to test our work! Start to debug and fill out the boxes with some data. Here I have entered John as a first name and Doe as a last name, then I clicked Send:

Let’s see how the database looks now:

Yes, the new record with ID = 1 has appeared and everything is going well.

Step 2

Now we’ve reached the final function for receiving. It is similar to the previous method. Double click on the “Read” button and copy the code:

      private void ReadBTN_Click(object sender, RoutedEventArgs e)
        {
            //Creating new proxy object of our service
            MyServicePortTypeClient read = new MyServicePortTypeClient();
            read.GetDataCompleted += new EventHandler<GetDataCompletedEventArgs>(read_GetDataCompleted);
            //Calling method, as a parameters we type text contained in IdTextBox
            //but we must change text type of string to integer (ID in web service have integer type)
            read.GetDataAsync(Convert.ToInt32(IdBox.Text));
        }
        void read_GetDataCompleted(object sender, GetDataCompletedEventArgs e)
        {
            MessageBox.Show(e.Result);
        }

This is the same process as before, “read_GetDataCompleted” executes after getting data from the database. In this method we’ll use a message box to show our result, i.e. first and last name. There is one more step to do; we need to change the type of text in IdBox from string to integer because the variable called ID in the web service has an integer type. To do this I used a function called “Convert.ToIn32()”

8. Testing

Now we can see if this works. Enter ID into “IdTextBox”. I entered “1″, then clicked the “Read” button.

Everything is working! Our application is now complete!

Conclusion

In this tutorial we created a database using a Windows Phone 7 Silverlight based application and NuSOAP web service. This database is helpful to receive or send data. External databases are important because they are used by many mobile applications.

Create a Weather App with Forecast – Project Setup

Bart Jacobs — Mon, 13 May 2013 19:52:08 +0000

In March of this year, the company behind Dark Sky and Forecast.io introduced Forecast. Forecast is a simple weather API that provides both short- and longterm weather data. In this series, I will show you how to create a beautiful weather application for iOS powered by Forecast.

Introduction

Earlier this year, the Dark Sky Company introduced Forecast, a simple yet powerful weather API that provides short and longterm weather predictions. In this series we will create an iOS application that is powered by the Forecast API. Forecast is free for up to a thousand API calls per day, so feel free to sign up for a developer account and follow along with me.

Even though a number of open source wrappers for the Forecast API are available, in this series we will use the AFNetworking library to query the Forecast API. In the first part of this series, we will create the project’s foundation and implement a basic user interface. Even though our application is simple in scope, it will support multiple locations and that is what we will focus on in this article.

1. Project Setup

Step 1: Creating the Project

Fire up Xcode and create a new project based on the Empty Application template (figure 1). Name the application Rain and enable Automatic Reference Counting (figure 2).

Figure 1: Setting Up the Project

Figure 2: Configuring the Project

Step 2: Adding Libraries

For this project, we will be using three open source libraries, SVProgressHUD created by Sam Vermette, AFNetworking created by Mattt Thompson, and ViewDeck created by Tom Adriaenssen.

Since I am an avid fan of CocoaPods, I will be using it to install and manage the libraries of our project. If you are not familiar with CocoaPods, then I recommend visiting the website of CocoaPods or reading my introduction to CocoaPods. You can also manually add each library to your project if you prefer to not use CocoaPods.

Close your project, browse to the project’s root, and create a file named Podfile. Open Podfile in your favorite text editor and replace its contents with the snippet below. In the project’s pod file, we specify the platform, deployment target, and the pods we want to include in the project.

platform :ios, '6.0'
pod 'ViewDeck', '~> 2.2.11'
pod 'AFNetworking', '~> 1.2.1'
pod 'SVProgressHUD', '~> 0.9.0'

Open the Terminal application, browse to the project’s root, and install the libraries by executing pod install. In addition to installing the three pods that we specified in the project’s pod file, CocoaPods has already created an Xcode workspace for us. Open the new workspace by executing the open Rain.xcworkspace command from the command line.

Step 3: Adding Dependencies

Before we can continue, we need to link our project against a handful of frameworks. The AFNetworking library depends on the Mobile Core Services and System Configuration frameworks and the ViewDeck library makes use of the Quartz Core framework. Select the project from the Project Navigator on the left, select the Rain target in the list of targets, open the Build Phases tab at the top, and expand the Link Binary With Libraries drawer. Click the plus button to link your project against the aforementioned frameworks. We will be using the Core Location framework a bit later in this article so now is good time to link your project against that framework as well (figure 3).

Figure 3: Linking the Project Against a Handful of Frameworks

Step 4: Edit the Precompiled Header File

Before we start implementing the basic structure of our weather application, it is a good idea to edit the precompiled header file of our project. Add an import statement for each of the frameworks we added to our project a moment ago and do the same for the AFNetworking, SVProgressHUD, and ViewDeck libraries.

#import <Availability.h>
#ifndef __IPHONE_3_0
#warning "This project uses features only available in iOS SDK 3.0 and later."
#endif
#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <QuartzCore/QuartzCore.h>
    #import <CoreLocation/CoreLocation.h>
    #import <MobileCoreServices/MobileCoreServices.h>
    #import <SystemConfiguration/SystemConfiguration.h>
    #import "AFNetworking.h"
    #import "SVProgressHUD.h"
    #import "IIViewDeckController.h"
#endif

2. Laying the Foundation

The concept and structure of the application is simple. The application manages three views, (1) a view in the center showing the current weather for a particular location, a view on the right showing the weather for the next few days, and a view on the left with a list of locations. The basic structure will make more sense once we’ve implemented it. To create this structure, we make use of the terrific ViewDeck library, created and maintained by Tom Adriaenssen. The ViewDeck library is one of the most powerful implementations of the sliding view design pattern originally introduced in Facebook for iOS.

Step 1: View Controllers

Before we put the ViewDeck library to use, we need to create the view controller classes that will manage the three views I mentioned in the previous paragraph. Create three UIViewController subclasses named MTWeatherViewController, MTForecastViewController, and MTLocationsViewController, respectively (figure 4). Don’t forget to create a user interface or XIB file for each class (figure 4).

Figure 4: Creating the Three Main View Controller Classes

Step 2: Creating a View Deck Controller

Open MTAppDelegate.m and import the header file the three UIViewController subclasses. Add a class extension and create a property of type IIViewDeckController and name it viewDeckController. The reason for this will become clear in a moment.

#import "MTAppDelegate.h"
#import "MTWeatherViewController.h"
#import "MTForecastViewController.h"
#import "MTLocationsViewController.h"
@interface MTAppDelegate ()
@property (strong, nonatomic) IIViewDeckController *viewDeckController;
@end

In application:didFinishLaunchingWithOptions:, we start by creating an instance of each of the three UIViewController subclasses. We then initialize an instance of the IIViewDeckController class and pass the view controller objects as arguments to initWithCenterViewController:leftViewController:rightViewController:. As the initializer indicates, the view deck controller that we create manages a center, left, and right view controller. The rest of the implementation of application:didFinishLaunchingWithOptions: should be familiar to you. We initialize the application window and set the view deck controller as its root view controller.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize View Controllers
    MTLocationsViewController *leftViewController = [[MTLocationsViewController alloc] initWithNibName:@"MTLocationsViewController" bundle:nil];
    MTForecastViewController *rightViewController = [[MTForecastViewController alloc] initWithNibName:@"MTForecastViewController" bundle:nil];
    MTWeatherViewController *centerViewController = [[MTWeatherViewController alloc] initWithNibName:@"MTWeatherViewController" bundle:nil];
    // Initialize View Deck Controller
    self.viewDeckController = [[IIViewDeckController alloc] initWithCenterViewController:centerViewController leftViewController:leftViewController rightViewController:rightViewController];
    // Initialize Window
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    // Configure Window
    [self.window setRootViewController:self.viewDeckController];
    [self.window makeKeyAndVisible];
    return YES;
}

Build and run the application in the iOS Simulator or on a physical device to see the ViewDeck library in action. Even though the views of the view controllers are empty, the fundamental application structure is ready.

3. Adding Locations

As I mentioned in the introduction, in this tutorial we will also add the ability to add locations to the list of locations managed by the application. The MTLocationsViewController class is in charge of managing the list of locations and presenting them in a table view. The user can add the current location to the list of locations by tapping the table view’s first row, which will be labeled “Add Current Location”. Adding a new location with the Core Location framework is a responsibility of the MTWeatherViewController class as we will see in a few minutes.

This leaves us with a problem. How is the weather view controller notified when the user has tapped the first row of the locations view controller? Notification center? Delegation is a better choice in this context. Whenever I encounter the need for a one-way communication between two objects, I tend to choose for delegation in favor of notifications. A delegate protocol is much easier to wrap your head around and extending it is as simple as declaring another method.

Another option would be to pass a reference to the weather view controller to the locations view controller, but I don’t like this type of tight coupling. Tight coupling makes code less reusable and it results in unnecessarily complex object hierarchies when the code base grows over time. Delegation is the right choice for this problem.

Step 1: Declaring the Delegate Protocol

Open MTLocationsViewController.h and update the header file as shown below. We create a property for the view controller’s delegate and we declare the MTLocationsViewControllerDelegate protocol. The protocol defines two methods, (1) controllerShouldAddCurrentLocation:, which is invoked when the first row in the view controller’s table view is tapped, and (2) controller:didSelectLocation:, which is invoked when the user select a location from the list of locations.

#import <UIKit/UIKit.h>
@protocol MTLocationsViewControllerDelegate;
@interface MTLocationsViewController : UIViewController
@property (weak, nonatomic) id<MTLocationsViewControllerDelegate> delegate;
@end
@protocol MTLocationsViewControllerDelegate <NSObject>
- (void)controllerShouldAddCurrentLocation:(MTLocationsViewController *)controller;
- (void)controller:(MTLocationsViewController *)controller didSelectLocation:(NSDictionary *)location;
@end

Step 2: Adding the Table View

Revisit MTLocationsViewController.h one more time. Create an outlet for the view controller’s table view and make sure to conform the MTLocationsViewController class to the UITableViewDataSource and UITableViewDelegate protocols.

#import <UIKit/UIKit.h>
@protocol MTLocationsViewControllerDelegate;
@interface MTLocationsViewController : UIViewController <UITableViewDataSource, UITableViewDelegate>
@property (weak, nonatomic) id<MTLocationsViewControllerDelegate> delegate;
@property (weak, nonatomic) IBOutlet UITableView *tableView;
@end
@protocol MTLocationsViewControllerDelegate <NSObject>
- (void)controllerShouldAddCurrentLocation:(MTLocationsViewController *)controller;
- (void)controller:(MTLocationsViewController *)controller didSelectLocation:(NSDictionary *)location;
@end

Open MTLocationsViewController.xib, add a table view to the view controller’s view, and set the table view’s dataSource and delegate outlets to the File’s Owner object. Select the File’s Owner object and connect its tableView outlet with the table view that we added to the view controller’s view (figure 5).

Figure 5: Adding a Table View to List the Locations

Step 3: Populating the Table View

Before we implement the UITableViewDataSource and UITableViewDelegate protocols, we need to create a property that will serve as the table view’s data source. Create a class extension at the top of MTLocationsViewController.m and create a property named locations of type NSMutableArray. It will store the locations managed by our application.

#import "MTLocationsViewController.h"
@interface MTLocationsViewController ()
@property (strong, nonatomic) NSMutableArray *locations;
@end

Implementing the UITableViewDataSource and the UITableViewDelegate protocols is pretty straightforward. We start by declaring a static string constant for the cell reuse identifier. In the view controller’s viewDidLoad method we invoke setupView, a helper method in which we configure the view controller’s user interface. In setupView, we tell the table view to use the UITableViewCell class to instantiate new table view cells for the reuse identifier we declared earlier.

static NSString *LocationCell = @"LocationCell";

- (void)viewDidLoad {
    [super viewDidLoad];
    // Setup View
    [self setupView];
}

- (void)setupView {
    // Register Class for Cell Reuse
    [self.tableView registerClass:[UITableViewCell class] forCellReuseIdentifier:LocationCell];
}

Implementing the UITableViewDataSource and UITableViewDelegate protocols is trivial as you can see below. Two implementation details require a bit explaining. We store each location as a dictionary with four keys, (1) city, (2) country, (3) latitude, and (4) longitude. With this in mind, the implementation of configureCell:atIndexPath: should become a bit clearer. Note that configureCell:atIndexPath: is nothing more than another helper method.

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return 1;
}
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    return ([self.locations count] + 1);
}
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:LocationCell forIndexPath:indexPath];
    // Configure Cell
    [self configureCell:cell atIndexPath:indexPath];
    return cell;
}
- (void)configureCell:(UITableViewCell *)cell atIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.row == 0) {
        [cell.textLabel setText:@"Add Current Location"];
    } else {
        // Fetch Location
        NSDictionary *location = [self.locations objectAtIndex:(indexPath.row - 1)];
        // Configure Cell
        [cell.textLabel setText:[NSString stringWithFormat:@"%@, %@", location[@"city"], location[@"country"]]];
    }
}
- (BOOL)tableView:(UITableView *)tableView canEditRowAtIndexPath:(NSIndexPath *)indexPath {
    return NO;
}
- (BOOL)tableView:(UITableView *)tableView canMoveRowAtIndexPath:(NSIndexPath *)indexPath {
    return NO;
}

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    [tableView deselectRowAtIndexPath:indexPath animated:YES];
    if (indexPath.row == 0) {
        // Notify Delegate
        [self.delegate controllerShouldAddCurrentLocation:self];
    } else {
        // Fetch Location
        NSDictionary *location = [self.locations objectAtIndex:(indexPath.row - 1)];
        // Notify Delegate
        [self.delegate controller:self didSelectLocation:location];
    }
    // Show Center View Controller
    [self.viewDeckController closeLeftViewAnimated:YES];
}

The tableView:didSelectRowAtIndexPath: also requires a short explanation. If the user taps the first row, labeled Add Current Location, the delegate is notified that the current location should be added to the list of locations. If any other row in the table view is tapped, the corresponding location is passed as the second argument of controller:didSelectLocation:, another delegate method of the MTLocationsViewController delegate protocol. This informs the delegate that the application should set the new location as the application’t default location and the weather data for that location should be fetched.

The last line of tableView:didSelectRowAtIndexPath: is also worth mentioning. The IIViewDeckController instance assigns itself to the view controllers it manages. The viewDeckController property provides access to a view controller’s view deck controller, which is convenient if you need to access the view controller’s view deck. It works very much like the navigationController property of a view controller instance. In the last line of tableView:didSelectRowAtIndexPath:, we tell the view deck controller to close the left view, which means that the center view becomes visible again.

Step 4: Keys and Constants

Before we continue populating the locations table view, we need to pay attention to some best practices. We currently use string literals to access the values of the location dictionary. Even though this works perfectly fine, it is better and safer to use string constants for this purpose. To make all this easy and maintainable, we declare the string constants in a central location. Let me show you how this works.

Create a subclass of NSObject and name it MTConstants. Replace the contents of MTConstants.h and MTConstants.m with the snippets shown below. It should be clear that MTConstants is not an Objective-C class. It is nothing more than a central place to store a set of constants specific to our project.

#pragma mark -
#pragma mark User Defaults
extern NSString * const MTRainUserDefaultsLocation;
extern NSString * const MTRainUserDefaultsLocations;
#pragma mark -
#pragma mark Notifications
extern NSString * const MTRainDidAddLocationNotification;
extern NSString * const MTRainLocationDidChangeNotification;
#pragma mark -
#pragma mark Location Keys
extern NSString * const MTLocationKeyCity;
extern NSString * const MTLocationKeyCountry;
extern NSString * const MTLocationKeyLatitude;
extern NSString * const MTLocationKeyLongitude;

#import "MTConstants.h"
#pragma mark -
#pragma mark User Defaults
NSString * const MTRainUserDefaultsLocation = @"location";
NSString * const MTRainUserDefaultsLocations = @"locations";
#pragma mark -
#pragma mark Notifications
NSString * const MTRainDidAddLocationNotification = @"com.mobileTuts.MTRainDidAddLocationNotification";
NSString * const MTRainLocationDidChangeNotification = @"com.mobileTuts.MTRainLocationDidChangeNotification";
#pragma mark -
#pragma mark Location Keys
NSString * const MTLocationKeyCity = @"city";
NSString * const MTLocationKeyCountry = @"country";
NSString * const MTLocationKeyLatitude = @"latitude";
NSString * const MTLocationKeyLongitude = @"longitude";

To make MTConstants really useful, add an import statement for MTConstants.h to your project’s precompiled header file so the constants declared in MTConstants are available throughout the project.

#import <Availability.h>
#ifndef __IPHONE_3_0
#warning "This project uses features only available in iOS SDK 3.0 and later."
#endif
#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <QuartzCore/QuartzCore.h>
    #import <CoreLocation/CoreLocation.h>
    #import <MobileCoreServices/MobileCoreServices.h>
    #import <SystemConfiguration/SystemConfiguration.h>
    #import "AFNetworking.h"
    #import "SVProgressHUD.h"
    #import "IIViewDeckController.h"
    #import "MTConstants.h"
#endif

We can now update configureCell:atIndexPath: (MTLocationsViewController.m) as shown below. Not only will this give use code completion and a very, very small performance gain, the true benefit of this best practice is that the compiler will warn us in case of typos. I’m sure I don’t have to tell you that typos are one of the most common causes of bugs in software development.

- (void)configureCell:(UITableViewCell *)cell atIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.row == 0) {
        [cell.textLabel setText:@"Add Current Location"];
    } else {
        // Fetch Location
        NSDictionary *location = [self.locations objectAtIndex:(indexPath.row - 1)];
        // Configure Cell
        [cell.textLabel setText:[NSString stringWithFormat:@"%@, %@", location[MTLocationKeyCity], location[MTLocationKeyCountry]]];
    }
}

At the moment, the locations property is empty and so will the table view. In initWithNibName:bundle:, we invoke loadLocations, a helper method that loads the array of locations. In loadLocations, load the array of locations that is stored in the application’s user defaults database. Note that we use another string constant that we declared in MTConstants.h.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Load Locations
        [self loadLocations];
    }
    return self;
}

- (void)loadLocations {
    self.locations = [NSMutableArray arrayWithArray:[[NSUserDefaults standardUserDefaults] objectForKey:MTRainUserDefaultsLocations]];
}

Step 5: Delegate Assignment

As I mentioned earlier, the MTWeatherViewController instance will serve as the delegate of the locations view controller. Revisit MTAppDelegate.m and update application:didFinishLaunchingWithOptions: as shown below.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize View Controllers
    MTLocationsViewController *leftViewController = [[MTLocationsViewController alloc] initWithNibName:@"MTLocationsViewController" bundle:nil];
    MTForecastViewController *rightViewController = [[MTForecastViewController alloc] initWithNibName:@"MTForecastViewController" bundle:nil];
    MTWeatherViewController *centerViewController = [[MTWeatherViewController alloc] initWithNibName:@"MTWeatherViewController" bundle:nil];
    // Configure Locations View Controller
    [leftViewController setDelegate:centerViewController];
    // Initialize View Deck Controller
    self.viewDeckController = [[IIViewDeckController alloc] initWithCenterViewController:centerViewController leftViewController:leftViewController rightViewController:rightViewController];
    // Initialize Window
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    // Configure Window
    [self.window setRootViewController:self.viewDeckController];
    [self.window makeKeyAndVisible];
    return YES;
}

By making this change, a warning should immediately pop up telling you that MTWeatherViewController does not conform to the MTLocationsViewControllerDelegate protocol. The compiler is right so let’s fix this.

Open MTWeatherViewController.h, import the header file of MTLocationsViewController, and conform MTWeatherViewController to the MTLocationsViewControllerDelegate protocol.

#import <UIKit/UIKit.h>
#import "MTLocationsViewController.h"
@interface MTWeatherViewController : UIViewController <MTLocationsViewControllerDelegate>
@end

Wait. Another warning? We haven’t implemented the two required methods of the delegate protocol yet hence the warning. Open MTWeatherViewController.m and add a stub implementation for each of the delegate methods.

- (void)controllerShouldAddCurrentLocation:(MTLocationsViewController *)controller {
    NSLog(@"%s", __PRETTY_FUNCTION__);
}
- (void)controller:(MTLocationsViewController *)controller didSelectLocation:(NSDictionary *)location {
    NSLog(@"%s", __PRETTY_FUNCTION__);
}

Step 6: Fetching the Current Location

It is finally time to fetch the current location of the device. Add a class extension at the top of MTWeatherViewController.m and declare two properties, (1) location (NSDictionary) to store the application’s default location and (2) locationManager (CLLocationManager), which we will use to fetch the device’s location. Conform the MTWeatherViewController class to the CLLocationManagerDelegate protocol and declare an instance variable named _locationFound of type BOOL. The purpose of _locationFound will become clear in a few minutes.

#import "MTWeatherViewController.h"
@interface MTWeatherViewController () <CLLocationManagerDelegate> {
    BOOL _locationFound;
}
@property (strong, nonatomic) NSDictionary *location;
@property (strong, nonatomic) CLLocationManager *locationManager;
@end

In the class’s designated initializer, initWithNibName:bundle:, we initialize and configure the location manager. We assign the view controller as the location manager’s delegate and set the location manager’s accuracy property to kCLLocationAccuracyKilometer. There is no need for better accuracy as we only need the location for weather data.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Initialize Location Manager
        self.locationManager = [[CLLocationManager alloc] init];
        // Configure Location Manager
        [self.locationManager setDelegate:self];
        [self.locationManager setDesiredAccuracy:kCLLocationAccuracyKilometer];
    }
    return self;
}

The next piece of the puzzle is implementing, locationManager:didUpdateLocations:, one of the methods of the CLLocationManagerDelegate protocol, which is invoked each time the location manager has updated the device’s location. The second argument of locationManager:didUpdateLocations: is an array CLLocation instances. The implementation of locationManager:didUpdateLocations: also reveals the purpose of _locationFound. Despite the fact that we tell the location manager to stop updating the location as soon as locationManager:didUpdateLocations: is invoked, it is not uncommon that another update of the location invokes locationManager:didUpdateLocations: again even after sending the location manager a message of stopUpdatingLocation. If this were to happen, the same location would be added twice to the list of locations. The simple solution is to use a helper variable, _locationFound, that keeps track of the state that we’re in.

- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations {
    if (![locations count] || _locationFound) return;
    // Stop Updating Location
    _locationFound = YES;
    [manager stopUpdatingLocation];
    // Current Location
    CLLocation *currentLocation = [locations objectAtIndex:0];
    // Reverse Geocode
    CLGeocoder *geocoder = [[CLGeocoder alloc] init];
    [geocoder reverseGeocodeLocation:currentLocation completionHandler:^(NSArray *placemarks, NSError *error) {
        if ([placemarks count]) {
            _locationFound = NO;
            [self processPlacemark:[placemarks objectAtIndex:0]];
        }
    }];
}

We extract the first location from the array of locations and use the CLGeocoder class to reverse geocode that location. Reverse geocoding simply means finding out the name of the (closest) city and the location’s country. The completion handler of reverseGeocodeLocation: returns an array of placemarks. A placemark object is nothing more than a container for storing location data for a coordinate.

- (void)processPlacemark:(CLPlacemark *)placemark {
    // Extract Data
    NSString *city = [placemark locality];
    NSString *country = [placemark country];
    CLLocationDegrees lat = placemark.location.coordinate.latitude;
    CLLocationDegrees lon = placemark.location.coordinate.longitude;
    // Create Location Dictionary
    NSDictionary *currentLocation = @{ MTLocationKeyCity : city,
                                       MTLocationKeyCountry : country,
                                       MTLocationKeyLatitude : @(lat),
                                       MTLocationKeyLongitude : @(lon) };
    // Add to Locations
    NSUserDefaults *ud = [NSUserDefaults standardUserDefaults];
    NSMutableArray *locations = [NSMutableArray arrayWithArray:[ud objectForKey:MTRainUserDefaultsLocations]];
    [locations addObject:currentLocation];
    [locations sortUsingDescriptors:@[[NSSortDescriptor sortDescriptorWithKey:MTLocationKeyCity ascending:YES]]];
    [ud setObject:locations forKey:MTRainUserDefaultsLocations];
    // Synchronize
    [ud synchronize];
    // Update Current Location
    self.location = currentLocation;
    // Post Notifications
    NSNotification *notification2 = [NSNotification notificationWithName:MTRainDidAddLocationNotification object:self userInfo:currentLocation];
    [[NSNotificationCenter defaultCenter] postNotification:notification2];
}

In processPlacemark:, we extract the data that we’re looking for, city, country, latitude, and longitude, store it in a dictionary, and update the array of locations in the application’s user defaults database. Note that we sort the array of locations before updating the user defaults database. The view controller’s location property is updated with the new location and a notification is sent to notify any object interested in this event.

That’s not all, though. I have also overridden the setter of the view controller’s location property. Because the MTWeatherViewController class is in charge of adding new locations, we can delegate a few additional responsibilities to this class, such as updating the default location in the user defaults database. Because other parts of the application also need to know about a change in location, a notification with name MTRainLocationDidChangeNotification is posted. We also invoke updateView, another helper method that we will implement shortly.

- (void)setLocation:(NSDictionary *)location {
    if (_location != location) {
        _location = location;
        // Update User Defaults
        NSUserDefaults *ud = [NSUserDefaults standardUserDefaults];
        [ud setObject:location forKey:MTRainUserDefaultsLocation];
        [ud synchronize];
        // Post Notification
        NSNotification *notification1 = [NSNotification notificationWithName:MTRainLocationDidChangeNotification object:self userInfo:location];
        [[NSNotificationCenter defaultCenter] postNotification:notification1];
        // Update View
        [self updateView];
    }
}

Step 7: Adding a Label

We won’t spend much time on the user interface in this tutorial, but to make sure that everything works as we expect, it is good to have some visual feedback by adding a label to the weather view controller’s view displaying the selected location. Open MTWeatherViewController.h and create an outlet of type UILabel and name it labelLocation.

#import <UIKit/UIKit.h>
#import "MTLocationsViewController.h"
@interface MTWeatherViewController : UIViewController <MTLocationsViewControllerDelegate>
@property (weak, nonatomic) IBOutlet UILabel *labelLocation;
@end

Open MTWeatherViewController.xib, add a label to the view controller’s view, and connect the outlet with the newly added label (figure 6). In updateView (MTWeatherViewController.m), we update the label with the new location as shown below.

Figure 6: Adding the Location Label to the Weather View Controller

- (void)updateView {
    // Update Location Label
    [self.labelLocation setText:[self.location objectForKey:MTLocationKeyCity]];
}

Step 8: Implementing the Delegate Protocol

Thanks to the work we have done so far, implementing the two methods of the MTLocationsViewControllerDelegate protocol is easy. In controllerShouldAddCurrentLocation:, we tell the location manager to start updating the location. In controller:didSelectLocation:, we set the view controller’s location property to the location that the user selected in the locations view controller, which in turn invokes the setter method we overrode a bit earlier.

- (void)controllerShouldAddCurrentLocation:(MTLocationsViewController *)controller {
    // Start Updating Location
    [self.locationManager startUpdatingLocation];
}
- (void)controller:(MTLocationsViewController *)controller didSelectLocation:(NSDictionary *)location {
    // Update Location
    self.location = location;
}

4. Final Touches

Before wrapping up the first installment of this series, we need to add a few final touches. When the user launches the application, for example, the location property of the MTWeatherViewController class needs to be set to the location stored in the application’s user defaults. In addition, when the user launches our application for the very first time, a default location is not yet set in the application’s user defaults. This isn’t a big problem, but to offer a good user experience it would be better to automatically fetch the user’s current location when the application launches for the first time.

We can make both changes by amending the weather view controller’s viewDidLoad as shown below. The view controller’s location property is set to the location stored in the user defaults database. If no location is found, that is, self.location is nil, we tell the location manager to start updating the location. In other words, when the application is launched for the first time, the current location is automatically retrieved and stored.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Load Location
    self.location = [[NSUserDefaults standardUserDefaults] objectForKey:MTRainUserDefaultsLocation];
    if (!self.location) {
        [self.locationManager startUpdatingLocation];
    }
}

There is one more loose end that we need to tie up. When a new location is added to the array of locations, the weather view controller posts a notification. We need to update the MTLocationsViewController class so that it adds itself as an observer for these notifications. By doing so, the locations view controller can update its table view whenever a new location is added.

Revisit MTLocationsViewController.m and update the initWithNibName:bundle: as shown below. We add the view controller as an observer for notifications with a name of MTRainDidAddLocationNotification. The implementation of didAddLocation: is straightforward, that is, we add the new location to the array of locations, sort the array by city, and reload the table view.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Load Locations
        [self loadLocations];
        // Add Observer
        [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didAddLocation:) name:MTRainDidAddLocationNotification object:nil];
    }
    return self;
}

- (void)didAddLocation:(NSNotification *)notification {
    NSDictionary *location = [notification userInfo];
    [self.locations addObject:location];
    [self.locations sortUsingDescriptors:@[[NSSortDescriptor sortDescriptorWithKey:MTLocationKeyCity ascending:YES]]];
    [self.tableView reloadData];
}

Don’t forget to remove the view controller as an observer in the view controller’s dealloc method. It is also good practice to set the view controller’s delegate property to nil in dealloc.

- (void)dealloc {
    // Remove Observer
    [[NSNotificationCenter defaultCenter] removeObserver:self];
    if (_delegate) {
        _delegate = nil;
    }
}

Build and run the application to see how all this works together. You may want to run the application in the iOS Simulator instead of a on physical device, because the iOS Simulator supports location simulation (figure 7), which makes it much easier to test location based applications such as the one we created.

Figure 7: Simulating Locations with the iOS Simulator

Conclusion

Even though we haven’t even touched the Forecast API, we did quite a bit of work in this article. I hope you have tried CocoaPods and are convinced of its power and flexibility. In the next installment of this series, we focus on the Forecast API and the AFNetworking library.

iOS SDK: Customizing Popovers

Aaron Crabtree — Thu, 09 May 2013 15:47:26 +0000

Popovers are a great way to display supplementary information in an iPad app. Inevitably, as with most iOS objects, a little customization goes a long way in creating a design that is unique and fits in with your own app. In this tutorial, we will build a basic popover, then explore customizations one at a time, giving you an easy-to-follow path to implement customizations in your own app.

1. Setting Up Your Project

Step 1

Launch Xcode and choose File > New > Project to create a new project. Select an iOS Single View Application and click Next.

Figure 1

Step 2

Fill in the text fields with your project name, organization name, and company identifier. Select iPad from the Devices drop down and make sure the box next to Use Automatic Reference Counting is checked. Leave the boxes for Use Storyboards and Include Unit Tests unchecked and click Next. Choose a location to save your file and click Create.

Figure 2

2. Adding a Navigation Controller

Step 1

Let’s use a navigation controller so that we can add a button to show the popover. Click on AppDelegate.m and find the application:didFinishLaunchingWithOptions: method. Add the following code to create a navigation controller and set it as the root view controller.

UINavigationController *navController = [[UINavigationController alloc] initWithRootViewController:self.viewController];
self.window.rootViewController = navController;

Step 2

Now we can add a plus button to the navigation bar. Click on ViewController.m and add the following code to the viewDidLoad method just below [super viewDidLoad];.

UIBarButtonItem *popoverButton = [[UIBarButtonItem alloc]
initWithBarButtonSystemItem:UIBarButtonSystemItemAdd
                     target:self
                     action:@selector(showPopover:)];
self.navigationItem.rightBarButtonItem = popoverButton;

The UIBarButtonSystemItemAdd creates a plus button; we’ll add it to the right side of the navigation bar. Next we’ll implement the showPopover: method used as the selector.

3. Showing the Popover

Step 1

Before implementing the showPopover: method, let’s add a property for the popover controller. Click on the ViewController.h file and add the following property.

@property (nonatomic, strong) UIPopoverController *popController;

Step 2

Navigate back to the ViewController.m file and declare the showPopover: method in the class extension as demonstrated below.

@interface ViewController ()
- (void)showPopover:(id)sender;
@end

Step 3

Add the following code to define the method under @implementation.

- (void)showPopover:(id)sender
{
    if (self.popController.popoverVisible) {
        [self.popController dismissPopoverAnimated:YES];
        return;
    }
    UIViewController *contentViewController = [[UIViewController alloc] init];
    contentViewController.view.backgroundColor = [UIColor yellowColor];
    UIPopoverController *popController = [[UIPopoverController alloc] initWithContentViewController:contentViewController];
    popController.popoverContentSize = CGSizeMake(300.0f, 600.0f);
    self.popController = popController;
    [self.popController presentPopoverFromBarButtonItem:sender
                    permittedArrowDirections:UIPopoverArrowDirectionUp
                                    animated:YES];
}

First we check to see if the popover is already being shown on the screen. If it is visible, the popover is dismissed and the method returns. If the popover is not being shown on the screen, we create a view controller to be displayed in the popover. Then we create the popover controller and set its size. The last line of code tells the popover controller to present itself from the navigation bar button that was tapped – in this case the plus button -and allows the arrow direction to point up only. One benefit to using this method is that if the user taps another button on the navigation bar, the tap is passed through to the navigation bar.

4. Testing the Standard Popover

At this point, we have implemented a standard popover. Build and run your project and tap the plus button to see a basic popover appear. Let’s take a look at the basics of customizing its appearance.

5. Subclassing `UIPopoverBackgroundView`

Step 1

In order to customize the appearance of the popover, we’ll need to subclass UIPopoverBackgroundView. Click File > New > File, choose an iOS Cocoa Touch Objective-C Class, and click Next.

Figure 3

Step 2

Name the class PopoverBackgroundView and choose UIPopoverBackgroundView from the Subclass of drop down.

Figure 4

Step 3

There are two UIPopoverBackgroundView properties that need to be overridden. Add the following code to synthesize the arrow direction and arrow offset, overriding the setter and getter methods for these two properties.

@synthesize arrowDirection  = _arrowDirection;
@synthesize arrowOffset     = _arrowOffset;

Step 4

There are three class methods that need to be overridden. Let’s define some values to use with the methods.

#define kArrowBase 30.0f
#define kArrowHeight 20.0f
#define kBorderInset 8.0f

Step 5

Add the code below to override the arrowBase, arrowHeight and contentViewInsets methods.

+ (CGFloat)arrowBase
{
    return kArrowBase;
}
+ (CGFloat)arrowHeight
{
    return kArrowHeight;
}
+ (UIEdgeInsets)contentViewInsets
{
    return UIEdgeInsetsMake(kBorderInset, kBorderInset, kBorderInset, 		kBorderInset);
}

The arrowBase method determines the width of the arrow’s base, while the arrowHeight method determines the height of the arrow. The contentViewInsets method indicates how far from the edge of the background to display the content.

Step 6

Let’s add a background color so we can see the different pieces clearly. Add the following code inside the if statement in the initWithFrame: method.

self.backgroundColor = [UIColor grayColor];

6. Setting the Popover Background View Class Property

Before we can test the popover, we’ll need to import and set the popover controller’s popover background view class property. Click on the ViewController.m file and import the popover background view header file as demonstrated below.

#import "PopoverBackgroundView.h"

While we’re still in the ViewController.m file, add the following line of code just below where we created the UIPopoverController in the showPopover: method.

popController.popoverBackgroundViewClass = [PopoverBackgroundView class];

7. Testing the Popover Background View

Build and run the project and tap the plus button to see the popover. You can see that the standard popover has been replaced with the customizations we’ve added so far. The gray border around the popover shows the insets returned from the contentViewInsets method. You can adjust the insets as needed to achieve a desired look. We’ll draw an arrow later in the tutorial to display on the screen.

8. Setting the Shadows and Rounded Corners

The wantsDefaultContentAppearance method determines whether the default inset shadows and rounded corners are displayed in the popover. By returning NO, the popover background view will no longer show the default shadows and rounded corners, allowing you to implement your own. Add the following code to override the method.

+ (BOOL)wantsDefaultContentAppearance
{
    return NO;
}

Build and run the project and you will be able to see the difference.

9. Adding the Arrow

Step 1

We’ll need to create and manage the arrow ourselves; let’s declare a property for an image view that will display the arrow. Add the following code to the class extension.

@property (nonatomic, strong) UIImageView *arrowImageView;

Now we can instantiate the image view. Replace the code inside the if statement in initWithFrame: with the following code.

self.backgroundColor = [UIColor clearColor];
UIImageView *arrowImageView = [[UIImageView alloc] initWithFrame:CGRectZero];
self.arrowImageView = arrowImageView;
[self addSubview:self.arrowImageView];

Step 2

Let’s change the border inset by updating the the kBorderInset defined in PopoverBackgroundView.m with the following code.

#define kBorderInset 0.0f

Step 3

In order to draw the arrow, we’ll need to declare a method to perform the drawing. Add the following method declaration in the class extension in PopoverBackgroundView.m.

- (UIImage *)drawArrowImage:(CGSize)size;

Step 4

Now add the method definition under @implementation.

- (UIImage *)drawArrowImage:(CGSize)size
{
    UIGraphicsBeginImageContextWithOptions(size, NO, 0);
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    [[UIColor clearColor] setFill];
    CGContextFillRect(ctx, CGRectMake(0.0f, 0.0f, size.width, size.height));
    CGMutablePathRef arrowPath = CGPathCreateMutable();
    CGPathMoveToPoint(arrowPath, NULL, (size.width/2.0f), 0.0f);
    CGPathAddLineToPoint(arrowPath, NULL, size.width, size.height);
    CGPathAddLineToPoint(arrowPath, NULL, 0.0f, size.height);
    CGPathCloseSubpath(arrowPath);
    CGContextAddPath(ctx, arrowPath);
    CGPathRelease(arrowPath);
    UIColor *fillColor = [UIColor yellowColor];
    CGContextSetFillColorWithColor(ctx, fillColor.CGColor);
    CGContextDrawPath(ctx, kCGPathFill);
    UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();
    return image;
}

Instead of using an imported image, the code above programmatically creates the arrow.

Step 5

Each time the bounds of the popover background view subclass changes, the frame of the arrow needs to be recalculated. We can accomplish this by overriding layoutSubviews. Add the following code to PopoverBackgroundView.m.

- (void)layoutSubviews
{
    [super layoutSubviews];
	CGSize arrowSize = CGSizeMake([[self class] arrowBase], [[self class] arrowHeight]);
    self.arrowImageView.image = [self drawArrowImage:arrowSize];
    self.arrowImageView.frame = CGRectMake(((self.bounds.size.width - arrowSize.width) kBorderInset), 0.0f, arrowSize.width, arrowSize.height);
}

The frame of the arrow’s image view and the arrow’s image are calculated based on the bounds of the popover background view, the border’s insets, and the arrow’s base and height.

10. Testing the Popover

Build and run your project to see the customized popover. Even though the border inset is set to zero, the arrow is adjusted to line up with the inside edge of the right inset. By subtracting the border inset when determining the x coordinate for the image view frame for the arrow, we are able to align the image view appropriately.

Conclusion

This tutorial is designed to get you up and running with customizing a popover. There are many directions you can take the project from here; for example, adding another image view to display a custom border image. To do this, you would follow a similar pattern like we did when we created the image view for the arrow. Furthermore, you may want to customize the popover based on the arrow’s direction. In layoutSubviews, a series of if statements could help you test for the arrow’s direction so you could adjust the arrow accordingly. Leave a comment or question below if you have a specific direction you’d like to go with your customizations.

Build an AudioPlayer with PhoneGap: Application Tuning

Aurelio De Rosa — Wed, 08 May 2013 15:44:00 +0000

This is the third and final part of the series about Audero Audio Player. In this article, I will go over the remaining files so that you can finish the project and play around with it.

Series Overview

Style Tuning

jQuery Mobile does a lot of the work for you by enhancing pages’ elements for devices with smaller screens. However, there are some that I don’t care for, and we’ll adjust these in our style.css file. This is also used to style the player’s markup.

By default, even if you don’t have buttons within the header or the footer of a page, the framework still reserves some space on both side of the elements and truncates long titles. This behavior is applied to other elements as well. We can change it simply by applying the rule white-space: normal !important; to our targeted elements as .ui-title.

The source of the stylesheet is shown here:

.ui-header .ui-title,
.ui-footer .ui-title,
.ui-btn-inner *
{
  white-space: normal !important;
}
.photo
{
  text-align: center;
}
#player-play,
#player-stop
{
  display: inline-block;
  width: 48px;
  height: 48px;
}
#player-play
{
  background-image: url('../images/play.png');
}
#player-stop
{
  background-image: url('../images/stop.png');
}
#time-slider
{
  display: none;
}
div.ui-slider-track
{
  margin: 0;
  width: 100%;
}

jQuery Mobile Custom Configuration

jQuery Mobile has a default configuration that should be good enough for most projects with simple requirements. However, there will be times when you will want to modify or take control of some default behavior. You can achieve this by writing a configuration file. The file jquery.mobile.config.js is exactly where we’ll have the configuration. Please note that you must include the configuration file before the jQuery Mobile files. When jQuery Mobile starts, it fires the mobileinit event, which is the one you must bind to override the default settings.

We’ll make the change by assigning values to the properties of the $.mobile object. I won’t change a lot of properties. I’ll instead change the option to have the text shown on the page loader widget, and the theme.

The full source of the file is listed below:

$(document).on(
   'mobileinit',
   function()
   {
      // Page Loader Widget
      $.mobile.loader.prototype.options.text = 'Loading...';
      $.mobile.loader.prototype.options.textVisible = true;
      // Theme
      $.mobile.page.prototype.options.theme  = 'a';
      $.mobile.page.prototype.options.headerTheme = 'a';
      $.mobile.page.prototype.options.contentTheme = 'a';
      $.mobile.page.prototype.options.footerTheme = 'a';
      $.mobile.page.prototype.options.backBtnTheme = 'a';
   }
);

Build Configuration

The Adobe PhoneGap Build service gives you the ability to specify the metadata of an application, like author and description, by using a configuration file. This file is called config.xml. Explaining the format in depth is outside the scope of this series, but I’ll give you a brief overview. If you want to read more on this topic, take a look at the official documentation page.

The config.xml file follows the W3C widget specification and must stay inside the app’s root, at the same level of the index.html file. Its first line is the XML declaration, and the root of the document is a <widget> tag that has several possible attributes. The most important ones are id (the unique identifier for your project), and version (which specifies the version of the application). Inside the <widget> tag, you can write the metadata of your application. In our file we’ll use a lot of them, but the most important are the following:

name (required): The name of the application. It doesn’t have to be unique.
description (required): The description of the application. It’s particularly important because it will be shown in the app’s marketplace listing.
icon (optional): The icon to display on the devices that will install your app. If you do not specify it, the Cordova logo will be used.
splash (optional): This tag sets the splash screen of the application, which is the image shown during loading.
feature (optional): Specifies the features you want to use. For example, Android, before installing any app, shows the user the permissions it requires and, if the user agrees, it goes on.
preference (optional): A set of preferences you want to apply to your app. It’s a closed tag and you can have zero or more <preference> tags inside the file. It has two attributes, and both are required: name and value. There are a lot of preferences that you can define, but the most important one in my opinion is specifying the Cordova version used.

The <access> tag is also very important because, to cite the documentation, it provides your app with access to resources on other domains – in particular, it allows your app to load pages from external domains that can take over your entire webview. Recalling what we discussed in the section Managing External Links from the previous post, to open the external links in the Cordova WebView, we must add them to the app whitelist. Since our application won’t retrieve links from external and unsafe sources, we can shorten the process to allow for any external resource using the * special character. For example:

<access origin="*" />

I’ve pointed out the key points of the format, and now you can understand the source of the configuration file. The complete file is below:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns     = "http://www.w3.org/ns/widgets"
        xmlns:gap = "http://phonegap.com/ns/1.0"
        id        = "com.audero.free.player.auderoaudioplayer"
        version   = "1.0.0">
   <name>Audero Audio Player</name>
   <description>Audero Audio Player is a basic audio player that collects the audio files and then allows the user to listen to them. This app also enables you to update the list at any time to include other files that may have been downloaded after running the operation for the first time. You can also remove any unwanted audio from the list by clicking an icon on the right side of the song's name. The sound list is ordered alphabetically with letter dividers to organize and group the list items, and has a search box to filter the files.</description>
   <author href="http://www.audero.it" email="aurelioderosa@gmail.com">Aurelio De Rosa</author>
   <feature name="http://api.phonegap.com/1.0/network"/>
   <feature name="http://api.phonegap.com/1.0/media"/>
   <feature name="http://api.phonegap.com/1.0/file"/>
   <feature name="http://api.phonegap.com/1.0/notification"/>
   <preference name="phonegap-version" value="2.3.0" />
   <preference name="target-device" value="universal" />
   <access origin="*" />
   <!-- Icons -->
   <icon src="icon.png" width="64" height="64" gap:role="default" />
   <icon src="images/icon-72x72.png" width="72" height="72" gap:platform="android" gap:density="hdpi" />
   <icon src="images/icon-96x96.png" width="96" height="96" gap:platform="android" gap:density="xhdpi" />
   <icon src="images/icon-72x72.png" width="72" height="72" gap:platform="ios" />
   <!-- Splash Screens -->
   <gap:splash src="splash.png" />
   <gap:splash src="images/splash-160x220.png" gap:platform="android" gap:density="ldpi" />
   <gap:splash src="splash.png" gap:platform="android" gap:density="mdpi" />
   <gap:splash src="images/splash-450x650.png" gap:platform="android" gap:density="hdpi" />
</widget>

Running the Application

In the last section, all the business logic, HTML and CSS files for the application were built, so now it’s time to set the entry functions for the application and play. The targeted function will be the initApplication() method of the Application class. It will run once Cordova is fully loaded, ensuring that you can safely call the Cordova APIs. To do this, we’ll set initApplication() as a callback function for the deviceready event by adding the following code to the index.html file. You can see this by looking at the next snippet:

<script>
  $(document).on('pagebeforecreate orientationchange', Application.updateIcons);
  $(document).one('deviceready', Application.initApplication);
</script>

Possible Improvements

You are now at the end of the project. That being said, every project has room for improvements and new feature, so before I conclude the series, I would like to suggest some of these to you.

The first feature that you can add is the internationalization (i18n) of the application. Our player doesn’t have much text, so translating it into other languages should be very easy. To translate the application, you can use the Globalization API, an API added to the core starting from version 2.2.0. In addition, a specific jQuery library like jquery-i18n-properties or jQuery-i18n would surely be useful for this feature.

Other minor suggestions are:

Allow the user to create playlist.
Create a “Play All” button to play all the songs in the list.
Create a ratings system for the audio so that the user can filter and order songs by rating.
Add a “Repeat” button so that the user can continue listening to the current song.

These suggestions are just some of the potential improvements you can make to the Audero Audio Player. Using the information from this tutorial and your own skills, you can do much, much more.

Conclusion

As you’ve seen throughout this series, you can build powerful and useful apps using web technologies and popular frameworks. Now it’s your turn to play around with this project. Try starting your own project to test what you learned in this series!

Tuts+ Premium Cash Back Offer: 3 Days to Go

Joel Bankhead — Tue, 07 May 2013 16:30:36 +0000

This offer ends soon! Act now and don’t miss out on cash back when trying a monthly Tuts+ Premium subscription.

At $19 a month, Tuts+ Premium is fantastic value. But it’s even better when we hand your first $19 right back to you!

For a limited time we’re offering $19 cash back to new Tuts+ Premium monthly subscribers when signing up via PayPal. If you’ve been thinking about checking out our extensive library of courses, tutorials, eBooks and guides there’s never been a better time to join up and dive in.

This offer ends at noon on the 20th of May AEST, so act fast.

Become a Tuts+ Premium Member and take your creative & technical skills to a new level.

What can you learn on Tuts+ Premium? Glad you asked! Currently, more than 15,000 members are sharpening their skills in a wide range of areas including web design, web development, Photoshop, vectors, video effects, and many more.

With Tuts+ Premium you learn from expert instructors in every field, such as:

Designer Justin Maller (Nike, Verizon, DC Shoe Co.)
Illustrator Russell Tate (McDonald’s, Coca-Cola)
Developer Burak Guzel (Software Engineer at Facebook)

Join now and get instant access to your very own library of courses, tutorials, and eBooks, available whenever you need them. Become part of a community of over 15,000 members and start getting better at the skills you care about. Our dedicated team adds new content weekly, so there’s always something fresh to sink your teeth into.

Join Tuts+ Premium

How To Submit an iOS App to the App Store

Bart Jacobs — Mon, 06 May 2013 17:09:11 +0000

You have worked weeks or months on your first iOS application and you are ready to submit your masterpiece to Apple’s App Store. How do you do this? Is your application ready for submission? I am sure that some of these questions have entered your mind at one point or another. Is submitting an application as simple as sending Apple your application’s binary? Not quite. With this tutorial, I will provide you with a detailed map to get your application submitted to Apple’s App Store.

Introduction

Even though the App Store review process is a black box for the most part, that doesn’t mean that you can’t prepare yourself and your application for Apple’s review process. Apple provides guidelines to help you stay within the sometimes invisible boundaries of what is and isn’t allowed in the App Store.

The first time you submit an application to the App Store is exciting and nerve-racking at the same time. Even for experienced iOS developers, submitting an application to the App Store is often a stressful undertaking because it is something that most developers don’t do on a daily basis.

Throughout this article, I am assuming that you are a registered iOS developer which means that you are enrolled in Apple’s iOS Developer Program and are allowed to submit applications for publication in the App Store. To submit an iOS application to the App Store, you need to be a registered iOS developer. Red flag? Don’t worry. You can enroll in Apple’s iOS Developer Program by visiting this link and clicking the Enroll Now button.

Figure 1: Enrolling in Apple’s iOS Developer Program

1. Is your application ready?

Step 1: Testing

An application isn’t necessarily ready when you’ve written the last line of code or implemented the final feature of the application’s specification. Have you tested your application on one or more physical devices? Have you profiled your application for memory leaks and performance issues? Does your application crash from time to time? The family of iOS devices has grown substantially over the past years and it is important to test your application on as many iOS devices as you can lay your hands on. Common issues include not optimizing an application for the iPhone 5′s 4″ screen or the iPad Mini’s 7.9″ screen.

The iOS Simulator is a great tool, but it runs on your Mac, which has more memory and processing power than the phone in your pocket. I can assure you that the differences in performance between an old(er) iPhone 3GS and an iPhone 5 are like night and day. As an iOS developer, you should never get rid of an old iOS device as long as you build or maintain applications that can run on any of these older devices.

Apple’s Review Process isn’t airtight, but it is very capable of identifying problems that might affect your application’s user experience. If your application crashes from time to time or it becomes slow after ten minutes of use, then you have some work to do before submitting it to the App Store. Even if Apple’s review team doesn’t spot the problem, your users will. If the people using your application are not pleased, they will leave bad reviews on the App Store, which may harm sales or inhibit downloads.

Step 2: Rules and Guidelines

As I mentioned earlier, Apple provides developers with a number of documents that are a great help during the creation and development process of your application. The documents that you should be aware of are the iOS Human Interface Guidelines and the App Store Review Guidelines. Despite the availability of these documents, it seems that few developers take the time to browse them, let alone read them. It shouldn’t be a surprise that some applications are therefore rejected even though the reason for the rejection is clearly stated in these documents.

Even if you don’t intend to read the iOS Human Interface Guidelines or the App Store Review Guidelines, it is important to know about some of the rules that they talk about. Take a look at the short list below to get an idea of what your application should and shouldn’t do.

Your application …

doesn’t crash.
shouldn’t use private API’s.
shouldn’t replicate the functionality of native applications.
should use In App Purchase for in-app (financial) transactions.
shouldn’t use the camera or microphone without the user’s knowledge.
only uses artwork that you have the copyright of or you have permission to use.

Keep in mind that this is a tiny subset of the guidelines included in the aforementioned documents. The majority of the rules and guidelines are trivial, but some are not and you might even violate some of them inadvertently. Let me give you an example. Before Apple started using its own maps, the MapKit framework used Google’s maps. This was clear to the user because of the small Google logo in the bottom left corner of each map. However, if some part of your application’s user interface covered or obscured Google’s logo, your application would get rejected. This rule seems trivial, but it is a rule that is easily violated if you’re not careful. Even automated tests won’t cover you in this case.

2. Prerequisites

Before you can even start thinking about submitting your application to the App Store, you need to make sure that you have an App ID, a valid distribution certificate, and a valid provisioning profile. Let me show you what this entails.

Step 1: App ID

Every application needs an App ID or application identifier. There are two types of application identifiers, (1) an explicit App ID and (2) a wildcard App ID. A wildcard App ID can be used for building and installing multiple applications. Despite the convenience of a wildcard App ID, an explicit App ID is required if your application uses iCloud or makes use of other iOS features, such as Game Center, Apple Push Notifications, or In App Purchase.

If you’re not sure what App ID best fits your project, then I recommend reading Technical Note QA1713 for more information about this topic.

Step 2: Distribution Certificate

To submit an application to the App Store, you need to create an iOS provisioning profile for distribution. To create such a provisioning profile, you first need to create a distribution certificate. The process for creating a distribution certificate is very similar to creating a development certificate. If you have tested your application on a physical device, then you are probably already familiar with the creation of a development certificate.

If you need to refresh your memory, I suggest reading Apple’s detailed guide about signing certificates and provisioning profiles. The process is not difficult once you understand how the various pieces of the puzzle fit together.

Step 3: Provisioning Profile

Once you’ve created an App ID and a distribution certificate, you can create an iOS provisioning profile for distributing your application through the App Store. Keep in mind that you cannot use the same provisioning profile that you use for ad hoc distribution. You need to create a separate provisioning profile for App Store distribution. If you use a wildcard App ID for your project, then you can use the same provisioning profile for multiple applications.

Step 4: Build Settings

With the App ID, distribution certificate, and provisioning profile in place, it is time to configure your target’s build settings in Xcode. This means selecting the target from the list of targets in Xcode’s Project Navigator, opening the Build Settings tab at the top, and updating the settings in the Code Signing section to match the distribution provisioning profile you created earlier. Newly added provisioning profiles are sometimes not immediately visible in the Code Signing section of the build settings. Quitting and relaunching Xcode remedies this issue.

Figure 2: Configuring the Target’s Build Settings

Even though the code signing process is fairly simple once you understand it, it is something that trips up a lot of developers. I don’t know a single Cocoa developer who hasn’t run into code signing issues at some point in their career. Once you’ve taken this hurdle, the rest of the submission process is fairly easy.

Step 5: Deployment Target

It is useful to write a few words about your application’s deployment target. Each target in an Xcode project, has a deployment target, which indicates the minimum version of the operating system that the application can run on. It is up to you to set the deployment target, but keep in mind that modifying the deployment target is not something you can do without consequences once your application is in the App Store. If you increase the deployment target for an update of your application, then users who already purchased your application but don’t meet the new deployment target, cannot run the update. It gets really problematic when a user downloads an update through iTunes (not the device), replacing the previous version on their computer, and then discovers that the new update doesn’t run on their device.

I have two very simple tips with regards to your application’s deployment target. (1) Be very careful when you decide to increase the deployment target of an existing application. Mention this in the application’s release notes of the updates that precede the change and again in the update that uses the new deployment target. If your warn your customers well in advance, you have done all you can to prevent potential problems. (2) For new applications, I almost always set the deployment target to the last major release, iOS 6 at the time of writing. Because of the incredible adoption rate of new iOS releases, there is no harm in doing this. Some people think that they miss out on a large chunk of the market, but that is not true. Take the release of iOS 6 as an example. One month after the release of iOS 6, more than 60% of iOS devices had upgraded to the new version of iOS. Unfortunately, the same isn’t true for Android.

3. Assets

Step 1: Icons

You probably know that an application icon is a vital component of every iOS application, but you need to make sure that your application ships with the correct sizes of the artwork. Take a look at the list below for an overview.

iTunes Artwork: 1024px x 1024px (required)
iPad/iPad Mini: 72px x 72px and 114px x 114px (required)
iPhone/iPod Touch: 57px x 57px and 114px x 114px (required)
Search Icon: 29px x 29px and 58px x 58px (optional)
Settings Application: 50px x 50px and 100px x 100px (optional)

It goes without saying that you don’t need to include an application icon for the iPad/iPad Mini device family if your application only targets the iPhone/iPod Touch device family, and vice versa.

Step 2: Screenshots

Each application can have up to five screenshots and you must provide at least one. If you are developing a universal application, then you need to provide separate screenshots for iPhone/iPod Touch and iPad/iPad Mini. In addition, you can optionally include separate screenshots for the 3.5″ and the 4″ screen sizes of the iPhone/iPod Touch. This is quite a bit of work and you want to make sure that the screenshots show your application from its best side. Shiny Development sells a Mac application, Status Magic that helps you get the status bar in your screenshots right. Status Magic will save you quite a bit of time.

It is important to spend some time thinking about the screenshots. Your application’s screenshots are often the only thing that a customer can use to decide whether she purchases or downloads your application or not. What a lot of developers don’t know is that the screenshots don’t have to be actual screenshots. The hard rule is that the size of each screenshot needs to be that of the screen size of the target device. Many companies are creative with this rule. Take a look at the screenshots of Where’s My Water?, for example. By using this strategy, screenshots can be much more attractive and compelling.

Step 3: Metadata

Before you submit your application, it is a good idea to have your application’s metadata at hand. This includes (1) your application’s name, (2) the version number, (3) the primary (and an optional secondary) category, (4) a concise description, (5) keywords, and (6) a support URL. If you are submitting an update, then you can also provide information for the What’s new in this Version section.

Does your application require users to sign in? Then you also need to provide Apple with a test or demo account to make sure that the review team can immediately sign in and use your application without first having to sign up for an account.

4. Submission Preparation

The submission process has become much easier since the release of Xcode 4. You can now validate and submit an application using Xcode, for example. First, however, you need to create your application in iTunes Connect.

Visit iTunes Connect, sign in with your iOS developer account, and click Manage Your Apps on the right. Click the Add New App in the top left, select iOS App, and fill out the form.

Figure 3: Visit iTunes Connect to Get Started

Step 1: Basic Information

The App Name, which needs to be unique, is the name of your application as it will appear in the App Store. This can be different than the name that is displayed below your application icon on the home screen, but it is recommended to choose the same name. The SKU Number is a unique string that identifies your application. I usually use the application’s bundle identifier. The last piece of information is the Bundle ID of your application. This means selecting the (wildcard or explicit) App ID that you created earlier from the drop down menu.

Figure 4: Specifying Name, SKU Number, and Bundle ID

Step 2: Price and Availability

In the next step, you specify your application’s price and availability. Apple works with price tiers so that you don’t have to specify a price for each country that Apple operates in. You can also specify in which stores your application should – or shouldn’t – be available. The information that you enter in this step can be modified once your application is live in the App Store. In other words, you can change the price and availability of an application without having to submit an update.

Figure 5: Specifying Price and Availability

Step 3: Metadata

We’ve already covered the application’s metadata. The only aspect that I haven’t talked about yet is your application’s rating. Based on your application’s content and functionality, it is given a rating. This rating is not only useful for telling users about your application’s content and features, the rating is also used by the operating system for the parental controls features.

It is strongly recommended that you don’t try to outsmart the rating system. Apple is well aware of this and will reject your application if it doesn’t agree with the rating that you have set.

Figure 6: Entering Your Application’s Metadata and Assigning a Rating

Step 4: Ready to Upload Binary

Once your application’s metadata is submitted, you will be presented with a summary of your application. Under Versions, you should see the version that you submitted a moment ago. Click the View Details button and click the Ready to Upload Binary button in the top right. You are then asked one or more questions regarding your application and, if all went well, you should see a message telling you that you are now ready to upload your application binary. The status of your application has changed to Waiting for Upload.

Figure 7: Your Application’s Summary

5. Uploading Binary

To submit your application, you need to create an archive of your application. You can only create an archive by building your application on a physical device. If you select the iOS Simulator in the active scheme, you will notice that the Archive option in Xcode’s Product menu is grayed out. Connect an iOS device to your Mac, select it in the active scheme, and select Archive from Xcode’s Product menu.

Figure 8: Archiving Your Application using Xcode

If all went well, you should now have an archive and Xcode’s Organizer should automatically open and show you the archive you just created. Select the archive from the list and click the Distribute… button on the right. From the options you are presented with, select Submit to the iOS App Store. After entering your iOS developer account credentials and selecting the Application and Code Signing Identity, the application binary is uploaded to Apple’s servers. During this process, your application is also validated. If an error occurs during the validation, the submission process will fail. The validation process is very useful as it will tell you if there is something wrong with your application binary that would otherwise result in a rejection by the App Store review team.

Figure 9: Archiving Your Application using Xcode

Figure 10: Submit Your Application to the iOS App Store

Figure 11: Enter Your iOS Developer Account Credentials

Figure 12: Select Application and Code Signing Identity

Figure 13: An Error is Shown if Validation Fails

6. Waiting

If the submission process went without problems, your application’s status will change to Waiting for Review. It takes several days for Apple to review your application and the time it takes, tends to fluctuate over time. To get an idea of the average review times of iOS and Mac applications, I recommend visiting the website of Shiny Development (Dave Verwer). This will give you a good indication of how long the review process will take.

Conclusion

The submission process is quite lengthy for a new application, but submitting an update to the App Store is much less cumbersome. Keep in mind that the submission process is much more involving if your application is localized in various languages as your application’s metadata needs to be localized as well. However, localizing your application is well worth the effort as it often results in higher sales and positive customer feedback.

Mobiletuts+

iOS SDK: Advanced UIImage Techniques

Theoretical Overview

1. Starting a New Project

2. Creating an Image in Code

3. Resizable Images

4. Animated Images

Conclusion

Android SDK: Create a Barcode Reader

1. Create a New Android Project

Step 1

Step 2

2. Add ZXing to Your Project

Step 1

Step 2

3. Do Some Scanning

Step 1

Step 2

4. Retrieve Scanning Results

Step 1

Step 2

Step 3

Conclusion

Create a Weather App with Forecast – API Integration

Introduction

1. Subclassing AFHTTPClient

Step 1: Create the Class

Step 2: Creating a Singleton Object

Step 3: Configuring the Client

Step 4: Adding a Helper Method

2. Querying the Forecast API

Step 1: Amend setLocation:

Step 2: Sending the Request

3. Reachability

4. Refreshing Data

Bonus: Removing Locations

Conclusion

Reading NFC Tags with Android

What is NFC?

NFC Technologies

Adding NFC Support in an App

How to Filter for NFC Tags

NFC Intent Filter

Tech Discovered Intent

NDEF Discovered Intent

Foreground Dispatch

Reading Data From an NDEF Tag

Useful Apps

Conclusion

About the Author

Sources

Connecting to an External Database With NuSOAP

1. Install the Software

2. Creating an External Database

Step 1

Step 2

Step 3

3. NuSOAP Server – Starting Web Service

Step 1

Step 2

Step 3

4. Writing Web Service Functions

Step 1

Step 2

Step 3

5. Creating a Simple Layout for a Windows Phone Application

Step 1

Step 2

6. Connecting to Service

7. Writing Windows Phone Functions

Step 1

Step 2

8. Testing

Conclusion

Create a Weather App with Forecast – Project Setup

Introduction

1. Project Setup

Step 1: Creating the Project

Step 2: Adding Libraries

Step 3: Adding Dependencies

1. Subclassing `AFHTTPClient`

Step 1: Amend `setLocation:`

5. Subclassing `UIPopoverBackgroundView`