Introduction to Coding Guidelines for Cocoa

Developing a Cocoa framework, plug-in, or other executable with a public API requires some approaches and conventions that are different from those used in application development. This is where API naming conventions come in handy, to make the interfaces consistent and clear. There are also programming techniques that are special to—or of greater importance with—frameworks, such as versioning, binary compatibility, error-handling, and memory management. This topic includes information on both Cocoa naming conventions and recommended programming practices for frameworks.

Link: Introduction to Coding Guidelines for Cocoa

googledocs-cocoa-sample: Example iPhone project showing how to use GData API for Google Docs from Objective-C.

This sample iPhone application demonstrates how to use the GData API Objective-C library to log in, upload, download and rename files in Google Docs, including support for documents inside multiple levels of folders.

There are two ways to use the code.

First, the GoogleDocs.m/.h can be used as-is and plugged into an iPhone app. It should also work in a Mac OS X Cocoa app with little or no changes needed.

Second, GoogleDocs.m/.h shows an example of how to use various aspects of the GData Objective-C API. By seeing how this code works, a developer can learn the underlying API to create their own interface.

Additionally, the code demonstrates a method for packing up binary/non-user editable data files and uploading them as HTML files, then downloading and decoding the original content.

The sample application fully exercises the included interface in an app that will run on an iPhone, iPod Touch and the iPhone Simulator.

link: googledocs-cocoa-sample Project Home

Tag Attribute

Tag is a property of UIView objects, includeing views an controls. It's a number assigned to any UIView object, and will keep no change in you application.

For example, if you have more than one object, which trigger the same action method, how can you identify the actual source of the event? Tag is a good solution. As shown in my previouse exercise "Change UIView.backgroundColor using UIColor".

 UISlider *sliderRed = (UISlider *)[self.view viewWithTag:10];
 UISlider *sliderGreen = (UISlider *)[self.view viewWithTag:11];
 UISlider *sliderBlue = (UISlider *)[self.view viewWithTag:12];

Assign Tag using Interface Builder

In Interface Builder with the UIView object select, there is a Tag property in the Inspector pane, as shown in the figure. You can enter the value you want. And also you can check this Tag value in your code to identify the object.

General steps to define and connect a IBOutlet

In Xcode development, controller class refer to object in xib using a special kind of instance variable, outlet. Outlet are declared with a special keyword, IBOutlet.

Typically, the declaration of an outet is look like this:
@property (nonatomic, retain) IBOutlet UILabel *outlet;

As a example, the text of a Label will be changed in our controller class.

modify the header file, in form of xxxViewController.h, to add declaration of the outlet.

@interface exampleViewController : UIViewController {
 UILabel *outlet
}
@property (nonatomic, retain) IBOutlet UILabel *outlet;
- (IBAction)actionMethod:(id)sender;
@end

Modify inside definition file, xxxViewController.m, to access the object using the outlet.

@implementation exampleViewController
@synthesize outlet;
-(IBAction)actionMethod:(id)sender{
 outlet.text = @"Access using outlet";
}

and have to release it in the method dealloc

- (void)dealloc {
    [outlet release];
    [super dealloc];
}

Save your works.

Connect IBOutlet in INterface Builder:

Double click on the xxxViewController.xib in Groups & Files pane, under Resources folder, to start Interface Builder.

Drag the object you want from Library to View pane, if you haven't placed it.

Hold down the Control key and drag (or drag by right button on mouse) the File's Owner in xib to over the object in View.

Release mouse button, the available outlets will be listed, select the outlet you want to connect.

that's.

General steps to implement and connect a IBAction

In Xcode development, interface objects (such as button, slider...) are "placed" using Interface Builder (IB). It will generate a event (such as Touch Up) to trigger a action method in the controller class.

Action Methods are declared with a special keyword, IBAction, which tells Interface Builder that tis is a action method, and can be triggered by a control objects. Typically, the declaration of an action method is look like this:
- (IBAction)actionMethod:(id)sender;

As a example, a button will be used to generate a Touch Up event, to trigger a action method, actionMethod() in controller class.

modify the header file, in form of xxxViewController.h, to add declaration of the Action Method.

@interface xxxViewController : UIViewController {
}
- (IBAction)actionMethod:(id)sender;
@end 

Define the body of the Action Method inside definition file, xxxViewController.m.

