1. Ekkehard Koch
  2. pyobjc


pyobjc / pyobjc / Doc / tutorial / tutorial.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Creating your first PyObjC application.</title>
<h2>Creating your first PyObjC application.</h2>
<p>In this tutorial you will learn how to create your first Python Cocoa application:
a simple dialog that allows you to convert amounts of money from one
currency to another. Definitely easier to do with a calculator, but in the
process of following the tutorial you will learn which bits of Apple's Cocoa
documentation apply to PyObjC and which bits are different, and how to adapt
the different bits to PyObjC from Objective-C.</p>
<p>To follow the tutorial you need PyObjC, which you apparently have, and either
Python 2.2 (pre-installed by Apple since Mac OS X 10.2) or MacPython 2.3,
which you probably also have. PyObjC works fine with any python more recent than
2.2, so if you installed python 2.2.2 through <code><span>fink</span></code> that should work, but
you will have to work out the details for step 1 yourself. PyObjC does not
work with MacPython-2.2 or MacPython-OS9 2.3.</p>
<p>In addition you need Interface Builder to
create your user interface. Interface Builder is not included in Mac OS X
by default, but it is part of Apple's free Developer Tools, which can
be gotten from <a href="http://developer.apple.com/tools">http://developer.apple.com/tools</a> as a hefty 300 MB download
after registering (for free).</p>
<h2><a name="getting-started">Getting Started</a></h2>
<ol type="1">
<li>Create a work directory <code><span>src</span></code>. Check which Python you have installed PyObjC
for, by running <code><span>python</span></code> and checking that <code><span>import</span> <span>Foundation</span></code> works. If it
does not work it could be that you have installed PyObjC for <code><span>/usr/local/python</span></code>
but Apple's <code><span>/usr/bin/python</span></code> comes first in your <code><span>$PATH</span></code>. Make sure you
use the right python whereever it says <code><span>python</span></code> in this tutorial.<p>For convenience, set a shell variable PYLIB
to the Python Lib directory. For MacPython-2.3 this will be:</p>
$ setenv PYLIB /Library/Frameworks/Python.framework/Versions/Current/lib/python2.3
<p>or if you use bash as your shell:</p>
$ export PYLIB=/Library/Frameworks/Python.framework/Versions/Current/lib/python2.3
<p>For Apple's <code><span>/usr/bin/python</span></code> set the variable to <code><span>/usr/lib/python2.2</span></code>,
if you are running on MacOS X set it to <code><span>/System/Library/Frameworks/Python.framework/Versions/Current/lib/python2.3</span></code>.</p>
<li>Start Interface Builder, select <i>Cocoa Application</i>
in the new file dialog, save this file as <code><span>src/MainMenu.nib</span></code>.</li>
<li>Proceed with the instructions as lined out in Apple's
<a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjCTutorial/index.html">Developing Cocoa Objective-C Applications: a Tutorial</a>, <a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjCTutorial/chapter03/index.html">chapter 3</a>,
just after the section &quot;<i>Creating the Currency Converter Interface</i>&quot;.
Work through &quot;Defining the Classes of Currency Converter&quot;, &quot;Connecting
ConverterController to the Interface&quot;, and stop at &quot;<i>Implementing the Classes
of Currency Converter</i>&quot;, as we are going to do this in Python, not Objective-C.
Your nib file should now be the same as <a href="step3-MainMenu.nib">step3-MainMenu.nib</a>.</li>
<ol start="4" type="1">
<li>Create the skeleton Python script by running <code><span>NibClassBuilder</span></code> as a tool.
When invoked as a main program from the command line <code><span>NibClassBuilder</span></code> will
parse the NIB file and create a skeleton module for you. Invoke
it as follows (from the <code><span>src</span></code> directory):<pre>
$ python $PYLIB/site-packages/PyObjC/PyObjCTools/NibClassBuilder.py \
        MainMenu.nib &gt; CurrencyConverter.py
<p>The result of this can be seen in <a href="step4-CurrencyConverter.py">step4-CurrencyConverter.py</a>.</p>
<ol start="5" type="1">
<li>There is no step 5.</li>
<h2><a name="testing-the-user-interface">Testing the user interface</a></h2>
<ol start="6" type="1">
<li>Now we need to create an application framework around our program. Again,
in the future it could well be that this step is not needed during 
development, or that it becomes simpler, but for now we do the following:<pre>
$ python $PYLIB/site-packages/PyObjC/bundlebuilder.py --link --nib=MainMenu \
        --mainprogram=CurrencyConverter.py --resource=MainMenu.nib build
