Hello, iPhone

Main.cs

The Main.cs file is very simple. It contains a static Main method which creates a new MonoTouch application instance and passes the name of the class that will handle OS events, which in our case is the AppDelegateclass:

using System;
using System.Collections.Generic;
using System.Linq;
using MonoTouch.Foundation;
using MonoTouch.UIKit;

namespace HelloWorld_iPhone
{
       public class Application
       {
              static void Main (string[] args)
              {
                     UIApplication.Main (args, null, "AppDelegate");
              }
       }
}

AppDelegate.cs

The AppDelegate.cs file contains our AppDelegate class, which is responsible for creating our window and listening to OS events:

using System;
using System.Collections.Generic;
using System.Linq;
using MonoTouch.Foundation;
using MonoTouch.UIKit;
namespace HelloWorld_iPhone
{
       [Register ("AppDelegate")]
       public partial class AppDelegate : UIApplicationDelegate
       {
              UIWindow window;
              HelloWorld_iPhoneViewController viewController;             
              // This method is invoked when the application has loaded
              // its UI and is ready to run
              public override bool FinishedLaunching (UIApplication app, NSDictionary options)
              {
                      window = new UIWindow (UIScreen.MainScreen.Bounds);                     
                      viewController = new HelloWorld_iPhoneViewController
                             ("HelloWorld_iPhoneViewController", null);
                      window.RootViewController = viewController;
                      window.MakeKeyAndVisible ();                     
                      return true;
              }
       }
}

This code is probably unfamiliar unless you’ve built an iOS application before, but it’s fairly simple. Let’s examine the important lines.

First, let’s take a look at the two class-level variable declarations:

UIWindow window;

HelloWorld_iPhoneViewController viewController;

The UIWindow declaration represents the actual application window. The second declaration is of type HelloWorld_iPhoneViewController, which is responsible for displaying a view in our window. In iOS applications, you only ever have one window, but you can have many screens. Each screen is actually a view, and it has a view controller that is responsible for the view’s life cycle, such as showing the view.

This pattern is known as the Model View Controller (MVC) pattern. We’ll examine this in more depth in the next tutorial, when we create an application with multiple screens.

Next, we have the FinishedLaunching method. This method runs after the application has been instantiated, and it’s responsible for actually creating the application window and beginning the process of displaying the view in it. It’s important to note that this method has 10 seconds to return; otherwise iOS will terminate the application. Therefore, you should keep this method as simple and spare as possible.

The first line of this method actually creates the window at the exact size of the screen:

window = new UIWindow (UIScreen.MainScreen.Bounds);

Next, the code creates a new view controller, and tells the window that it’s the top most (root) view controller (and it is therefore the main screen):

viewController = new HelloWorld_iPhoneViewController("HelloWorld_iPhoneViewController", null);
window.RootViewController = viewController;

Finally, we tell the iOS that this window should be visible and then return out of the method:

window.MakeKeyAndVisible ();
return true;

The MakeKey portion of this method is inherited from the OS X programming model in which you need to tell the OS which window should have focus in a multiple window environment.

HelloWorld_iPhoneViewController.cs

As we’ve already seen, the HelloWorld_iPhoneViewController class is our main view controller. That means it’s responsible for the life cycle of the main view (screen). We’re going to examine this in detail later, so we can skip any more detail about it for now, other than to point out that it has several view life cycle events that are important, including ViewDidLoad, ViewDidUnload, and others:

using MonoTouch.UIKit;
using System.Drawing;
using System;
using MonoTouch.Foundation;

namespace HelloWorld_iPhone
{
       public partial class HelloWorld_iPhoneViewController : UIViewController
       {
              public HelloWorld_iPhoneViewController (string nibName, NSBundle bundle) 
                   : base (nibName, bundle)
              {
              }             
              public override void DidReceiveMemoryWarning ()
              {
                      // Releases the view if it doesn't have a superview.
                      base.DidReceiveMemoryWarning ();                     
                      // Release any cached data, images, etc that aren't
                      // in use.
              }             
              public override void ViewDidLoad ()
              {
                      base.ViewDidLoad ();                     
                      //any additional setup after loading the view,
                      //typically from a nib.
              }             
              public override void ViewDidUnload ()
              {
                      base.ViewDidUnload ();                     
                      // Release any retained subviews of the main view.
                      // e.g. this.myOutlet = null;
              }             
              public override bool ShouldAutorotateToInterfaceOrientation
                      (UIInterfaceOrientation toInterfaceOrientation)
              {
                      // Return true for supported orientations
                      return (toInterfaceOrientation != UIInterfaceOrientation.PortraitUpsideDown);
              }
       }
}

HelloWorld_iPhoneViewController.Designer.cs

The designer file for our HelloWorld_iPhoneViewController class is empty right now, but it will be automatically populated by MonoDevelop as we create our UI:

// This file has been generated automatically by MonoDevelop to store outlets and
// actions made in the Xcode designer. If it is removed, they will be lost.
// Manual changes to this file may not be handled correctly.
using MonoTouch.Foundation;

namespace HelloWorld_iPhone
{
       [Register ("HelloWorld_iPhoneViewController")]
       partial class HelloWorld_iPhoneViewController
       {
       }
}

Now that we have created our MonoTouch application and we have a basic understanding of its components, let’s jump over to Xcode and create our UI.

Outlets + Actions Defined

So what are Outlets and Actions? In traditional .NET UI programming, a control in the UI is automatically exposed as a property when it’s added. Things work differently in iOS (and in OS X programming, for that matter). Simply adding a control to a view doesn’t make it accessible to code. In order to access our controls from code, Apple gives us two options:

• Outlets – Outlets are analogous to properties. If you wire up a control to an Outlet, it’s exposed to your code via a property, so you can do things like attach event handlers, call methods on it, etc.
• Actions – Actions are analogous to the command pattern in WPF. For example, when an Action is performed on a control, say a button click, the control will automatically call a method in your code. Actions are powerful and convenient because you can wire up many controls to the same Action.

In Xcode 4, Apple has added a new way to create Outlets and Actions directly in code via Control-dragging. More specifically, this means that in order to create an Outlet or Action, you choose which control element you’d like to add an Outlet or Action, hold down the Control button on the keyboard, and drag that control directly into your code.

For MonoTouch developers, this means that you drag into the Objective-C stub files that correspond to the C# file where you want to create the Outlet or Action.

In order to facilitate this, Xcode 4 introduced a split-view in the Editor Area called the Assistant Editor that allows two files to be visible at once (the .xib file in the Interface Builder designer, and the code file in the code editor).
In order to view the Assistant Editor split screen, click the middle button of the Editor choice buttons in the toolbar:

Xcode will then show two documents at once:

Now we’re going to do a couple things to make this two-up view useful for wiring up Outlets and Actions.

First, show the Utility Area by clicking on the right button in the View buttons in the toolbar:

Next, click on the .xib file from the Project Navigator. We should now have a two-up view of the code, the designer, and the Utility Area:

Now we can start wiring up our Outlets and Actions.

Adding an Outlet

In order to create the Outlet, use the following procedure:

1. Determine for which control you want an Outlet.
2. Hold down the Control key on the keyboard, and then drag from the control to an empty space in your code file after the @interface definition.

You can drag from the Document Inspector as well, which can be helpful if you have a complicated UI with nested controls.

A popover will then show, giving you the option to choose either Outlet or Action. Choose Outlet and name it btnClickMe:

Click Connect after you’ve filled out the form, and Xcode will insert the appropriate code in the .h file:

Save the file, and then go back to MonoDevelop. If you open the .designer.cs file that corresponds to the .h file that was just modified in Xcode, you’ll see your new Outlet exposed as a property:

As you can see, MonoDevelop listens for changes to the .h file, and then automatically synchronizes those changes in the respective Designer.cs file to expose them to your application.

We need to create one more Outlet for our label, so switch back over to Xcode. Create the label’s Outlet the same way you did the button’s Outlet and name it lblOutput. The .h file should have the following Outlets now defined:

@property (nonatomic, retain) IBOutlet UIButton *btnClickMe;
@property (nonatomic, retain) IBOutlet UILabel *lblOutput;

We’re going to use these in our MonoTouch application in just a bit, but while we’re in Xcode, let’s wire up the two Action buttons to an Action.

Adding an Action

Creating an Action is done the same way as creating an Outlet. Control-drag from the control into the code, as you did before:

This time, though, choose Action as the Connection type in the popover menu:

Name the Action and select on which event you’d like the Action to be called. In this case, we’re going to use Touch Up Inside.

We use the TouchUpInside event because it doesn’t get fired until the user releases the button with their finger. This allows the user to cancel an accidental touch by sliding their finger off the button before releasing it. At first it may seem more logical to use TouchDownInside; however, this will raise the event as soon as a button is touched, and doesn’t allow for cancellation.

You can also strongly-type the type controls that can call this Action by changing the Type from id to a particular control type. If you don’t strongly type it, you’ll have to cast the sender object to its appropriate type when you want to use it, as we’ll see in a moment. If you do strongly type this control, then only that one type of control can call this Action.

You may want to wire up multiple items to the same action (which is the entire point of using an Action, as opposed to an Outlet). In our UI, we have two Action buttons so that we can illustrate this at work.

To wire up a control to an existing Action, instead of Control-dragging to a blank space in the code, you Control-drag to an existing Action declaration in code:

In this case, we Control-Dragged from the Connections Inspector, which allowed us to select the event on which we wanted to call the Action, but we could have just as easily Control-dragged from the control in the designer or in the Document Inspector.

Once your Actions and Outlets are wired up, the final declarations in the .h file should be:

@property (nonatomic, retain) IBOutlet UIButton *btnClickMe;
@property (nonatomic, retain) IBOutlet UILabel *lblOutput;
- (IBAction)actnButtonClick:(id)sender;

Now that we have them wired up, let’s save the files and switch back to MonoDevelop to actually do something interesting with them.

Note: It probably took a long time to create the UI, Outlets, and Actions for our first application, and it may seem like a lot of work, but we’ve introduced a lot of new concepts and we’ve spent a lot of time covering new ground. Once you’ve practiced awhile working with IB, this interface and all its Outlets and Actions can be created in just a couple of minutes.

Choosing Which Device to Simulate

By default, the Device Simulator will simulate the standard resolution iPhone (iPhone 3GS and older). However, you can also simulate an iPhone with the Retina Display (iPhone 4+), as well as the iPad.

To change your simulator target, choose one of the following from the Project : iPhone Simulator Target menu:

• Default – Default launches the iPhone simulator with the regular resolution (320x480) display. This resolution matches the iPhone 3GS and older phones.
• iPhone Simulator 4.3 – Use this setting if you want to run the application using the iPhone simulator with the Retina Display resolution (640x960). Note: if you want to use the Retina Display iPhone Simulator, in addition to setting this target, you must first launch the simulator and then change it to the Retina Display by selecting Hardware > Device > iPhone (Retina) in the menu. This is, unfortunately, the way Apple designed it, and this same behavior exists even if you’re using Xcode and writing in Objective-C.
• iPad Simulator 4.3 – This setting will launch the iPhone simulator at the iPad resolution (1024x768).