#import "helloiphoneViewController.h"

@implementation helloiphoneViewController
-(IBAction)actionMethod:(id)sender{
 //do something...
}

Save your works.

Connect IBAction in INterface Builder:

Double click on the xxxViewController.xib in Groups & Files pane, under Resources folder, to start Interface Builder.

Drag the control you want from Library to View pane, if you haven't placed it.

Open the Connection Inspector from Tools on top menu.

Click on to select the control object you want to connect the IBAction.

A list of available events will be listed inside the Connection Inspector. Select the event you expect to trigger the action, drag the circle on the right of it, to over File's Owner on xib pane.

Release mouse button, the available action methods will be listed, click to select the right one.

Connection Inspector will be updated to have the new connection.

Save your works.

that's.

Change UIView.backgroundColor using UIColor

In this exercise, I will create a simple iPhone application with three sliders to change the background color.

It will have three sliders on screen, with Tag 10, 11 and 12, to control the colors of red, green blue. At start-up, all the initiate values are set to 0, also the background will be in black. Whenever any slider's value changed, the values of all the sliders will be read and update UIView.backgroundColor accordingly.

- Create a iPhone Application using View-base Application template, xcodeBackgroundColor.

- Modify xcodeBackgroundColorViewController.h to have a (IBAction)sliderChanged:(id)sender.

#import <UIKit/UIKit.h>

@interface xcodeBackgroundColorViewController : UIViewController {

}
- (IBAction)sliderChanged:(id)sender;
@end

- Modify xcodeBackgroundColorViewController.m to implement (IBAction)sliderChanged:(id)sender.

#import "xcodeBackgroundColorViewController.h"

@implementation xcodeBackgroundColorViewController
- (IBAction)sliderChanged:(id)sender { 
    UISlider *sliderRed = (UISlider *)[self.view viewWithTag:10];
 UISlider *sliderGreen = (UISlider *)[self.view viewWithTag:11];
 UISlider *sliderBlue = (UISlider *)[self.view viewWithTag:12];
 CGFloat red = sliderRed.value;
 CGFloat green = sliderGreen.value;
 CGFloat blue = sliderBlue.value;
 self.view.backgroundColor = [UIColor colorWithRed:red green:green blue:blue alpha:1.0f];
} 
...

Save the works.
- Double click on xcodeBackgroundColorViewController.xib to start Interface Builder.
Click on the View to change the background to Black.

Place three Sliders on the View, set minimum=0.0, maximum=1.0, and initial=0.0. Set Tag=10, 11 and 12 respectively.

Select each Slider on it, connect the IBAction of Value Changed to sliderChanged:

- Open Connection Inspector from Tools -> Connection Inspector, or select the second tag on Inspector.

- Click on the Slider to select it. Drag the circle on the right of Value Changed over the File's Owner in xcodeBackgroundColorViewController.xib.

Release and select ValueChanged.

Repeat on all the three sliders. Save the works.

Build and Go in Xcode.

UIColor

A UIColor object represents color and sometimes opacity (alpha value). You can use UIColor objects to store color data, and during drawing you can use them to set the current fill and stroke colors.
Many methods in UIKit require you to specify color data using a UIColor object, and for general color needs it should be your main way of specifying colors.

In the coming exercise, Change UIView.backgroundColor using UIColor, I will create a simple iPhone application to change UIView.backgroundColor using UIColor.

Change alpha of Image View

In the last exercise, "Implement a Slider", the Image View is a static image element without any interaction. In this exercise, It's alpha will be changed according to the slider value.

Modify ImageViewViewController.h to add a IBOutlet, imageView, which will be point to the Image View.

#import <UIKit/UIKit.h>

@interface ImageViewViewController : UIViewController {
 UILabel     *sliderValue;
 UIImageView *imageView;
}
@property (nonatomic, retain) IBOutlet UILabel *sliderValue;
@property (nonatomic, retain) IBOutlet UIImageView *imageView;
- (IBAction)sliderChanged:(id)sender;
@end

Modify ImageViewViewController.m, to update imageView.alpha according to the slider.value.

#import "ImageViewViewController.h"

