Mojomonkey Coding

I’m writing this quick little tutorial because I could not find a single source for what I wanted to do, but found myself reading multiple docs and putting it together. So, here we go:

Having Return Execute an Action for an NSTextField

Part 1: Quick Setup

1. Create a new Cocoa Application named TextFieldTutorial. (I am not going to go into much detail about this, as there are better beginning tutorials out there if you need it).
2. Open your MainMenu.xib and create your UI. Create two NSTextFields one for input and the other for output. Set these up visually however you’d like.
3. Add a new File that extends NSObject and name it TextFieldTutorialController (be sure to generate the .h file as well).

Part Two: Writing the Code

There are a couple set-up things we need to add to the code. We’ll need to add the references to the two NSTextFields in our controller’s header file. Make sure these are tagged by IBOutlet to allow Interface Builder to know that it can hook into it.

Additionally, create the method definition for hitting enter. You code should look something like:

#import <Cocoa/Cocoa.h>

@interface TextFieldTutorialController : NSObject {

IBOutlet NSTextField* inputField;

IBOutlet NSTextField* outputField;

}

-(IBAction)userHitEnter:(id)sender;

@end

Next, all we have to do is fill in the body for userHitEnter. It will be a rather simplistic method:

@implementation TextFieldTutorialController

-(IBAction)userHitEnter:(id)sender {

[outputField setStringValue:[inputField stringValue]];

}

@end

Yep, that’s it. This is easy.

Part Three: Hooking Everything Together

Now, that our code is ready, we need to hook the UI to the controller. Go back to Interface Builder and add a new Object to your NIB file.

Change the type of NSObject to TextViewTutorialController:

Now, hook up the outlets of TextViewTutorialController to the two NSTextViews. Do this for both inputText and outputText.

Next, we need to set up our inputText object. First, we will set it to only call an action on Enter. Otherwise, we would be making a message call on every press of the keyboard (feel free to leave it like this if you want to experiment).

Then the last thing we need to do it set the Sent Actions selector of the Input NSTextField to our controller and select the userHitEnter method.

That’s it! Build and Run, and you should be able to type anything in the inputText area and hit enter, this will update the outputText.

Often times you’ll see:

-(IBAction)someMethod:(id)sender

IBAction is the return value of the method, but what is IBAction? IBAction is void. Nothing is returned by the method. It does provide Interface Builder a hint that this should be exposed as a callable action from a UI element.

When refactoring existing code, be careful to ensure that your Interface Builder outlets are still correct. For example, if I have a simple controller class with the following attributes:

They are defined as IBOutlet’s and are, therefore, connected in Interface Builder to UI elements.

Now, let’s say we wish to change the name of “switcher” to “switchElement”. Obviously, the worst thing we could do is make the change manually, even without the Interface Builder connections we’d have to manually update both the .H and the .M files. So, we should make use of Xcode’s refactoring mechanism.

Right click on the attribute in question (“switcher”), and select Refactor

This will bring up a new Dialog with the “rename” option already selected. Type in the new name, it will identify what files will be changed. You’ll notice that the .H, .M and the nib file are selected for changing.

Once you apply the change, you’ll need to revert the nib in Interface Builder to the version on file. However, Xcode doesn’t handle everything for you, there is one more step that you have to take care of. If you open up the connections part of the UI, you’ll see that it did, in fact, update your connection. But, the old outlet name still appears as another entry and the new name has a warning. The warning is that the class doesn’t have an outlet with the new name.

After banging my head for awhile trying to figure out why they wouldn’t take the final step during a refactor I realized I needed to do one more thing. Save the .M and .H files. Now, everything is in sync and working properly.