MacResearch

After months of preparation, we are finally ready to take advantage of Apple’s developer tools, and create a graphical Cocoa application. In this lesson, you will get acquainted with Xcode, Apple’s Integrated Development Environment (IDE), and in the next tutorial we will take a look at Interface Builder, for laying out the User Interface (UI).

The example I will use for the first lessons is wholly unimaginative, but can at least start out simple and grow in complexity: a unit conversion app. Although hardly original, we will push this idea a little further than most, and actually try to make it a useful product. In my particular field of science, and I think this is true of many, there are some strange units, and very few standard conversion tools include them. To make our utility useful, we are going to make it programmable. That is, when it is all finished, you will be able to program your own unit conversions into it. And we may add some nice touches, like conversion charts. But that is in the future…

Configuring Xcode

Xcode is a reasonably complex piece of software, and can be configured in a number of different ways. One thing you typically need to decide before even starting a project is how you want the interface to be laid out. There are three different modes to choose from, and which you use will depend on how you like to work. I prefer the All-In-One option, which puts everything, from editing source code to building and debugging, in a single window. With this layout, you move between the various activities by clicking a button in the toolbar. Other options split different activities off into different windows, but I find this leads to a lot of clutter. That’s just my preference.

For the purpose of these tutorials, or at least the first few, I suggest you stick with my All-In-One layout, because that will allow you to more easily compare your screen with my screen shots. Later, when you can easily find your way around Xcode, you can change to another layout.

To choose the All-In-One layout, first open Xcode, which can be found in /Developer/Applications. Open the Xcode preferences by choosing the Xcode > Preferences… menu, and click on the ‘General’ tab. Make sure ‘All-In-One’ is selected from the ‘Layout’ popup button, and click the ‘OK’ button.

Creating a Project

You are now ready to create your first Xcode project. This will contain all the source code and other files needed to build the application. To create a project for the unit conversion application, follow this procedure:

1. Choose the File > New Project… menu item
2. Select ‘Cocoa Application’ in the ‘Application’ group of the New Project panel
3. Enter ‘Unitary’ as project name, and choose where you want to put the project on your hard disk
4. Click the ‘Finish’ button to create the project

You should end up with an Xcode project window not dissimilar to the one below.

Adding a Source File

With a project in place, you are now ready to add some source files. When you use the All-In-One layout, there is a file browser on the left of the window. Files are gathered into Groups which are like folders in Finder.

To add a new Cocoa source file, follow this procedure:

1. Open the ‘Unitary’ project group in the ‘Groups & Files’ pane on the left, and select the ‘Classes’ group
2. Choose the File > New File… menu item
3. Select ‘Objective-C class’ from the Cocoa group in the New File panel
4. Click the ‘Next’ button
5. Fill in Name ‘UnitaryController.m’
6. Make sure ‘Also create UnitaryController.h’ is checked
7. Click the ‘Finish’ button

You should see two new files appear in the ‘Classes’ group of the ‘Groups & Files’ pane.

Editing UnitaryController.h

Now we need to add some source code for the unit converter. We’ll begin in the header file UnitaryController.h:
First, click on the UnitaryController.h file in ‘Groups & Files’. The file contents should appear in the editor at the bottom of the right pane. You may need to grab the split view handle from the bottom of the window and drag it up to see the editor.

Enter the following code in the editor:

#import <Cocoa/Cocoa.h>


@interface UnitaryController : NSObject {
    IBOutlet NSTextField    *celsiusTextField;
    IBOutlet NSTextField    *fahrenheitTextFied;
}

-(IBAction)convert:(id)sender;

@end

At this point, you are probably wondering what the IBOutlet and IBAction are. In fact, they are just preprocessor macros. IBOutlet will be completely removed by the preprocessor, and IBAction will be converted to void. These macros are not for use by the Objective-C compiler, but for Interface Builder, which we will meet next time. Interface Builder parses these directives, and uses them to determine how a particular class can be ‘connected-up’ in the interface. We’ll learn more about all that next time.

Adding Implementation in UnitaryController.m

Repeat the same procedure for the implementation file UnitaryController.m. Open it in the editor, and insert this code:

#import "UnitaryController.h"


@implementation UnitaryController

-(void)awakeFromNib {
    [fahrenheitTextField setFloatValue:32.0];
    [celsiusTextField setFloatValue:0.0];
}

-(IBAction)convert:(id)sender {
    if ( sender == celsiusTextField ) {
        float celsiusTemperature = [celsiusTextField floatValue];
        [fahrenheitTextField setFloatValue:(1.8 * celsiusTemperature + 32.0)];
    }
    else if ( sender == fahrenheitTextField ) {
        float fahrenheitTemperature = [fahrenheitTextField floatValue];
        [celsiusTextField setFloatValue:((fahrenheitTemperature - 32.0) / 1.8)];
    }
}

@end

The awakeFromNib method is from NSObject, and is basically called whenever the interface is loaded and ready for initialization. ‘Nib’ refers to a nib file, which stands for ‘NeXT Interface Builder’; in other words, it’s called a nib for historical reasons, and is the file format of the Interface Builder application. awakeFromNib will begin to make more sense when we start adding interface elements next time.

The other method supplied was declared in the header file: convert:. This method does a conversion between Fahrenheit and Celsius, or vice versa. To determine which conversion it will carry out, it looks at the object that is sending the message, which is stored in the variable sender. If the sender is the celsius text field, it converts to fahrenheit, and vice versa. A text field is just an interface element that you enter text into. The idea is that when the user of the application enters a number in the Celsius text field, and presses return, the convert: method will be called with the text field as sender. The method will test the sender, realize that it is the celsius text field, and convert the value in the field to fahrenheit. Finally, it will set the value of the fahrenheit field with the setFloatValue: method.

Building the Project

With some source files in place, you are now ready to try to build the application.
Click the ‘Build’ button (hammer icon) in toolbar. If you get asked to save, just choose to save all files.

You can see if everything went well in the bottom strip of window on the right hand side. It should say ‘Succeeded’; if it says ‘Failed’, you have a bug. Actually, I planted a juicy bug in the source code just for this purpose, so if you followed the instructions to a T, you should get a failure message.

To view the error message, click on the central workspace button on the left of the toolbar, the one which has a hammer icon. Then make sure the ‘Build’ tab is selected in the pane on the right.

You should see two identical error messages in red. They indicate that the fahrenheitTextField variable has not been declared. If you click on the error line, you should see the relevant source code line appear in the editor. (If you can’t see the editor, you probably need to drag up the split view from the bottom of the window.) The line itself seems fine. The problem is probably where we declared the variable, namely, in the header.

To get out of the Build workspace, click on the Project workspace button in the toolbar, which is on the far left. Now click on the UnitaryController.h header. In the editor, you should see that the variable fahrenheitTextField has been misspelt. Correct the spelling, and click ‘Build’ in the toolbar. It should succeed this time around.

Next Time…

That’s the ball game for this week. You can download the project so far by clicking here. You got to play a bit with Xcode, but you’ll have to wait until next time to actually get the app up and running. We will move into Interface Builder, and add those text fields discussed above. Within no time you will be able to convert temperatures for your European/US colleagues. Not very exciting, I know, but after that we will push into more interesting territory, and actually try to make a useful utility.