iPhone SDK Hello World Tutorial

[Frenchb0ygenius]

Read This First! :

Spoiler for READ THIS FIRST!!!:

If you didn't already know:
Programming for a Mac is (mostly) done using the Cocoa frameworks, for the iPhone it's done using Cocoa Touch (just a modified version of Cocoa). The native language for Cocoa or Cocoa Touch is Objective-C. Objective-C is just a small superset of C, and is obviously meant to give object oriented functionality. This means that not only are you able to use new features of the language, but also regular C stuff as well. I highly recommend learning C before getting into any of this stuff. Learning Objective-C is not difficult at all, If you have some general knowledge in C or any other object oriented programming language, you can probably learn it in a day or two. The hard part about iPhone and Mac programming is learning to use the Cocoa/Cocoa Touch frameworks, but once you get the hang of it, you'll like it.

Some basic terminology:

Method: Basically just the equivalent of a function in any other programming language...you can give it some input, and you can have it return something.

Instance: Think of it as an object. If you see me say "instance of a class", then it means an object of that class.

.m/.h files: Well, you need to have somewhere to put your stuff...in C you have .c and .h files, well in Objective-C you have .m and .h files that do the same...here's some more on that:

Spoiler for 3 Portions:

In the Objective-C language, you have basically 3 major parts to your code. They are: @interface, @implementation, and the program section.

-The @interface section is where you declare instance variables, methods, properties, all that...it's just like the .h section of a C program. If you look at any of the .h files in an Objective-C program you will see that this is the @interface section.

-The @implementation section is where you define all of the variables and methods you made in the @interface section. You will find this section in your .m files.

-The program section is basically where your main is. It won't be denoted anywhere like the @interface or @implementation sections are, but again, it is basically where your main is. In most Cocoa or Cocoa Touch applications you will almost never modify your main function.

So what is Interface Builder anyways?
Interface Builder is a GUI builder basically. You build your interface the way you want, connect everything to your code, and then write your code out. I highly recommend using Interface Builder whenever making any kind of iPhone or Mac application...it's easy to get the hang of it, and eliminates a lot of unnecessary code.

Lets Start:

In this tutorial, I will show you how to create an application that has a text field (the thing that you tap and a keyboard pops up), a button, and a label. The user will enter something in the text field, and when they are done they press the button and the same text they typed in the text field will appear in the label.

(I'm using Beta 8 of the iPhone SDK, I haven't gotten around to downloading the final release yet.)

First open Xcode. Go to File < New Project:



In this tutorial, choose a "View Based Application" under iPhone OS. Under the name it tells you what's included in it.



After that, just rename it to whatever you wan and save it wherever you want.



Here's what the project window will look like:



As you can see it includes some files for you already, like the AppDelegate, and a View Controller. If you look under the "Resources" folder, you will see two files with a .xib exension. These are the interface files that store your interface. We need to delete the View Controller .xib file, since we are not going to be using a view controller in our app. So delete the "your project name"ViewController.xib. Now double click on the "Main Window.xib". You should see Interface Builder open.

By default you should have 4 windows open. Your main window in which you create your interface, the inspector, the library, and another window that has instances of different things. We won't be using that one in this, so just make sure you have the Inspector and the Library, and of course your main window. If you don't, you can find them in the Tools menu.

Edit the Attributes tab of the window to look like this:



Since we aren't using the view controller, we don't want the view to be loaded from that. So we have to add in our own view. In the Library, look for the UIView and drag that into your window.



Once you have your view on your window, click on it and in the Inspector, go to the "View Identity" tab (far right). Change the class to whatever you want your class name to be named...I will name mine "MyView".



Now we can add our controls to our window...so in the Library find a UITextField, a UIButton, and a UILabel and just drag those into your window (remember they should all be on top of your view).



Here's what my window looks like now:



Now we will be setting some attributes of each of our controls. We'll start with the text field. So click on the text field, and in the Inspector go to the Attributes tab (far left one). You can change anything you want, such as the text size, color, or allignment, but the only thing I want to change is here:



What I did here is make it so that when the keyboard pops up, the "Return" button will say "Done".

Now onto the button's attributes. You can change the text of the button by double clicking the button, and typing whatever you want. I chose to have mine say "Press Me!":



And now the label attributes. We just want the text to be centered and for it to say nothing at the launch of our application:



All I did was change the text to nothing, and choosing the centered allignment button.