@implementation ImageViewViewController
@synthesize sliderValue; 
@synthesize imageView;
- (IBAction)sliderChanged:(id)sender { 
    UISlider *slider = (UISlider *)sender; 
    NSString *newText = [[NSString alloc] initWithFormat:@"%1.2f", 
       slider.value]; 
    sliderValue.text = newText; 
 imageView.alpha = slider.value;
    [newText release]; 
} 

- (void)didReceiveMemoryWarning {
    // Releases the view if it doesn't have a superview.
    [super didReceiveMemoryWarning];
 
    // Release any cached data, images, etc that aren't in use.
}

- (void)viewDidUnload {
 // Release any retained subviews of the main view.
 // e.g. self.myOutlet = nil;
}


- (void)dealloc {
 [sliderValue release];
 [imageView release];
    [super dealloc];
}

@end

Connect Outlet to Image View:

Drag the File's Owner by right button on mouse in ImageViewViewController.xib to over the Image View in View. Release and select imageView.

Save your work, and Build and Run in Xcode.

Implement a Slider

In this article, we are going to add a slider with a label to reflect he value of the slider, over the last exercise "Load a Image View in iPhone".

So we need a Action Method for the slider, sliderChanged, to receive the event. And a outlet to the label, sliderValue, to update the text according to the slider value.

Modify ImageViewViewController.h:

#import <UIKit/UIKit.h>

@interface ImageViewViewController : UIViewController {
 UILabel     *sliderValue;
}
@property (nonatomic, retain) IBOutlet UILabel *sliderValue;
- (IBAction)sliderChanged:(id)sender;
@end

Modify ImageViewViewController.m:

#import "ImageViewViewController.h"

@implementation ImageViewViewController
@synthesize sliderValue; 
- (IBAction)sliderChanged:(id)sender { 
    UISlider *slider = (UISlider *)sender; 
    NSString *newText = [[NSString alloc] initWithFormat:@"%1.2f", 
       slider.value]; 
    sliderValue.text = newText; 
    [newText release]; 
} 

- (void)didReceiveMemoryWarning {
    // Releases the view if it doesn't have a superview.
    [super didReceiveMemoryWarning];
 
    // Release any cached data, images, etc that aren't in use.
}

- (void)viewDidUnload {
 // Release any retained subviews of the main view.
 // e.g. self.myOutlet = nil;
}


- (void)dealloc {
 [sliderValue release];
    [super dealloc];
}

@end

Switch to Interface Builder to add the UI now, double click on ImageViewViewController.xib to start Interface Builder.

Add a Label and Slider (both from the Inputs & Values under Cocoa Touch of Library) on the View pane.

Now check the setting of the Slider: click on the Slider to select it, and click Tools -> Inspector from Interface Builder top menu.

Accept the default value of min = 0, max =1 and initial = 0.5...

Now double click on the Label to change the text to 0.5, to match with the initial value of the Slider.

Connect the Action Method of the Slider:

click on the Slider to select it, and click Tools -> Connections Inspector from Interface Builder top menu.

Drag the circle on the right of the event Value Changed, to over File's Owner in ImageViewViewController.xib, release and select sliderChanged.

Connect the Outlet to the Label:

Drag the File's Owner by right button on mouse in ImageViewViewController.xib to over the Label in View. Release and select sliderValue.

Save your work, and Build and Run in Xcode.

Load a Image View in iPhone

To display a Image View on iPhone screen, it involve simple using Interface Builder, without any programmatic coding.

Start Xcode, and creat a new iPhone OS Application using View-based Application template, name it ImageView.

Import image into project.

Click Project from Xcode top menu, select Add to Project.... Browser to load the image you want.

Drag it into Resources folder.
(Or save the graph above to the Resources folder. )

Double click on the file ImageViewViewController.xib under Resources to open Interface Builder. Make sure both View and Library pane are opened, open it from Tools on Interface Builder top menu if not yet.

Select Data Views under Cocoa Touch inside Library, select Image View.

Drag a Image View to over View Pane.

Because the Image View is cover the whole screen now. Sometimes, it's not easy to select object. There is another way to select object using View Mode, instead of select it from View Pane:

Select the middle button over View Mode inside ImageViewController.xib pane. The objects will be listed in hierarchical mode, expand View and select Imge View.

Open the Inspector (Tools -> Inspector).

Click on the arrow on the Image selection box, and select the image you have imported.

With the Image View is selected in the ImageViewController.xib pane, you can adjust the image size easily, and also try to change the properties in the Inspector pane.

