This tutorial is aimed primarily at people with little or no background in ObjC and Cocoa, and it will help you to understand PyObjC programs written by other people, such as the examples included with the distribution. This document is actually not a true tutorial: you do not get to build anything, only read and examine things.
It is strongly suggested that you first do the Creating your first PyObjC application tutorial to get some hands-on experience with PyObjC, Cocoa and especially Interface Builder.
If you have used another GUI toolkit in the past it is essential that you understand that Cocoa is different. For this once this isn't marketing-speak: Cocoa is inherently different from common toolkits such as Tk, wxWindows, Carbon, win32 and all the other popular ones. Apple's documentation explains this, but in the introductory sections that are often quickly glanced over. It is a good idea to refer back to Application Architecture after reading this section. If you really want you can break out of the architecture sketched in this section, but then you are on your own, really: Cocoa and Interface Builder really expect you to follow this model.
Cocoa is built on the Model-View-Controller paradigm (MVC). What this means is that the application code is going to be split into three parts:
To summarize: the Model knows nothing about dialogs and buttons and such, the View knows nothing about data and algorithms and the Controller ties it all together. For really tiny applications, such as the currency converter, you could do away with the Model and simply put that code right in the Controller. MVC purists say you should not do this, and it can indeed make your code harder to read (because the Controller will contain a mix of algorithms and glue code), but there is no architectural reason that stops you. If you combine the two classes it is customary to use the name you would use for your document class, so without "Controller". Note that MVC is not specific to Cocoa, you can use the paradigm with any GUI toolkit, but Cocoa really steers you towards it.
You should have an MVC trio for every distinct unit of information in your program. In case of a simple dialog-style application such as Currency Converter you will have one such trio. Most applications, however, will have at least two: one for the application itself and one for the "documents" the application handles. These may be real documents (i.e. files), but they could also be more abstract. If your application does scientific simulation and you want to be able to open two simulation windows at the same time you should use the document model.
Cocoa and Interface Builder strongly encourage you to use a NIB file per MVC trio. Again: follow this encouragement unless you are sure what you are doing.
This brings us to the second big difference between Cocoa and other GUI toolkits: almost all the boilerplate code is in the NIB, and therefore the source of Cocoa programs, especially example programs that do little real work, will look stunningly small if you are familiar with, say, Tkinter.
The NIB file is not a description of dialogs and menus and buttons, as you would get out of interface-builders for other toolkits. There, at startup something will read the description, create the buttons and hand the finished dialog to your code. A NIB file is more: it contains a complete set of frozen objects, conceptually similar to a pickle in Python. You tell Interface Builder knows about all the relevant classes in your application, the instances you want to create from those classes, and how the classes should connect to each other. Interface Builder the actually instantiates the classes, makes all the connections and at that point freezes and stores the whole lot.
When your NIB is read the objects are thawed, the connections restored and the objects get a running start. Again, this is conceptually similar to how unpickling works.
The section above explains a lot of the strangeness in PyObjC programs: why you don't create windows and other dialogs (they already exist); why you shouldn't do initialization in
__init__(because it will be called at some undefined point in time, while reading the NIB) but inawakeFromNib:in stead; why you don't have to create and initialize the attributes that tie your objects together (they are already tied together).
awakeFromNib:is very similar in nature to__setstate__for a pickled Python object, but it happens after all objects have been unserialized.
This also explains why you want separate NIB files for each MVC trio: the objects and classes in a NIB file are all unpickled together. In other words: if you had created your document window in your application NIB (even if you set it to "hidden" initially so it does not show up) it would become very difficult to create a second window for a new document.
If you think about the consequences of this section for a while it will become clear why all the boilerplate code is missing from Cocoa applications: you don't need it. The NIB file usually contains all of the things that need to be done for the Views objects, as is often the case with other gui-builders. But in addition the NIB also contains a large proportion of your Model functionality: creating the View and Controller objects and tieing the lot together.
If you are familiar with other object-oriented GUI toolkits such as MFC
another thing to notice is that Cocoa applications often use a delegate
object where other toolkits would use a subclass. For example: it is not
common to use your own subclass in stead of NSApplication for the
main application object. In stead, NSApplication objects have a helper
called its delegate. The application object will attempt to inform
its delegate of all sorts of things happening, and the delegate implements
only the methods for the events in which it is interested.
For example, the method applicationShouldTerminate: on the delegate
is called just before the application quits, and it has a chance to return
NO if you don't want to quit just yet.
Let us examine the final NIB of the Currency Converter tutorial with this in mind.
If you open it and look at the main window (the one with "MainMenu.nib" as
its title) and select the "Instances" pane you see six objects. Two of these
have a greyed-out name ("File's Owner" and "First Responder"): these have
been created for you by Apple. The other four are created by you. Actually:
"Main Menu" was created by Apple as a convenience, but you are free to modify
it. The "File's Owner" is either the Controller or the combined Model-Controller
object, in this case it is the application itself, an instance of NSApplication.
Because this application is not a document-based application the MVC trio
for the actual conversion window are in here too: Converter, Window and
ConverterController respectively.
Let us have a look at the ConverterController object by double clicking it.
The "MainMenu.nib" window goes to the "Classes" tab, and an info window shows up.
In the "MainMenu.nib" window the ConverterController class is selected, and
you can see it is a subclass of NSobject. Having the same name for the class
and the instance is common in Cocoa programs, the main exception being the File
Owner object.
The info window shows more information on the ConverterController class. It
should pop open to the "attributes" page. In the "Outlets" tab you see that instances
of this class have four attributes, converter, rateField, dollarField
and totalField. In any instance of ConverterController you can connect these
to other objects, as we shall see below. The "Actions" tab shows that there are two
methods convert: and invertRate:, and again you can arrange for these to
be called on instances of your ConverterController on certain events by
making connections.
So let us now look at the connections for our ConverterController instance. Select
the "Instances" tab in the main window, select ConverterController and set the info
window to show "Connections". You now see all the outlets defined in the class.
Select one, and in the lower half of the info window you will see which object it connects
to. Moreover, a blue line will also link the object representations in the main window and
in the dialog preview window.
Finding out who calls your convert: method is more difficult, though, with this view.
But, if you select the "Convert" button in the dialog you will see that its target
action will go to the ConverterController.convert: method.
Luckily there is a way to find such incoming connections without reverting to guessing.
For instance, you will be hard put to find who, if anyone, calls
ConverterController.invertRate:. The solution: go to the "MainMenu.nib" window and
look at the top of the vertical scrollbar. There are two little icons there, one with
lines and one with squares, with the squares being higlighted. Press it. The view will change
to a scrollable list with objects in the left column and an indication of connections
in the right column. You can now see our ConverterController object has four
outgoing connections (the ones we found earlier) and two incoming connections. Click
on the incoming connections icon. The view will change again and ConverterController
will probably scroll out of sight. Locate it, and see that there are two lines
going out of the ConverterController object. One goes to NSButton(Convert)
and is labeled convert:, we knew about that already. The other one goes to an
object NSMenuItem(Invert Exchange Rate) and is labeled invertRate:, so that
is where calls to invertRate: come from. And if you look at where this
NSMenuItem sits in the object hierarchy you find that it is an entry in the
"Edit" menu in the menubar.
This section remains to be written. Contributions will be gratefully accepted:-)