That's it for laying out our interface, now we need to make outlets and actions, and connect everything...What are these things?
1. Outlets are a way for both Interface Builder and Xcode to recognize your variables. We need to create an outlet for the text field, and the label. Not the button though, that will have an action.
2. Actions are just methods, that will be triggered by a certain control. In this case, our button. So whenever we press our button, a certain action method will be called.
3. Connections are a way of linking our outlets and actions to the controls. Without them, our controls would still be in our window, but they would serve no purpose.

So here we go. Click on the background (the view) of your window, and go to the View Identity tab. Make sure that you are in the view you created by checking that the name in "Class" is the one you created. On this tab you should see two little sections. One for outlets, and one for actions:



Lets start with the outlets. Press on the "+" button, and name it "label" (lowercase) and press enter. Now in the "Type", type in UILabel. Now do this for the text field. Call it textField and make it of type UITextField.

And now the action. Press the "+" button in the actions section, and just name this one "press Button". leave the type to "id".

Here is what it should look like:



Now that we are done making these outlets and actions, we need to connect them to our actual controls. In the Inspector go to the "Connections" tab (to the right of the attributes). You should see all your outlets and the action. This might get confusing, but here's what you do: Literally drag from the little circle of one outlet, and drag that to the corresponding control on the window.

From the textField outlet to the text field:



From the label outlet to our label:



Connecting actions is a little different. At first it's the same, but then you have to choose the event. So drag from the pressButton action to the button, and then in the list that comes up you can either choose "Touch up inside" or "Touch down". They both represent the event of being pressed down:





We have one more connection to make. Click on your text field and make sure you are still in the connections tab. Connect the "delegate" outlet to the view (so anywhere on the background) like so:



What is a delegate?

First lets talk about helper objects. Helper objects are pretty self explanatory, they "help" the object they are assigned to. For example, table views have a helper object called datasource, which includes methods that return the number of columns, the object to be displayed at a certain column or row, etc...

A delegate is a helper objects, many classes that in the Cocoa and Cocoa Touch frameworks have delegates. The only delegate method we will be using is one that will make sure that when the user presses "Done" in the keyboard, it goes away. If you don't understand this, it's ok...just make sure the text field's delegate is connected to our view.

And now we are done with Interface Builder. Click on your view (the background) and go to File < Write Class Files. This will actually write out the file for the view.



After clicking on that make sure that the files are going to your project's folder, and that it looks like this:



Just make sure the name is the one you specified earlier. After clicking save, you will see this, make sure the little box is checked:



Now we are really done with Interface Builder. Go back to Xcode, and you should see the files you created:



You can either leave them there, or put them under the "Classes" folder, I'll do that, I just like it more organized.

Let's write out the code for the application. Lets start in the .h file for the view file that was just created. First we have to specify a superclass for this class we are creating, so where you see this:

@interface "your class' name" : blah blah...

Add UIView after the colon.

You also need to add a string, we'll use Apple's NSString instead of a C string. This string will contain the text of the text field, so that we can set the label's text to that string. So under the other variables (the IBOutlets) type this:

NSString *textFieldString

Here's what it should look like:


Now move on to the .m file. We will fill in the pressButton action method we created earlier. Here's what we will add (explanation in comments):

//Remember, this code is only called if the button is pressed, since 
//they are connected

textFieldString = textField.text;
// ^^ Takes the text from our text field, and puts it in our textFieldString

label.text = textFieldString;
//^^Sets the label's text to the textFieldString's value, which is the text
//from the text field.

Now we need to add that delegate method I said we were going to use. Where will we find this method? The documentation of course... Open the documentation like here:



Make sure you are in the iPhone OS Library (find it in the tab on the left) and in the search bar type in "UITextFieldDelegate" . The document we want should have that name...Look through the document until you find something like this:



That's the method we need (the one that returns a BOOL). Copy and paste that into your .m file and add some curly brackets. Here's what you need to add to that method:

[theTextField resignFirstResponder];
//^^ Kinda gives control back to everything else, instead of only being able //to use the keypad.

Return YES;
//^^Since this method expects a boolean return type, it's either YES or NO.
//We are saying YES for it to return once the "Done" button is pressed.

^^Without that method, the keypad would not leave, even if you pressed the done button. Here's what the end product should look like(make sure yours looks the same):



And you're done, so build and go, and I hope you learned something.

Spoiler for Hello World (No Interface Builder, just Xcode):

Title says it all, this will be a beginner tutorial on how to create a Hello World app for the iPhone using the iPhone SDK. Why did I make this? Mainly because it's fairly easy to learn a programming language and program for a pc, but as I found out, programming for the iPhone is a little different and would have been a lot easier for me if I had read a comprehensive guide.

There are a few things to take into consideration on the iPhone:

1. The resources that are available to you (CPU power, RAM, etc...) are very limited on the iPhone compared to a modern pc (thankfully the hello world example will not need to take these things into consideration).

2. Writing a simple hello world app will take a lot more code than you think. But the good thing is all of this code is not really "logical programming". Most of it is code that is there because you need it for the stuff you want to display to acutally display on the screen. But here is an explanation for this:If you didn't already know, the iPhone has a certain way of displaying things (in our case, the "Hello World" text) to the screen. First you must initialize the window, in which the everything will be placed. Since you can't place things directly onto the window, you must create a view to put things on. After that, you need to create a frame (most of the time this will be in the form of a rectangle). Inside of the frame you will put a label that contains all of the text you will be outputting, along with all of the properties the text will contain (ex: font/size, text color, background color, etc...). This process may seem long and boring, but you get really used to it after a while...and it is really easy to memorize.

So, lets get started:

1. Open Xcode and go to File --> New Project. A window like this will pop up:



There is only one choice under "iPhone OS", so that's taken care for you. Then you need to choose "Cocoa Touch Application". Click the "Choose" button and then you will be asked to name the project and choose a folder to put it in...

When done with that you will see the Xcode project window:


I guess I should explain what these files do:

-CoreGraphics.framework, Foundation.framework, and UIKit.framework: These are all frameworks that Apple has provided. CoreGraphics and UIKit are both visual things, they are what you see on you iPhone. Foundation is what you don't see, all of the stuff that goes on behind the scenes.

-Your_project.App (in my case Hello World.App): Think of it as the .exe on Windows.

-Your_project_nameAppDeleg ate.m/.h(in my case HelloWorldAppDelegate): Again, remember what I said about .m/.h files. The AppDelegate.m file is somewhat considered as your main (even though there already is a main). It is where your window and your main view are set up. The .h file simply has all of the instances you will use, and properties for those instances.

-Main.m: In reality this is actually your main, but in most cases it is good not to mess around with this file, as Apple has already written it for you.

-MainWindow.xib: If you open this up, you will see that Interface Builder will open up. MainWindow.xib is the user interface for your application.



2. Now, in previous versions of the beta sdk (like beta 1 and 2 i think), a source file called MyView.m (accompanied by MyView.h) was automatically added to the project. MyView is basically where you code for the frame, and the label, as I mentioned earlier. Here's why: Again, in previous versions of the beta, Interface Builder (another tool provided with the sdk), was not available. Interface Builder is where you create your iPhone app's GUI. In Interface Builder creating a label is a lot easier than doing it by code, so that's why MyView.m & .h were removed in later versions of the beta. However, I think it's more beneficial to learn how to create the frame and label by code, so that's why I do it that way in this tutorial.

So, you guessed it, we need to create MyView.m & MyView.h. Here's how:[/B] [B]On the left side in the Xcode project window you will see a bunch of folders, one of them being "Classes". Right click on the "Classes" folder, and then click "Add", "New file". Here is how it should look:



Then this window should pop up:



(If you haven't guessed already, MyView will be a subclass of UIView)

Under where it says iPhone OS, choose "Cocoa Touch Classes", and choose "UIView subclass. Another window should pop up, just leave the settings to default, but make sure that "Add MyView.h" is added. You should now see MyView.m and MyView.h added as part of the classes folder.

3. Now we can start writing some code. The first file we will work in is MyView.h, so open that up. MyView.h is where we will be creating instances of the class CGRect (a rectangle for our frame) and UILabel (our label). So inside of the "@interface MyView : UIView" part, add in the following:

CGRect rect; //ALWAYS REMEMBER THE SEMICOLON!!!
UILabel *label; //ALWAYS REMEMBER THE SEMICOLON!!!

As you can see, we have created an instance (or basically created an object) of the CGRect class named frame, and an instance (again, an object of) the UILabel class named label. And that is it for the MyView.h file, save it (File > Save) and now we are ready to move on to MyView.m. Btw, here is what MyView.h should look like (i cropped it or else it would have been really big):



4. Now let's move on to making use of the frame (rect) and the label (label). Open the MyView.m file. We will first be working in the "initWithFrame" method (the one with this name: -(id)initWithFrame: (CGRect)frame).

So, now that we have our frame (rect) created, we need to actually put it somewhere. But to do that, we need to give it coordinates to place itself on the screen. So first we declare four int (integer) variables. They are x(the x coordinate), y(the y coordinate), w(the width), and h(the height). Since I want the "Hello World" text to not come off of the x axis, I will set the x variable to 0. I will set the y variable to 240...Why? Because I want our text to display in the middle of the iPhone screen, and since the iPhone screen's length is 480...well you get the point... The w and h variables are pretty self explanatory. So, this is what should be added to the initWithFrame method:

int x = 00;
int y = 240;
int w = 320;
int h = 50;

Now we need to initialize the rect frame with the constructers we just initialized, the x, y, w, and h variables. So here's how you do this:

rect = CGRectMake(x, y, w, h);

Ok, so our frame is set, now we need to put our label onto to frame. Here is how it's done:

label = [[UILabel alloc] initWithFrame: rect]; //Allocate the label within memory, then initialize it inside of the frame we created earlier (rect)

The comment pretty much says it all, the [UILabel alloc] allocates the label into ram, and the rest puts it into the frame we created earlier (rect).

Now comes the actual "Hello World" part. We will now assign some properties to this label, one of them being the text. The properties we will add are the text alignment, the actual text, the font of the text, the text color, and the background color. Here is the code to do this:

label.textAlignment = UITextAlignmentCenter //Center the text.
label.text = @"Hello World!" //Set the text to "Hello World!"
label.font = [UIFont systemFontOfSize: 60.00 //Set font size to 60
label.textColor = [UIColor redColor] // Sets the text color to red
label.backgroundColor = [UIColor clearColor] //Sets the background to a clear color

Now that the label has been created and given some properties, we need to add it as a subview to our frame. Add this code:

[self addSubview: label];

Sorry if this view stuff is getting confusing, I was totally confused at the beginning but I started to understand it after a few days.

And that is it for the initWithFrame method, now we just need to add one small thing to the "dealloc" (deallocate) method (it should be the last method inside of the MyView.m file):

[label release];

If you don't add that to the dealloc method, you won't get an error or a warning while compiling but at runtime the program will not function properly. And there! Most of the program is done, and now all we have to do is create the window and an instance of MyView to display everything. Here is what the MyView.m file should look like:



5. So now we move on to the AppDelegate files. Yours should be named like this: name_of_projAppDelegate.m (and there will also be a .h file).

So open up the AppDelegate.h file first. First put this in right after the "#import (etc...)" stuff:

@class MyView;

This will tell the compiler that in the rest of this file we are referring to the MyView files.

Next we will create an instance of the UIWindow class named window...you guessed it, this is what our window will be. We also create an instance of the MyView class named contentView. contentView will be placed onto the window, and then the magical hello world text will be displayed.

Inside of the "@interface name_of_projAppDelegate NSObject: (etc...) part, you can see that an instance of UIWindow has already been created. Go ahead and delete the "IBOutlet" part before UIWindow, this is because we are not using Interface Builder. After that create an instance of MyView, I called it contentView. Here is what it should look like inside of the @interface name_of_projAppDelegate NSObject: (etc...) part:

UIWindow *window;
MyView *contentView;

Now outside of the "@interface name_of_projAppDelegate NSObject: (etc...) part (but before the @end) you should see a line like this:

@property (nonatomic, retain) UIWindow *window;

I won't go into detail about what this is, but all you need to do is copy & paste this line, and put it right below. Now replace "UIWindow *window" with "MyView *contentView". And that is all for the AppDelegate.h file. Here is how it should look:






6. Now open the AppDelegate.m file. This is our last file to edit. Under where it says @synthesize window type @synthesize contentView (or whatever you named your instance of MyView).

Now inside of the applicationDidFinishLaunc hing method, we need to allocate contentView and window into memory, and give them frames. Add this code to your file:

window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];

//NOTE: If you are using earlier versions of the beta SDK, go ahead and put in the above code, however if you are using beta 5 and above, you don't need it and it can cause some problems such as the screen turning white while running your app.

contentView = [[MyView alloc] initWithFrame:[window bounds]];

This stuff should look familiar, if not, revisit step 4. Now, since we aren't using Interface Builder, we need to make the window visible by adding this:

[window makeKeyAndVisible];

We also need to make contentView a subview of our window:

[window addSubview: contentView];

We are done with this method, now let's move on to the dealloc method down at the bottom. Add the following:

[contentView release];

And now you are done with the AppDelegate files, here is what the .m should look like:



Congratulations, you have written your first iPhone app! Before you compile I recommend that you check over all of the files that you worked in and check for silly mistakes, like capital letters, forgotten semicolons, etc...When done with that, click the "Build and Go" button to compile and run your app on the iPhone Simulator:



The iPhone Simulator should look like this:



That's pretty much it...The great thing about the iPhone SDK is that Apple has included an enormous collection of classes and methods to work with. Creating apps that actually do things becomes very easy once you know the basics.

If anyone finds an error in what I posted please let me know and I will fix it, I'm not here to mislead anyone.

[voyager163]

hi..I have problem displaying the Hello World. Sometime it appear but sometime it do not. Sometime it just shows a white screen..Can you help me?anyway thanks for tutorial...It is the best one out there.=)