Save your work and back to Xcode, Build and Go.

Retrieve properties of the sender

In last article, Hello iPhone, using View-Based Application, the triggered Action Method modify the text of the Label, without any knowledge of event source.

In this article, the title of the source button will be displayed on the screen, to show how to retrieve the properties of the Sender.

Modify helloiphoneViewController.xib to add one more button, rename the two buttons with the name Button 1 and Button 2. Repeat the step in the last article to Connect the Action from Botton 2 to buttonPressed.

Modify the method buttonPressed inside the file helloiphoneViewController.m

-(IBAction)buttonPressed:(id)sender{

NSString *title = [sender titleForState:UIControlStateNormal];

NSString *newText = [[NSString alloc] initWithFormat:@"Hello! %@ Pressed", title];

labelText.text = newText;

[newText release];

}

[sender titleForState:UIControlStateNormal] return the title of the sender, such that we can identify which button pressed to trigger the event buttonPressed.

Back to Xcode, Build and Run the application again.

Hello iPhone, using View-Based Application.

In this article, I implement my very first iPhone application starting from View-Based Application, which is a template for applications that uses a single view to implement its user interface.

Create a new Project in Xcode, select View-Based Application from Application under iPhone OS, choose a location and Save As helloiphone.

In the project window, expand the Classes folder under helloiphone. There are four files generated:

- helloiphoneAppDelegate.h

- helloiphoneAppDelegate.m

- helloiphoneViewController.h

- helloiphoneViewController.m

We will deal on the four files mainly.

ViewController -

There is only one view in the application. helloiphoneViewController, which is a subclass of UIViewController, is a controller class that manage the view. UIViewController is a part of UIKit.

AppDelegate -

The other two files implement the application delegate, classes response to do something at certain times on behalf of UIApplication. In certain times, UIApplication will call the implemented delegate methods, such as applicationDidFinishLaunching. In this application, we have no need to touch the AppDelegate files.

IBOutlet -

The controller class refer to a object (such as a text label) in nib using outlet, such that the code can change the property (such as the text of the label) of a object using outlet.

IBAction -

Interface object (such as a button) can generate action methods (such as touch up) in the controller class

We are going to implement a action method, named buttonPressed, which will be triggered by the interface object button. And create an outlet point to the text label. The code inside the action method change the text of the text label using the out.

Modify the file helloiphoneViewController.h

#import <UIKit/UIKit.h>

@interface helloiphoneViewController : UIViewController {

UILabel *labelText;

}

@property (nonatomic, retain) IBOutlet UILabel *labelText;

- (IBAction)buttonPressed:(id)sender;

@end

Modify the file helloiphoneViewController.m

#import "helloiphoneViewController.h"

@implementation helloiphoneViewController

@synthesize labelText;

-(IBAction)buttonPressed:(id)sender{

NSString *newText = [[NSString alloc] initWithFormat:@"Hello iPhone!"];

labelText.text = newText;

[newText release];

}

- (void)didReceiveMemoryWarning {

// Releases the view if it doesn't have a superview.

    [super didReceiveMemoryWarning];

// Release any cached data, images, etc that aren't in use.

}

- (void)viewDidUnload {

// Release any retained subviews of the main view.

// e.g. self.myOutlet = nil;

}

- (void)dealloc {

  [labelText release];

    [super dealloc];

}

@end

Create the View using Interface Builder

Expand the Resources, and double click to open helloiphoneViewController.xib in Interface Builder.

Drag a Label from Library to View, place on any where you want, double click on it to edit the starting text, eg. Hello!.

Drag a Round Rect Button from Library to View, place on any where you want, double click on it to edit the starting text, eg. Press Me.

Connect the Outlet

Hold down the Control key and drag (or drag by right button on mouse) the File's Owner in helloiphoneViewController.xib to over the Label in View. Release and select labelText.

Connect the Action

Select Tools from top menu of Interface Builder, select Connections Inspector. Click on the Button on the View. The Connections Inspector will show the available events of the Button.

 Drag the circle on the right of the event Touch Up Inside, to over File's Owner in helloiphoneViewController, release and select buttonPressed.

Save the work and go back to Xcode, click Build and Go.

The Label display Hello! in start-up, and change to Hello iPhone! once the button pressed.