Getting Started - Responding to Events
Events are at the heart of GUI programming. Every Cocoa application has an "event loop" that repeatedly looks for incoming events such as mouse clicks, menu selections, and key strokes, and dispatches the corresponding events to your application. A great deal of your application code - possibly even all of it - will be contained in methods that are called in response to these events.
This HowTo will show you how to write an event handler method. In it you'll add a button to your application's main window, and respond when a user clicks on that button by writing a message to the console. (We'll display the message in a GUI element in the next lesson - one thing at a time for now.) If you've already done the previous "Hello World!" HowTo, you can keep using that; if not, begin by creating a new Cocoa-Perl application project in Xcode.
This HowTo assumes that you've used the name "Hello" for your project. The file and class names reflect that of the project. The class HelloWindowController is used in Interface Builder, and is defined in HelloWindowController.pm. If you've created your project using a different name, the names of these classes and files will also be different. For example, if your project is "Goodbye", the class will be called "GoodbyeWindowController", and will be defined in "GoodbyeWindowController.pm".
1. Add a button to the main window
A button in Interface Builder
click to enlarge
Open the MainWindow.nib in Interface Builder. Select the "Cocoa Controls" palette, and drag a button onto the main window. If you want, double-click the button to change its title. You can also change the title in the Info panel, which you can open with cmd-shift-I.
2. Create an action to handle button clicks
Interface Builder's actions tab
click to enlarge
Still in Interface Builder, double-click the blue cube labeled "File's Owner" to edit the definition of the class that "owns" the MainWindow.nib. The main IB window should switch from the "Instances" to the "Classes" tab, with the "MyWindowController" class selected. The info panel should appear if it's not already visible. First, change the name of the class from "MyWindowController" to "HelloWindowController".
Adding an action in Interface Builder
click to enlarge
In the Info panel, there are two tabs. If you're using a brand new project, these will read "1 Outlet" and "0 Actions." Select the "Actions" tab. Actions are messages that are sent to your Perl code in response to GUI events. Typically, they are named the same as the Perl methods that are called to handle them. Outlets are used in the next HowTo, "Updating Controls."
Define an action message that a "HelloWindowController" object will be able to receive by clicking the "add" button located at the bottom of the Info panel. This should add the action to the list, with the action name selected and editable. Let's call this action "sayHello". Note that, when you press "return" to end editing, IB adds a colon to the end of the action name - don't be concerned, that's normal.
3. Create the connection from the button to the action
Drawing a connection
click to enlarge
In the main IB window, switch back to the "Instances" tab.
Holding down the control key, click on the button you added to the main window, and drag the mouse cursor to the blue cube labeled "File's Owner." While you're dragging, you should see a line being drawn, which represents the connection you're creating. Note that the direction of the dragging is significant, and determines the type of connection that is created; dragging from "File's Owner" to the button will create an Outlet, not an Action. Outlets are described in more detail in the next HowTo, "Updating controls."
Choosing the action
click to enlarge
In the Info window, the "Connections" pane should be selected, and "Target/Action" tab should list all the actions defined for the "HelloWindowController" class. If you started with a clean project, and used the action name suggested above, there should be a single item in this list named "sayHello:".
Select the "sayHello:" action, which will enable the "connect" button at the bottom of the Info panel. Clicking the "connect" button will create the connection. A dot should appear to the left of the action name to indicate an active connection.
You're finished with Interface Builder for now, so save your work and switch back to Xcode.
4. Create the Perl method to handle the action
To handle incoming actions, you need to add the corresponding methods to the controller class. Assuming your project is named "Hello", that will be "HelloWindowController", defined in "HelloWindowController.pm".
You should give the method the same name as the message to which it responds. For example, if you used the action name suggested above, you'd name the method "sayHello," and it would look something like this:
# Handle the sayHello: action
sub sayHello : Selector(sayHello:) IBAction {
NSLog("Hello, world!");
}
Note: the NSLog() function is a Cocoa function that sends output to the console, similar to Perl's own print() function.
Output from NSLog()
click to enlarge
Save the HelloWindowController.pm file, and build and run your application. The "Hello World!" message printed by the NSLog() function should appear in the Xcode output panel. If you run your application outside of Xcode, the output will appear in the console log, which you can use "Console.app" to view.
What's next?
Next: Outlets