<p>If you are using Python 2.3 the script is located in <code><span>plat-mac</span></code> instead
of <code><span>site-packages</span></code> and the command is:</p>
$ python2.3 $PYLIB/plat-mac/PyObjC/bundlebuilder.py --link --nib=MainMenu \
        --mainprogram=CurrencyConverter.py --resource=MainMenu.nib build
<p>There are a few things to note:</p>
<li>We use the <code><span>--link</span></code> argument. This creates a <code><span>.app</span></code> bundle which has symlinks
to our source files (<code><span>CurrencyConverter.py</span></code> and <code><span>MainMenu.nib</span></code>) in stead of copies.
This allows us to keep working on the sources without having to re-run bundlebuilder
after every edit.</li>
<li>You have to specify MainMenu twice: once (with <code><span>--resource</span></code>) to get it linked/copied 
into the bundle and once (with <code><span>--nib</span></code>) to get it listed in the <code><span>.plist</span></code> file.</li>
<li>Run the program. This can be done in three ways:<ul>
<li>double-click <code><span>build/CurrencyConverter.app</span></code> from the Finder (where you won't see the
.app extension)</li>
<li>similarly, open it from the terminal with:<pre>
$ open build/CurrencyConverter.app
<li>run it directly from the Terminal, as:<pre>
$ ./build/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
<p>The last method is actually the best to use: it leaves stdout and stderr connected
to your terminal session so you can see what is going on if there are errors. When
running with the other two methods stdout and stderr go to the console.</p>
<p>When you run your script as it is now it should behave identically as when you
tested your interface in Interface Builder in step 3, only now the skeleton is
in Python, not Objective-C.</p>
<h2><a name="writing-the-code">Writing the code</a></h2>
<ol start="8" type="1">
<li>Time to actually write some code. Edit CurrencyConverter.py again, and add
some. Follow Apple's documentation again, chapter 3, section &quot;Implementing
Currency Converter's Classes&quot;. We need to do some name mangling on ObjC
names to get the corresponding Python names, see <i>An introduction to PyObjC</i>
for the details, but
in short if the ObjC name of a method is <code><span>modifyArg:andAnother:</span></code>, in
other words, if an ObjC call would be:<pre>
[object modifyArg: arg1 andAnother: arg2]
<p>the Python name will be <code><span>modifyArg_andAnother_</span></code> and you invoke it as:</p>
object.modifyArg_andAnother_(arg1, arg2)
<p>Note that we don't do this mangling for <code><span>Converter.convertAmount()</span></code>: this method is
only called by other Python code, so there is no need to go through the name mangling.
Also, if we would want to make this method callable from ObjC code we would have
to tell the PyObjC runtime system about the types of the arguments, so it could
do the conversion. This is beyond the scope of this first tutorial, <i>An introduction to PyObjC</i>
has a little more detail on this.</p>
<p>The application should now be fully functional, try it. The results of what we have
up to now can be seen in <a href="step8-CurrencyConverter.py">step8-CurrencyConverter.py</a>.</p>
<h2><a name="extending-the-functionality">Extending the functionality</a></h2>
<ol start="9" type="1">
<li>We are going to add one more goodie, just to show how you edit an existing application.
The main problem, which may be obvious, is that we cannot run NibClassBuilder again
because we would destroy all the code we wrote in steps 5 and 8, so we do this by
hand.<p>What we are going to do is add an &quot;invert rate&quot; command, because I always get this
wrong: in stead of typing in the exchange rate from dollars to euros I type in the
rate to convert from euros to dollars.</p>
<p>Open <code><span>MainMenu.nib</span></code> in Interface Builder. Select the <i>Classes</i> view and there select the
<code><span>ConverterController</span></code> class. In the info panel select the <i>Attributes</i> from the popup.
Select the <i>Actions</i> tab, and add an action <code><span>invertRate:</span></code>. You have now told Interface Builder
that instances of the <code><span>ConverterController</span></code> class have grown a new method <code><span>invertRate_()</span></code>.</p>
<p>In the <code><span>MainMenu.nib</span> <span>main</span></code> window open the <i>MainMenu</i> menubar. Select the <code><span>Edit</span></code>
menu. Make sure the <i>Menus</i> palette is open and selected, drag a separator to the 
<code><span>Edit</span></code> menu and then drag an <code><span>Item</span></code> there. Double click the item and set the text to
<code><span>Invert</span> <span>Exchange</span> <span>Rate</span></code>.</p>
<p>Make the connection by control-dragging from the new <code><span>Invert</span> <span>Exchange</span> <span>Rate</span></code> menu item to
the <code><span>ConverterController</span></code> instance in the Instances tab in the <code><span>MainMenu.nib</span></code> main window.
<i>NOTE:</i> you drag to the <i>instance</i> of <code><span>ConverterController</span></code>, not to the class. This is logical
if you think about it, but I keep forgetting it myself all the time too.
In the <i>Info</i> panel, <i>Connections</i> section, select <code><span>invertRate:</span></code> and press <i>Connect</i>. 
<i>NOTE:</i> that is another thing I always forget: pressing <i>Connect</i> after selecting the action:-)</p>
<li>We know our program can't invert rates yet, because we haven't actually written the code
to do it, but we are going to try it anyway, just to see what sort of spectacular
crash we get. Alas, nothing spectacular about it: when the NIB is loaded the Cocoa runtime
system tries to make the connection, notices that we have no <code><span>invertRate_()</span></code> method in
our <code><span>ConverterController</span></code> class and it gives an error message:<pre>
$ ./build/CurrencyConverter.app/Contents/MacOS/CurrencyConverter 
2003-03-24 16:22:43.037 CurrencyConverter[16163] Could not connect the action 
invertRate: to target of class ConverterController
<p>Moreover, it has disabled the <code><span>Invert</span> <span>Exchange</span> <span>Rate</span></code> menu command and continues, so the 
program really works as it did before, only with one more (disabled) menu item.</p>
<h2><a name="debugging">Debugging</a></h2>
<ol start="11" type="1">
<li>Writing the code is easy: add a method <code><span>invertRate_(self,</span> <span>sender)</span></code> that gets the float
value of <code><span>rateField</span></code>, inverts it and puts it back. We deliberately forget to test for
divide by zero. We run the program again, and now the menu entry is enabled. After
trying it with a couple of non-zero exchange rates we try it with an exchange rate of
zero (or empty, which is the same). We get a dialog box giving the Python exception, and
offering the choice of continuing or quitting.<p><i>XXXX Implementation Note:</i> what is described in the next paragraph does not
seem to work in the current distribution.</p>
<p>If we select <i>Quit</i> then we get a normal
Python exception traceback in the Terminal window. The exception is actually re-raised,
so we can use the standard Python trick to debug this: set shell variable
<code><span>PYTHONINSPECT</span></code> to <code><span>1</span></code>, run our program, try to invert an exchange rate of <code><span>0</span></code>, press quit.
At the <code><span>&gt;&gt;&gt;</span></code> prompt, type <code><span>import</span> <span>pdb</span> <span>;</span> <span>pdb.pm()</span></code> and we can inspect all local variables,
<li>Fix the final bug by testing for <code><span>rate==0</span></code> in <code><span>invertRate_()</span></code>. The result is in the
<a href="step12-src">step12-src</a> directory.</li>
<h2><a name="creating-an-applet-for-local-use">Creating an applet for local use</a></h2>
<p>Your application is finished, and you want to move it to the <code><span>Applications</span></code> folder
(or anywhere else) and insulate it from the original source code.
This can be done by re-running the <code><span>bundlebuilder.py</span></code> invocation from step
6 without  using the '--link' in the invocation. Move <code><span>build/CurrencyConverter.app</span></code>
anywhere you want and double-click it from the Finder to run it.</p>
<p>For programs with more Python sourcefiles you include all additional sources as resources.</p>
<p>It is even possible to include all of Python (or, if you are using Apple's Python 2.2,
all the bits of Python that are non-standard), this gives you an application that
is distributable to anyone in the world (as long as they have Mac OS X 10.2)! Unfortunately,
the exact details of this procedure are not streamlined enough for inclusion in this
tutorial at this point in time.</p>