My msn is voyager163@hotmail.com

i am a student C# developer who is turning to Mac developer.

[leejames04]

hi..I have problem displaying the Hello World. Sometime it appear but sometime it do not. Sometime it just shows a white screen..Can you help me?anyway thanks for tutorial...It is the best one out there.=)

My msn is voyager163@hotmail.com

i am a student C# developer who is turning to Mac developer.

When you try this application, are you trying it on the iPhone emulator or the iPhone/iPod itself? If you are running the application on the iPhone/iPod are you running 2.0 in any form?

Anyway great tutorial Frenchb0y. I am trying to get my head around C++ and have made a few applications with it (I could show you but you'd need to PM) but I plan to learn objective-C next for Mac/iPhone development.

[Frenchb0ygenius]

Thanks guys.

hi..I have problem displaying the Hello World. Sometime it appear but sometime it do not. Sometime it just shows a white screen..Can you help me?anyway thanks for tutorial...It is the best one out there.=)

My msn is voyager163@hotmail.com

i am a student C# developer who is turning to Mac developer.

Make sure that all of the dealloc methods look like the ones I posted screenshots of. If they aren't it would cause a lot of memory issues and what not.

[Vee]

Bravo frenchboy. One of the best posts on this forum.

A shame its only available to Leopard users.

[Vanden]

Very nice... How long did it take for you to write all this...

[RoBz]

Nice guide dude.

So there's no way to use the SDK on Windows?

[Frenchb0ygenius]

Bravo frenchboy. One of the best posts on this forum.

A shame its only available to Leopard users.

Thanks! Ya it sucks, but you can always try cygwin and the toolchain: http://www.ipodtouchfans.com/forums/...ad.php?t=61883

Very nice... How long did it take for you to write all this...

Ehh, a few hours.

Nice guide dude.

So there's no way to use the SDK on Windows?

Thank you! You can use cygwin and the toolchain: http://www.ipodtouchfans.com/forums/...ad.php?t=61883

[leejames04]

I've hit a problem.

I have used the interface builder to create my app so I know what it look like.

What I plan to do is have the iPhone create a random number, then get the user to guess this number.

I have a view set up to show the text and receive the guesses. But i don't know how to get xCode to recognize this and thus be able to add text that will change.

Please help.

[Frenchb0ygenius]

I'll try and make a tutorial using Interface Builder...

[Frenchb0ygenius]

Interface Builder tut is up.

[Deturbanator]

cool, im requesting a vista emulator with coolz graphics and i wants it to be fast so i can plays crysis on very high... tutorial would be nice
lol good job on the tut, didnt do it but i could follow easily :]

[Frenchb0ygenius]

cool, im requesting a vista emulator with coolz graphics and i wants it to be fast so i can plays crysis on very high... tutorial would be nice
lol good job on the tut, didnt do it but i could follow easily :]

Would you like the Ultra High mod on that emu? lol thanks.

[leejames04]

Thanks so much, I finally followed your tutorial and it worked perfectly, however I am having a problem with my new app, how would I be able to make a random number that will not change. At the moment I have srand(time(0)) and random() in the MyView.m in the IBAction {} as that's the only place that it lets me put it, however because of this whenever you press the button the random number will change which I don't want the app to do.

I am also having a problem with loops and if statements, when I do them the app will crash and I am getting warnings about comparing text (a number) to an integer.

Please help

[Frenchb0ygenius]

pm'd you.

[MCMOS]

Hi,
When I work through this code, I get the following errors in the MyView.m file:

" 'textFieldString' undeclared (first use in this function) "
**This error note is after the "textFieldString = textField.text; line

" 'theTextField' undeclared (first use in this function) "
**this error note is after the [theTextField resignFirstResponder]; line

I thought I recreated your sample code exactly, but apparently not...any suggestions?
-=Double Post Merge =-
My bad. I had the following problems with my code:

my MyView.h file had incorrect syntax for the string. I used "nsstring" rather than "NSString" (note capital "NSS")

my MyView.m file had a typo in the "(Bool)textFieldShoulRetu rn:"...etc. line

Thanks for the post! This is the best simple tutorial I've found.

[Frenchb0ygenius]

This tutorial is hella old btw, it uses the beta sdk...