1 2 3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5 6 7<html xmlns="http://www.w3.org/1999/xhtml"> 8 <head> 9 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 10 11 <title>An introduction to PyObjC — PyObjC-Core 2.5.0b1 documentation</title> 12 13 <link rel="stylesheet" href="_static/default.css" type="text/css" /> 14 <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> 15 16 <script type="text/javascript"> 17 var DOCUMENTATION_OPTIONS = { 18 URL_ROOT: '', 19 VERSION: '2.5.0b1', 20 COLLAPSE_INDEX: false, 21 FILE_SUFFIX: '.html', 22 HAS_SOURCE: true 23 }; 24 </script> 25 <script type="text/javascript" src="_static/jquery.js"></script> 26 <script type="text/javascript" src="_static/underscore.js"></script> 27 <script type="text/javascript" src="_static/doctools.js"></script> 28 <link rel="top" title="PyObjC-Core 2.5.0b1 documentation" href="index.html" /> 29 <link rel="next" title="PyObjC Tutorials" href="tutorials/index.html" /> 30 <link rel="prev" title="Welcome to PyObjC-Core’s documentation!" href="index.html" /> 31 </head> 32 <body> 33 <div class="related"> 34 <h3>Navigation</h3> 35 <ul> 36 <li class="right" style="margin-right: 10px"> 37 <a href="genindex.html" title="General Index" 38 accesskey="I">index</a></li> 39 <li class="right" > 40 <a href="py-modindex.html" title="Python Module Index" 41 >modules</a> |</li> 42 <li class="right" > 43 <a href="tutorials/index.html" title="PyObjC Tutorials" 44 accesskey="N">next</a> |</li> 45 <li class="right" > 46 <a href="index.html" title="Welcome to PyObjC-Core’s documentation!" 47 accesskey="P">previous</a> |</li> 48 <li><a href="index.html">PyObjC-Core 2.5.0b1 documentation</a> »</li> 49 </ul> 50 </div> 51 52 <div class="document"> 53 <div class="documentwrapper"> 54 <div class="bodywrapper"> 55 <div class="body"> 56 57 <div class="section" id="an-introduction-to-pyobjc"> 58<h1>An introduction to PyObjC<a class="headerlink" href="#an-introduction-to-pyobjc" title="Permalink to this headline">¶</a></h1> 59<div class="section" id="preface"> 60<h2>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h2> 61<p>PyObjC is a bridge between Python and Objective-C. It allows Python 62scripts to use and extend existing Objective-C class libraries; 63most importantly the <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a> by <a class="reference external" href="http://www.apple.com/">Apple</a>.</p> 64<p>This document describes how to use Objective-C class libraries from Python 65scripts and how to interpret the documentation of those libraries from the 66point of view of a Python programmer.</p> 67</div> 68<div class="section" id="first-steps"> 69<h2>First Steps<a class="headerlink" href="#first-steps" title="Permalink to this headline">¶</a></h2> 70<p>When dealing with the Objective-C runtime, there are certain patterns 71you need to learn when writing Python code. If you’re not already an 72Objective-C programmer, some of them will seem strange or even 73“un-pythonic” at first. However, you will get used to it, and the way 74that PyObjC works is quite compliant with the <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0020"><strong>PEP 20</strong></a> (the Zen of Python, 75<tt class="docutils literal"><span class="pre">import</span> <span class="pre">this</span></tt>). In fact, Ronald is Dutch ;)</p> 76<p>With no further ado, here are the three most important things you 77<em>must</em> know before embarking on any PyObjC voyage:</p> 78<div class="section" id="underscores-and-lots-of-them"> 79<h3>Underscores, and lots of them<a class="headerlink" href="#underscores-and-lots-of-them" title="Permalink to this headline">¶</a></h3> 80<p>Objective-C objects communicate with each other by sending messages. 81The syntax for messages is somewhere in-between Python’s positional and 82keyword arguments. Specificlaly, Objective-C message dispatch uses 83positional arguments, but parts of the message name (called “selector” 84in Objective-C terminology) are interleaved with the arguments.</p> 85<p>An Objective-C message looks like this:</p> 86<blockquote> 87<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">someObject</span> <span class="nl">doSomething:</span><span class="n">arg1</span> <span class="nl">withSomethingElse:</span><span class="n">arg2</span><span class="p">];</span> 88</pre></div> 89</div> 90</div></blockquote> 91<p>The selector (message name) for the above snippet is this (note the colons):</p> 92<blockquote> 93<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="nl">doSomething:withSomethingElse:</span> 94</pre></div> 95</div> 96</div></blockquote> 97<p>In order to have a lossless and unambiguous translation between Objective-C 98messages and Python methods, the Python method name equivalent is simply 99the selector with colons replaced by underscores. Since each colon in an 100Objective-C selector is a placeholder for an argument, the number of 101underscores in the PyObjC-ified method name is the number of arguments 102that should be given.</p> 103<p>The PyObjC translation of the above selector is (note the underscores):</p> 104<blockquote> 105<div><div class="highlight-python"><div class="highlight"><pre><span class="n">doSomething_withSomethingElse_</span> 106</pre></div> 107</div> 108</div></blockquote> 109<p>The message dispatch, translated to PyObjC, looks like this:</p> 110<blockquote> 111<div><div class="highlight-python"><div class="highlight"><pre><span class="n">someObject</span><span class="o">.</span><span class="n">doSomething_withSomethingElse_</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">)</span> 112</pre></div> 113</div> 114</div></blockquote> 115<p><em>Methods that take one argument will have a trailing underscore</em>.</p> 116<p>It may take a little while to get used to, but PyObjC does not ever 117rename selectors. The trailing underscore will seem strange at first, 118especially for cases like this:</p> 119<blockquote> 120<div><div class="highlight-python"><div class="highlight"><pre><span class="c"># note the trailing underscore</span> 121<span class="n">someObject</span><span class="o">.</span><span class="n">setValue_</span><span class="p">(</span><span class="n">aValue</span><span class="p">)</span> 122</pre></div> 123</div> 124</div></blockquote> 125<p>There are a few additional rules regarding message dispatch, see the 126<a class="reference internal" href="#overview-of-the-bridge">Overview of the bridge</a> for the complete rundown.</p> 127</div> 128<div class="section" id="two-phase-instantiation"> 129<h3>Two-phase instantiation<a class="headerlink" href="#two-phase-instantiation" title="Permalink to this headline">¶</a></h3> 130<p>Objective-C, being a low-level runtime, separates the two concepts required 131to instantiate an object.</p> 132<dl class="docutils"> 133<dt>allocation:</dt> 134<dd>Reserve a chunk of memory large enough to hold the new object, and make 135sure that all of its declared instance variables are set to “zero” 136(this means nil pointers to objects, 0 for integers, etc.).</dd> 137<dt>initialization:</dt> 138<dd>Fill in the blank slate allocated by the allocation phase.</dd> 139</dl> 140<p>In Objective-C, the convention is for allocation to be performed by a class 141method called <tt class="docutils literal"><span class="pre">alloc</span></tt>, and initialization is done with method 142<em>beginning with</em> the word <tt class="docutils literal"><span class="pre">init</span></tt>. For example, here is the syntax for 143instantiating an <tt class="docutils literal"><span class="pre">NSObject</span></tt>:</p> 144<blockquote> 145<div><div class="highlight-python"><div class="highlight"><pre><span class="n">myObject</span> <span class="o">=</span> <span class="n">NSObject</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 146</pre></div> 147</div> 148</div></blockquote> 149<p>And here is an example for creating an <tt class="docutils literal"><span class="pre">NSData</span></tt> instance given a few bytes:</p> 150<blockquote> 151<div><div class="highlight-python"><div class="highlight"><pre><span class="n">myData</span> <span class="o">=</span> <span class="n">NSData</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">initWithBytes_length_</span><span class="p">(</span><span class="s">'the bytes'</span><span class="p">,</span> <span class="mi">9</span><span class="p">)</span> 152</pre></div> 153</div> 154</div></blockquote> 155<p>You must also follow this convention when subclassing Objective-C classes. 156When initializing, an object must always (directly or indirectly) call the 157designated initializer of its <tt class="docutils literal"><span class="pre">super</span></tt>. The designated initializer is the 158“most basic” initializer through which all initialization eventually ends up. 159The designated initializer for <tt class="docutils literal"><span class="pre">NSObject</span></tt> is <tt class="docutils literal"><span class="pre">init</span></tt>. To find the 160designated initializer for other classes, consult the documentation for that 161class. Here is an example of an <tt class="docutils literal"><span class="pre">NSObject</span></tt> subclass with a customized 162initialization phase:</p> 163<blockquote> 164<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 165 2 166 3 167 4 168 5 169 6 170 7 171 8 172 9 17310 17411 17512 17613 17714 17815 17916 18017 18118 18219 18320 18421 18522 18623 18724 18825 18926 19027 19128 19229 19330 19431 19532 19633</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span> 197 198 <span class="k">def</span> <span class="nf">init</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> 199 <span class="sd">"""</span> 200<span class="sd"> Designated initializer for MyClass</span> 201<span class="sd"> """</span> 202 <span class="c"># ALWAYS call the super's designated initializer.</span> 203 <span class="c"># Also, make sure to re-bind "self" just in case it</span> 204 <span class="c"># returns something else, or even None!</span> 205 <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyClass</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 206 <span class="k">if</span> <span class="bp">self</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span> <span class="k">return</span> <span class="bp">None</span> 207 208 <span class="bp">self</span><span class="o">.</span><span class="n">myVariable</span> <span class="o">=</span> <span class="mi">10</span> 209 210 <span class="c"># Unlike Python's __init__, initializers MUST return self,</span> 211 <span class="c"># because they are allowed to return any object!</span> 212 <span class="k">return</span> <span class="bp">self</span> 213 214 215<span class="k">class</span> <span class="nc">MyOtherClass</span><span class="p">(</span><span class="n">MyClass</span><span class="p">):</span> 216 217 <span class="k">def</span> <span class="nf">initWithOtherVariable_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">otherVariable</span><span class="p">):</span> 218 <span class="sd">"""</span> 219<span class="sd"> Designated initializer for MyOtherClass</span> 220<span class="sd"> """</span> 221 <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyOtherClass</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 222 <span class="k">if</span> <span class="bp">self</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span> <span class="k">return</span> <span class="bp">None</span> 223 224 <span class="bp">self</span><span class="o">.</span><span class="n">otherVariable</span> <span class="o">=</span> <span class="n">otherVariable</span> 225 <span class="k">return</span> <span class="bp">self</span> 226 227<span class="n">myInstance</span> <span class="o">=</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 228<span class="n">myOtherInstance</span> <span class="o">=</span> <span class="n">MyOtherClass</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">initWithOtherVariable_</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span> 229</pre></div> 230</td></tr></table></div> 231</div></blockquote> 232<p>Many Objective-C classes provide class methods that perform two-phase 233instantiation for you in one step. Several examples of this are:</p> 234<blockquote> 235<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 236 2 237 3 238 4 239 5 240 6 241 7 242 8 243 9 24410 24511 24612 24713 24814 24915 25016 25117</pre></div></td><td class="code"><div class="highlight"><pre><span class="c"># This is equivalent to:</span> 252<span class="c">#</span> 253<span class="c"># myObject = NSObject.alloc().init()</span> 254<span class="c">#</span> 255<span class="n">myObject</span> <span class="o">=</span> <span class="n">NSObject</span><span class="o">.</span><span class="n">new</span><span class="p">()</span> 256 257<span class="c"># This is equivalent to:</span> 258<span class="c">#</span> 259<span class="c"># myDict = NSDictionary.alloc().init()</span> 260<span class="c">#</span> 261<span class="n">myDict</span> <span class="o">=</span> <span class="n">NSDictionary</span><span class="o">.</span><span class="n">dictionary</span><span class="p">()</span> 262 263<span class="c"># This is equivalent to:</span> 264<span class="c">#</span> 265<span class="c"># myString = NSString.alloc().initWithString_(u'my string')</span> 266<span class="c">#</span> 267<span class="n">myString</span> <span class="o">=</span> <span class="n">NSString</span><span class="o">.</span><span class="n">stringWithString_</span><span class="p">(</span><span class="s">u'my string'</span><span class="p">)</span> 268</pre></div> 269</td></tr></table></div> 270</div></blockquote> 271</div> 272<div class="section" id="objective-c-uses-accessors-everywhere"> 273<h3>Objective-C uses accessors everywhere<a class="headerlink" href="#objective-c-uses-accessors-everywhere" title="Permalink to this headline">¶</a></h3> 274<p>Unlike Python, Objective-C convention says to use accessors rather than 275directly accessing instance variables of other objects. This means 276that in order to access an instance variable <tt class="docutils literal"><span class="pre">value</span></tt> of an object 277<tt class="docutils literal"><span class="pre">valueContainer</span></tt> you will have to use the following syntax:</p> 278<blockquote> 279<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 280 2 281 3 282 4 283 5 284 6 285 7 286 8 287 9 28810 28911</pre></div></td><td class="code"><div class="highlight"><pre><span class="c"># Getting</span> 290<span class="c">#</span> 291<span class="c"># notice the method call</span> 292<span class="c">#</span> 293<span class="n">myValue</span> <span class="o">=</span> <span class="n">valueContainer</span><span class="o">.</span><span class="n">value</span><span class="p">()</span> 294 295<span class="c"># Setting</span> 296<span class="c">#</span> 297<span class="c"># notice the naming convention and trailing underscore</span> 298<span class="c">#</span> 299<span class="n">valueContainer</span><span class="o">.</span><span class="n">setValue_</span><span class="p">(</span><span class="n">myNewValue</span><span class="p">)</span> 300</pre></div> 301</td></tr></table></div> 302</div></blockquote> 303<p>When writing your own classes from Python, this is a bit harder since 304Python only has one namespace for all attributes, even methods. If you 305choose to implement accessors from Python, then you will have to name 306the instance variable something else:</p> 307<blockquote> 308<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 309 2 310 3 311 4 312 5 313 6 314 7 315 8 316 9 31710 31811 31912 32013 32114 32215 32316</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyValueHolder</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span> 324 325 <span class="k">def</span> <span class="nf">initWithValue_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> 326 <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyValueHolder</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 327 <span class="c"># It's recommended not to use typical Python convention here,</span> 328 <span class="c"># as instance variables prefixed with underscores are reserved</span> 329 <span class="c"># by the Objective-C runtime. It still works if you use</span> 330 <span class="c"># underscores, however.</span> 331 <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span> <span class="o">=</span> <span class="n">value</span> 332 <span class="k">return</span> <span class="bp">self</span> 333 334 <span class="k">def</span> <span class="nf">value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> 335 <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span> 336 337 <span class="k">def</span> <span class="nf">setValue_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> 338 <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span> <span class="o">=</span> <span class="n">value</span> 339</pre></div> 340</td></tr></table></div> 341</div></blockquote> 342<p>It’s also possible to use <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a> in some cases, which eliminates 343the need for writing most accessors, but only in scenarios where the rest of 344the code is using it.</p> 345</div> 346</div> 347<div class="section" id="objective-c-for-pyobjc-users"> 348<h2>Objective-C for PyObjC users<a class="headerlink" href="#objective-c-for-pyobjc-users" title="Permalink to this headline">¶</a></h2> 349<p>It is recommended that you take the time to understand a little bit about 350Objective-C before jumping into PyObjC development. The class libraries 351that you will be using from Cocoa are not documented in Python, and their 352documentation will be confusing without a grasp on the semantics and syntax 353of Objective-C.</p> 354<p>Objective-C is an object-oriented programming language implemented as a 355superset of C that borrows heavily in concept and syntax from Smalltalk. 356of C and borrows heavily from Smalltalk. It features single inheritance with 357dynamic dispatch and (in theory) multiple root classes. This is basically the 358same as Python with single inheritance.</p> 359<p>An important difference between Python and Objective-C is that the latter is 360not a pure object-oriented language. Some values are not objects, but values 361of plain C types, such as <tt class="docutils literal"><span class="pre">int</span></tt> and <tt class="docutils literal"><span class="pre">double</span></tt>. These basic C types can 362be used as the types of arguments and the return value of methods.</p> 363<p>Object allocation and initialization are explicit and separate actions in 364Objective-C. The former is done by the class-method <tt class="docutils literal"><span class="pre">alloc</span></tt>, while the 365latter is done by instance methods whose name customarily starts with <tt class="docutils literal"><span class="pre">init</span></tt>.</p> 366<p>Objective-C code looks just like plain C code, with some easily recognizable 367Smalltalk-like extensions for the object-oriented parts of the language. An 368example class declaration (usually found in <tt class="docutils literal"><span class="pre">.h</span></tt> files) and implementation 369(usually found in <tt class="docutils literal"><span class="pre">.m</span></tt> files) are listed below. Class declarations are easily 370recognized as blocks of code between <tt class="docutils literal"><span class="pre">@interface</span></tt> and <tt class="docutils literal"><span class="pre">@end</span></tt>, and similarly 371the implementation is between <tt class="docutils literal"><span class="pre">@implementation</span></tt> and <tt class="docutils literal"><span class="pre">@end</span></tt>. An expression 372enclosed in brackets in Objective-C is called a message, and is the equivalent 373to an instance method invocation in Python. For example, this Objective-C 374code:</p> 375<blockquote> 376<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">aMutableArray</span> <span class="nl">addObject:</span><span class="s">@"constant string"</span><span class="p">];</span> 377</pre></div> 378</div> 379</div></blockquote> 380<p>Is equivalent in intent to the following in Python:</p> 381<blockquote> 382<div><div class="highlight-python"><div class="highlight"><pre><span class="n">aList</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">u"constant string"</span><span class="p">)</span> 383</pre></div> 384</div> 385</div></blockquote> 386<p>Objective-C messages have three components: a target, a selector, and zero or 387more arguments. The target, <tt class="docutils literal"><span class="pre">aMutableArray</span></tt>, is the object or class 388receiving the message. The selector, <tt class="docutils literal"><span class="pre">addObject:</span></tt> uniquely identifies the 389kind of message that is being sent. Finally, the arguments, 390<tt class="docutils literal"><span class="pre">@"constant</span> <span class="pre">string"</span></tt> are used by the implementation of the method upon 391receipt of the message. The syntax of Objective-C message dispatch is 392deceptively similar to keyword arguments in Python, but they are actually 393quite different. Objective-C messages can not have default arguments, and all 394arguments are passed in a specific order. The components of a selector may not 395be reordered. Syntactically, one argument must be interleaved at every colon in 396the selector. The message:</p> 397<blockquote> 398<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">anArray</span> <span class="nl">indexOfObject:</span><span class="n">someObject</span> <span class="nl">inRange:</span><span class="n">someRange</span><span class="p">]</span> 399</pre></div> 400</div> 401</div></blockquote> 402<dl class="docutils"> 403<dt>Target:</dt> 404<dd><tt class="docutils literal"><span class="pre">anArray</span></tt></dd> 405<dt>Selector:</dt> 406<dd><tt class="docutils literal"><span class="pre">indexOfObject:inRange:</span></tt></dd> 407<dt>Arguments:</dt> 408<dd><tt class="docutils literal"><span class="pre">someObject</span></tt>, <tt class="docutils literal"><span class="pre">someRange</span></tt></dd> 409</dl> 410<p>As documented later, the straightforward translation of such a message to 411Python is:</p> 412<blockquote> 413<div><div class="highlight-python"><div class="highlight"><pre><span class="n">anArray</span><span class="o">.</span><span class="n">indexOfObject_inRange_</span><span class="p">(</span><span class="n">someObject</span><span class="p">,</span> <span class="n">someRange</span><span class="p">)</span> 414</pre></div> 415</div> 416</div></blockquote> 417<p>This may be awkward and “unpythonic” at first, however this syntax is necessary 418to preserve the semantics of Objective-C message dispatch.</p> 419<p>A class declaration:</p> 420<blockquote> 421<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 422 2 423 3 424 4 425 5 426 6 427 7 428 8 429 9 43010 43111 43212 43313 43414 43515 43616 43717 43818 43919</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">MyClass</span> : <span class="nc">MySuperClass</span> 440<span class="p">{</span> 441 <span class="kt">id</span> <span class="n">anInstanceVariable</span><span class="p">;</span> 442 <span class="kt">int</span> <span class="n">anotherInstanceVariable</span><span class="p">;</span> 443<span class="p">}</span> 444 445<span class="c1">// A class method that returns an initialized instance of this class.</span> 446<span class="c1">// Similar to an implementation of __call__ on the metaclass.</span> 447<span class="o">+</span><span class="nl">instanceWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">anObject</span> <span class="nl">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">anInteger</span><span class="p">;</span> 448 449<span class="c1">// An instance method, the designated initializer for MyClass.</span> 450<span class="c1">// Similar to an implementation of __new__ on MyClass.</span> 451<span class="k">-</span><span class="nf">initWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span><span class="p">;</span> 452 453<span class="c1">// An accessor, instance variables (attributes) are in a separate</span> 454<span class="c1">// namespace and are considered "private" in Objective-C. Conventionally,</span> 455<span class="c1">// there is nothing similar to this in Python.</span> 456<span class="k">-</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nf">anotherInstanceVariable</span><span class="p">;</span> 457<span class="k">@end</span> 458</pre></div> 459</td></tr></table></div> 460</div></blockquote> 461<p>A class implementation:</p> 462<blockquote> 463<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 464 2 465 3 466 4 467 5 468 6 469 7 470 8 471 9 47210 47311 47412 47513 47614 47715 47816 47917 48018 48119 48220 48321 48422 48523 48624 48725 48826 48927 49028 49129 49230 49331 49432 49533 49634 49735 49836 49937 50038 50139 50240 50341 50442 50543 50644 50745 50846 50947 51048 51149 51250 51351 51452 51553 51654 51755 51856 51957 52058 52159 52260 52361 52462 52563 52664 52765 52866 52967 53068 53169 53270 53371 53472 53573 53674 53775 53876 53977 54078 54179 54280 54381 54482 54583 54684 54785 54886 54987 55088 55189</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">@implementation</span> <span class="nc">MyClass</span> 552 553<span class="c1">// Note that a type is not declared for the return value. Undeclared types</span> 554<span class="c1">// are assumed to be "id", which means any kind of instance.</span> 555<span class="k">+</span><span class="nf">instanceWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span> 556<span class="p">{</span> 557 <span class="c1">// 1. Create an instance of MyClass.</span> 558 <span class="c1">// 2. Initialize it with its designated initializer</span> 559 <span class="c1">// "initWithObject:andInteger:".</span> 560 <span class="c1">// 3. Autorelease it, so that it does not leak memory.</span> 561 <span class="c1">// 4. Return the new instance.</span> 562 <span class="c1">//</span> 563 <span class="c1">// NOTE:</span> 564 <span class="c1">// By convention,initializers (such as +new, -init, -copy)</span> 565 <span class="c1">// are the only methods that should return retained objects.</span> 566 <span class="c1">//</span> 567 <span class="c1">// NOTE:</span> 568 <span class="c1">// Since this is a class method, "self" refers to the class!</span> 569 <span class="c1">//</span> 570 <span class="c1">// Very roughly similar to:</span> 571 <span class="c1">// return self.__new__(anObject, anInteger)</span> 572 <span class="k">return</span> <span class="p">[[[</span><span class="n">self</span> <span class="n">alloc</span><span class="p">]</span> <span class="nl">initWithObject:</span><span class="n">anObject</span> <span class="nl">andInteger:</span><span class="n">anInteger</span><span class="p">]</span> <span class="n">autorelease</span><span class="p">];</span> 573<span class="p">}</span> 574 575<span class="c1">// Note that a type is not declared for the return value. Undeclared types</span> 576<span class="c1">// are assumed to be "id", which means any kind of instance.</span> 577<span class="k">-</span><span class="nf">initWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span> 578<span class="p">{</span> 579 <span class="c1">// Call the designated initializer of the superclass.</span> 580 <span class="c1">// Similar to:</span> 581 <span class="c1">// self = super(MyClass, self).__new__()</span> 582 <span class="n">self</span> <span class="o">=</span> <span class="p">[</span><span class="n">super</span> <span class="n">init</span><span class="p">];</span> 583 584 <span class="c1">// Bail if initialization of the superclass failed.</span> 585 <span class="c1">// Similar to:</span> 586 <span class="c1">// if self is None:</span> 587 <span class="c1">// return None</span> 588 <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">self</span><span class="p">)</span> <span class="p">{</span> 589 <span class="k">return</span> <span class="nb">nil</span><span class="p">;</span> 590 <span class="p">}</span> 591 592 <span class="c1">// Set the instance variable (attribute). The argument must be</span> 593 <span class="c1">// retained, since it will persist as long as the instance does.</span> 594 <span class="c1">// Similar to:</span> 595 <span class="c1">// # Reference counting is automatic in Python</span> 596 <span class="c1">// self.anInstanceVariable = anObject</span> 597 <span class="n">anInstanceVariable</span> <span class="o">=</span> <span class="p">[</span><span class="n">anObject</span> <span class="n">retain</span><span class="p">];</span> 598 599 <span class="c1">// Set the other instance variable. Note that since anInteger is</span> 600 <span class="c1">// a primitive "C" type, not an object, no reference counting takes</span> 601 <span class="c1">// place.</span> 602 <span class="c1">// Similar to:</span> 603 <span class="c1">// # Everything is an object in Python</span> 604 <span class="c1">// self.anotherInstanceVariable = anInteger</span> 605 <span class="n">anotherInstanceVariable</span> <span class="o">=</span> <span class="n">anInteger</span><span class="p">;</span> 606 607 <span class="c1">// Like __new__ in Python, initializers in Objective-C must</span> 608 <span class="c1">// explicitly return self. Note that this is different from</span> 609 <span class="c1">// __init__.</span> 610 <span class="c1">// Similar to:</span> 611 <span class="c1">// return self</span> 612 <span class="k">return</span> <span class="n">self</span><span class="p">;</span> 613<span class="p">}</span> 614 615 616<span class="c1">// an accessor, instance variables (attributes) are in a separate</span> 617<span class="c1">// namespace and are considered "private"</span> 618<span class="k">-</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nf">anotherInstanceVariable</span> 619<span class="p">{</span> 620 <span class="k">return</span> <span class="n">anotherInstanceVariable</span><span class="p">;</span> 621<span class="p">}</span> 622 623<span class="c1">// Since objects were retained as instance variables on this object,</span> 624<span class="c1">// they must be freed when the object is. This is similar to an</span> 625<span class="c1">// implementation of __del__ in Python. Since Objective-C has no</span> 626<span class="c1">// cyclic garbage collection, this isn't discouraged like it is in</span> 627<span class="c1">// Python.</span> 628<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">dealloc</span> 629<span class="p">{</span> 630 <span class="c1">// Very roughly similar to:</span> 631 <span class="c1">// del self.instanceVariable</span> 632 <span class="p">[</span><span class="n">instanceVariable</span> <span class="n">release</span><span class="p">];</span> 633 634 <span class="c1">// Very roughly similar to:</span> 635 <span class="c1">// super(MyClass, self).__del__()</span> 636 <span class="p">[</span><span class="n">super</span> <span class="n">dealloc</span><span class="p">];</span> 637<span class="p">}</span> 638 639<span class="k">@end</span> 640</pre></div> 641</td></tr></table></div> 642</div></blockquote> 643<p>Objective-C also features exceptions, but they are typically only used for 644disaster recovery, not error handling, so you will not encounter them very 645often. Read <a class="reference external" href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to 646know more about exceptions in Objective-C.</p> 647<p>One thing to keep in mind when translating Objective-C snippets to Python is 648that any message can be sent to <tt class="docutils literal"><span class="pre">nil</span></tt>, and the return value of that message 649will be <tt class="docutils literal"><span class="pre">nil</span></tt>. PyObjC translates <tt class="docutils literal"><span class="pre">nil</span></tt> to <tt class="docutils literal"><span class="pre">None</span></tt> when crossing the 650bridge, so any such attempt will raise an <tt class="docutils literal"><span class="pre">AttributeError</span></tt>.</p> 651<p>For more information about Objective-C see:</p> 652<ul class="simple"> 653<li><a class="reference external" href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a class="reference external" href="http://www.apple.com/">Apple</a>.</li> 654</ul> 655</div> 656<div class="section" id="overview-of-the-bridge"> 657<h2>Overview of the bridge<a class="headerlink" href="#overview-of-the-bridge" title="Permalink to this headline">¶</a></h2> 658<div class="section" id="classes"> 659<h3>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3> 660<p>Objective-C classes are visible as (new-style) Python classes and can be 661subclassed just like normal Python classes. All the usual introspection 662mechanisms work as well, as do <tt class="docutils literal"><span class="pre">__slots__</span></tt> and descriptors. The major 663differences between normal Python classes and Objective-C classes are the way 664that instances are created and initialized, and the fact that Objective-C 665selectors look strange when translated to Python methods.</p> 666<p>Multiple inheritance may be used when subclassing an Objective-C class, so 667long as the Objective-C class is the first base class and there is only one 668Objective-C base class. The Objective-C runtime does not support multiple 669inheritance. These mix-in classes should not contain different 670implementations for Objective-C methods. To achieve this behavior, Categories 671should be used instead.</p> 672<p>Another thing to keep in mind is that the names of Objective-C classes must 673be globally unique per process, including across Python modules. That is, 674it is <em>not</em> possible to have two Python modules that define a class with the 675same name. It is conventional to choose class names with a short prefix that 676uniquely identify your project or company. For example, Apple uses <tt class="docutils literal"><span class="pre">NS</span></tt> 677as the prefix for all classes in the <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a>. Note that the <tt class="docutils literal"><span class="pre">NS</span></tt> 678prefix made much more sense when it was called NeXTstep, but persists to this 679day for compatibility reasons.</p> 680<p>As described in <a class="reference internal" href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 681objects is a two-stage process. To initialize objects, first call a 682class method to allocate the memory (typically <tt class="docutils literal"><span class="pre">alloc</span></tt>), and then call an 683initializer (typically starts with <tt class="docutils literal"><span class="pre">init</span></tt>). Some classes have class methods 684which perform this behind the scenes, especially classes that create cached, 685immutable, or singleton instances.</p> 686</div> 687<div class="section" id="messages-and-functions"> 688<h3>Messages and Functions<a class="headerlink" href="#messages-and-functions" title="Permalink to this headline">¶</a></h3> 689<p>Objective-C methods are bridged to Python methods. Because Objective-C 690message dispatch syntax can not be translated directly to Python, a few 691simple translations must take place. The rules for these translations are:</p> 692<ol class="arabic"> 693<li><p class="first">Replace all colons in the selector with underscores:</p> 694<blockquote> 695<div><ul class="simple"> 696<li><tt class="docutils literal"><span class="pre">someMethod:withFoo:andBar:</span></tt> translates to <tt class="docutils literal"><span class="pre">someMethod_withFoo_andBar_</span></tt></li> 697</ul> 698</div></blockquote> 699</li> 700<li><p class="first">If the result <tt class="docutils literal"><span class="pre">class</span></tt> or <tt class="docutils literal"><span class="pre">raise</span></tt> (Python keywords), append two underscores:</p> 701<blockquote> 702<div><ul class="simple"> 703<li><tt class="docutils literal"><span class="pre">class</span></tt> translates to <tt class="docutils literal"><span class="pre">class__</span></tt></li> 704<li><tt class="docutils literal"><span class="pre">raise</span></tt> translates to <tt class="docutils literal"><span class="pre">raise__</span></tt></li> 705</ul> 706</div></blockquote> 707</li> 708<li><p class="first">Use this translated selector as a normal Python method. 709The arguments must be passed in the same order, and the number of 710arguments passed will normally be equal to the number of underscores 711in the method name; exceptions to this rule and the behavior of “result” 712are mentioned below.</p> 713<div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">someObject</span> <span class="nl">someMethod:</span><span class="n">firstArg</span> <span class="nl">withFoo:</span><span class="n">foo</span> <span class="nl">andBar:</span><span class="n">bar</span><span class="p">];</span> 714</pre></div> 715</td></tr></table></div> 716<p>translates to</p> 717<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="n">someObject</span><span class="o">.</span><span class="n">someMethod_withFoo_andBar_</span><span class="p">(</span><span class="n">firstArg</span><span class="p">,</span> <span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="p">)</span> 718</pre></div> 719</td></tr></table></div> 720</li> 721</ol> 722<p>Note that it is currently not possible to support methods with a variable 723number of arguments from Python. These selectors must be wrapped by 724custom Objective-C code in order to be accessible by Python.</p> 725<p>Wrapped/bridged methods (and functions) have the same number of arguments 726as the corresponding Objective-C method or function, unless otherwise noted 727in the documentation (<a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> for 728Cocoa on Mac OS X).</p> 729<p>Most methods or functions that take or return pointers to values will be an 730exception to this rule if it is callable from Python at all. In Objective-C 731terminology, there are three kinds of pointers that can be used in a method:</p> 732<dl class="docutils"> 733<dt><tt class="docutils literal"><span class="pre">in</span></tt>:</dt> 734<dd><p class="first">Used to pass data by reference to the function. This is not a special 735case from Python.</p> 736<p class="last">Instead of a regular value you may also pass in the value <tt class="docutils literal"><span class="pre">objc.NULL</span></tt>, 737when you do that the Objective-C method will receive a NULL pointer instead 738of a pointer to your value.</p> 739</dd> 740<dt><tt class="docutils literal"><span class="pre">out</span></tt>:</dt> 741<dd><p class="first">Used to pass data from the function (e.g. an additional return value).</p> 742<p class="last">Pass in either <tt class="docutils literal"><span class="pre">None</span></tt> or <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> for output arguments. 743to the method. If the value is <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> the Objective-C code will 744receive a NULL pointer for this argument, otherwise it will receive a 745valid pointer.</p> 746</dd> 747<dt><tt class="docutils literal"><span class="pre">inout</span></tt>:</dt> 748<dd><p class="first">A combination of in and out (a value is passed by reference, and mutated 749upon return). Unlike <tt class="docutils literal"><span class="pre">out</span></tt>, these arguments remain in the argument list, 750and thus do not have an effect on the number of arguments a method expects. 751See below for notes on how <tt class="docutils literal"><span class="pre">inout</span></tt> arguments change the return value.</p> 752<p class="last">Instead of a regular value you may also pass in the value <tt class="docutils literal"><span class="pre">objc.NULL</span></tt>, 753when you do that the Objective-C method will receive a NULL pointer instead 754of a pointer to your value.</p> 755</dd> 756</dl> 757<p>In order to determine what the return value of such an exceptional message will 758look like, you must “make a list” of the return values with the following rules:</p> 759<ol class="arabic simple"> 760<li>If the return type of the method or function is not <tt class="docutils literal"><span class="pre">void</span></tt>, add it to the 761list.</li> 762<li>For each argument in the method or function, add it to the list if it is 763<tt class="docutils literal"><span class="pre">out</span></tt> or <tt class="docutils literal"><span class="pre">inout</span></tt>. When <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> was used as the argument value it 764will also be used as the result value.</li> 765</ol> 766<p>After creating this list, you will have one of three cases:</p> 767<dl class="docutils"> 768<dt>Empty:</dt> 769<dd>The return value of this call will always be <tt class="docutils literal"><span class="pre">None</span></tt>.</dd> 770<dt>One element:</dt> 771<dd>The return value of this call will correspond to the one element of the list.</dd> 772<dt>More than one element:</dt> 773<dd>The return value of this call will be a tuple in the same order as the list.</dd> 774</dl> 775<p>The rules for pass by reference arguments may look quite complicated, but 776it turns out this is very straightforward when working with them.</p> 777<p>As an example of a method with two output arguments, <tt class="docutils literal"><span class="pre">NSMatrix</span></tt> implements a 778selector named <tt class="docutils literal"><span class="pre">getNumberOfRows:columns:</span></tt> with the following signature:</p> 779<blockquote> 780<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">getNumberOfRows:</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="p">)</span><span class="nv">rowCount</span> <span class="nf">columns:</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="p">)</span><span class="nv">columnCount</span> 781</pre></div> 782</div> 783</div></blockquote> 784<p>This method is used from Python like this:</p> 785<blockquote> 786<div><div class="highlight-python"><div class="highlight"><pre><span class="n">rowCount</span><span class="p">,</span> <span class="n">columnCount</span> <span class="o">=</span> <span class="n">matrix</span><span class="o">.</span><span class="n">getNumberOfRows_columns_</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span> 787</pre></div> 788</div> 789</div></blockquote> 790<p>When a function or method has an array of values and the length of that array 791as arguments, <tt class="docutils literal"><span class="pre">None</span></tt> may be passed as the length to specify that the length 792of the given sequence should be used.</p> 793<p>Python’s <tt class="docutils literal"><span class="pre">array.array</span></tt> type may be used to represent a C array if the 794typestr and size match what is expected by the selector. Numeric, numarray, 795and other third party array types are not supported at the moment.</p> 796<p>When defining methods in an Objective-C subclass, the bridge must provide 797type signatures for each method to the Objective-C runtime. The default 798type signature is for all arguments as well as the return value to be objects (just 799like with normal Python methods). If there is no return statement in the implementation, 800then the return value will be void. The bridge will automatically pick a better 801signature when it has more information available. Specifically, a method overrides 802an existing method, the bridge will assume you want to use the same 803method signature. Furthermore, if the method is implemented in an (informal) 804protocol known to the bridge it will use the signature from the corresponding 805method in that signature.</p> 806<p>The end result is that it is rarely necessary to explicitly add information about 807the signature of methods. For the two most common cases where this is necessary, 808we have provided convenience decorators (used like <tt class="docutils literal"><span class="pre">staticmethod</span></tt> or 809<tt class="docutils literal"><span class="pre">classmethod</span></tt>):</p> 810<dl class="docutils"> 811<dt><tt class="docutils literal"><span class="pre">objc.accessor</span></tt>:</dt> 812<dd>Use this to wrap a <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a> or <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> compliant 813accessor.</dd> 814<dt><tt class="docutils literal"><span class="pre">PyObjCTools.AppHelper.endSheetMethod</span></tt>:</dt> 815<dd>Use this to wrap the implementation of a sheet’s “didEndSelector” callback.</dd> 816</dl> 817<p>For complete control of the mapping to Objective-C you can use the function 818<tt class="docutils literal"><span class="pre">objc.selector</span></tt> to create custom descriptors. See the documentation of the 819<tt class="docutils literal"><span class="pre">objc</span></tt> module for the arguments you can use with this function. It is 820normally used like this:</p> 821<blockquote> 822<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 8232 8243 8254 8265 8276 8287</pre></div></td><td class="code"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">MyObject</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span> 829 830 <span class="c"># -(void)someMethod:(float)arg</span> 831 <span class="k">def</span> <span class="nf">someMethod_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span> 832 <span class="k">pass</span> 833 834 <span class="n">someMethod_</span> <span class="o">=</span> <span class="n">objc</span><span class="o">.</span><span class="n">selector</span><span class="p">(</span><span class="n">someMethod_</span><span class="p">,</span> <span class="n">signature</span><span class="o">=</span><span class="s">'v@:f'</span><span class="p">)</span> 835</pre></div> 836</td></tr></table></div> 837</div></blockquote> 838<p>In Python 2.4 or later there is a decorator for this purpose:</p> 839<blockquote> 840<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 8412 8423 8434 8445</pre></div></td><td class="code"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">MyObject</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span> 845 846 <span class="nd">@objc.signature</span><span class="p">(</span><span class="s">'v@:f'</span><span class="p">)</span> 847 <span class="k">def</span> <span class="nf">someMethod_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span> 848 <span class="k">pass</span> 849</pre></div> 850</td></tr></table></div> 851</div></blockquote> 852</div> 853<div class="section" id="reference-counting"> 854<h3>Reference counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h3> 855<p>The <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a>, and most (if not all) other class libraries for 856Objective-C use explicit reference counting to manage memory. The methods 857<tt class="docutils literal"><span class="pre">retain</span></tt>, <tt class="docutils literal"><span class="pre">release</span></tt> and <tt class="docutils literal"><span class="pre">autorelease</span></tt> are used to manage these 858reference counts. You won’t have to manage reference counts in Python, the 859bridge does all that work for you (but see <a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes 860on Mac OS X</a> for some advanced issues).</p> 861<p>The only reasons reference counts are mentioned at all are to tell you about 862ignoring them, and more importantly to introduce you to some issues w.r.t. 863reference counting.</p> 864<p>It turns out that Cocoa uses a primitive form of <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a>. Those 865are not true <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a> as in Python, but use-cases where an object 866stores a reference to another object without increasing the reference count 867for that other object. The bridge cannot solve the issues this introduces 868for you, which means that you get hard crashes when you’re not careful when 869dealing with those <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a>.</p> 870<p>The basic rule to deal with weak references is: make sure objects stays 871alive as long as someone might have a weak reference to them. Due to the way 872the bridge works, this means that you must make sure that you don’t create 873weak references from Objective-C to a plain Python object. The Python 874object stays alive, but the proxy object as seen by the Objective-C code is 875actually an autoreleased object that will be cleaned up unless the Objective-C 876code increases its reference count.</p> 877<p>The document <a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> contains 878information about classes that work with weak references. The most important 879are notification centers and <tt class="docutils literal"><span class="pre">NSOutlineView</span></tt>, to be exact: the outline view 880stores weak references to the objects return by the method 881<tt class="docutils literal"><span class="pre">outlineView:child:ofItem:</span></tt> of its data source. The easiest way to avoid 882crashes with outline views is to make sure that you model for the view uses 883subclasses of <tt class="docutils literal"><span class="pre">NSObject</span></tt> to represent the nodes in the outline view.</p> 884<p>Another gotcha is that <tt class="docutils literal"><span class="pre">obj.setDelegate_()</span></tt> often does <em>not</em> retain the 885delegate, so a reference should be maintained elsewhere.</p> 886</div> 887<div class="section" id="protocols"> 888<h3>Protocols<a class="headerlink" href="#protocols" title="Permalink to this headline">¶</a></h3> 889<p>Cocoa defines a number of formal and informal protocols that specify methods 890that should be implemented by a class if it is to be used in a specific role, 891such as the data source for an <tt class="docutils literal"><span class="pre">NSTableView</span></tt>.</p> 892<p>Those protocols are represented by instances of <tt class="docutils literal"><span class="pre">objc.informal_protocol</span></tt>, 893and <tt class="docutils literal"><span class="pre">objc.formal_protocol</span></tt>. The only ones that have to care about these 894objects are the maintainers of wrappers around Objective-C frameworks: they 895have to keep these protocol wrappers up-to-date.</p> 896<p>PyObjC will automatically use the information in the <tt class="docutils literal"><span class="pre">informal_protocol</span></tt> 897objects to add the right method signatures to methods, and to warn about 898classes that partially implement a protocol.</p> 899<p>See <a class="reference external" href="protocols.html">PyObjC protocol support</a> for more information.</p> 900</div> 901<div class="section" id="cocoa-bindings"> 902<h3>Cocoa Bindings<a class="headerlink" href="#cocoa-bindings" title="Permalink to this headline">¶</a></h3> 903<p>In Mac OS X 10.3 Apple introduced <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaBindings/CocoaBindings.html">Cocoa Bindings</a>, a method to make it easier 904to create and use <em>Controller</em> objects using <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> and 905<a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a>. In order to create accessors compatible with this, you 906must use <tt class="docutils literal"><span class="pre">objc.accessor</span></tt> to create an appropriate selector descriptor.</p> 907<p>PyObjC automaticly emits the right <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> notifications when 908you set attributes on an Objective-C class. This is however not supported for 909pure python objects. You should therefore use <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> instances 910instead of Python lists for instance variables that will be observed and contain 911a sequence of values (and simularly for <tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt> instead of 912<tt class="docutils literal"><span class="pre">dict</span></tt>).</p> 913<p>NOTE: Key-Value Observing is not supported for “pure” python objects, that 914is instances of classes that don’t inherit from <tt class="docutils literal"><span class="pre">NSObject</span></tt>. Adding such 915support is not possible adding a KVO-like interface to the Python interpreter.</p> 916</div> 917<div class="section" id="categories"> 918<h3>Categories<a class="headerlink" href="#categories" title="Permalink to this headline">¶</a></h3> 919<p>Objective-C has a mechanism for modularize a class definition, it is possible 920to add methods to an existing class in a separate compilation unit and even 921a separate library. This mechanism is named categories and is used to enhance 922existing classes, for splitting classes in several parts and to document 923informal protocols.</p> 924<p>An example of a category definition:</p> 925<blockquote> 926<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 9272 9283</pre></div></td><td class="code"><div class="highlight"><pre> <span class="k">@interface</span> <span class="nc">NSObject</span> <span class="nl">(MyCategory)</span> 929 <span class="o">-</span> <span class="p">(</span><span class="n">NSSize</span><span class="p">)</span><span class="n">objectFootprint</span><span class="p">;</span> 930 <span class="k">@end</span> 931</pre></div> 932</td></tr></table></div> 933</div></blockquote> 934<p>This declares an additional category on <tt class="docutils literal"><span class="pre">NSObject</span></tt>. This category contains 935a single method.</p> 936<p>The function <tt class="docutils literal"><span class="pre">objc.classAddMethods</span></tt> can be used to get the same effect in 937Python:</p> 938<blockquote> 939<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 9402 9413 9424</pre></div></td><td class="code"><div class="highlight"><pre> <span class="k">def</span> <span class="nf">objectFootprint</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> 943 <span class="k">pass</span> 944 945 <span class="n">objc</span><span class="o">.</span><span class="n">classAddMethods</span><span class="p">(</span><span class="n">NSObject</span><span class="p">,</span> <span class="p">[</span><span class="n">objectFootprint</span><span class="p">])</span> 946</pre></div> 947</td></tr></table></div> 948</div></blockquote> 949<p>This is not very clear, PyObjC therefore also provides the following 950mechanism, implemented on top of <tt class="docutils literal"><span class="pre">objc.classAddMethods</span></tt>:</p> 951<blockquote> 952<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 9532 9543</pre></div></td><td class="code"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">NSObject</span><span class="p">(</span><span class="n">objc</span><span class="o">.</span><span class="n">Category</span><span class="p">(</span><span class="n">NSObject</span><span class="p">)):</span> 955 <span class="k">def</span> <span class="nf">objectFootprint</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> 956 <span class="k">pass</span> 957</pre></div> 958</td></tr></table></div> 959</div></blockquote> 960<p>To make it clear that <tt class="docutils literal"><span class="pre">objc.Category</span></tt> performs a special task the name in 961the class definition must be the same as the <tt class="docutils literal"><span class="pre">__name__</span></tt> of the argument 962to <tt class="docutils literal"><span class="pre">objc.Category</span></tt>.</p> 963</div> 964</div> 965<div class="section" id="accessing-python-objects-from-objective-c"> 966<h2>Accessing Python objects from Objective-C<a class="headerlink" href="#accessing-python-objects-from-objective-c" title="Permalink to this headline">¶</a></h2> 967<p>All Python objects can be accessed from Objective-C through proxy objects. 968Whenever a Python object crosses the line from Python to Objective-C a proxy 969object is created (of class <tt class="docutils literal"><span class="pre">OC_PythonObject</span></tt>, a subclass of <tt class="docutils literal"><span class="pre">NSProxy</span></tt>). 970This proxy object will forward all method calls from Objective-C to Python, and 971will return the results back to Objective-C.</p> 972<p>See the section ‘Method protocol’ for a description of how PyObjC translates 973between Python and Objective-C method calls.</p> 974<p>A number of Python types/classes are treated specially:</p> 975<ul class="simple"> 976<li>Python numbers (<tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>) are translated into 977<tt class="docutils literal"><span class="pre">NSNumber</span></tt> instances. Their identity is not preserved across the bridge.</li> 978<li>Python <tt class="docutils literal"><span class="pre">str</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonString</span></tt>, a subclass of 979<tt class="docutils literal"><span class="pre">NSString</span></tt>. A Python <tt class="docutils literal"><span class="pre">str</span></tt> may be used anywhere a <tt class="docutils literal"><span class="pre">NSString</span></tt> is 980expected, but <tt class="docutils literal"><span class="pre">unicode</span></tt> should be used whenever possible. 981<tt class="docutils literal"><span class="pre">OC_PythonString</span></tt> will use the default encoding of <tt class="docutils literal"><span class="pre">NSString</span></tt>, which is 982normally MacRoman but could be something else.</li> 983<li>Python <tt class="docutils literal"><span class="pre">unicode</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonUnicode</span></tt>, a subclass of 984<tt class="docutils literal"><span class="pre">NSString</span></tt>. A Python <tt class="docutils literal"><span class="pre">unicode</span></tt> may be used anywhere a <tt class="docutils literal"><span class="pre">NSString</span></tt> 985is expected.</li> 986<li>Python <tt class="docutils literal"><span class="pre">dict</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonDictionary</span></tt>, a subclass of 987<tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt>. A Python <tt class="docutils literal"><span class="pre">dict</span></tt> may be used anywhere 988an <tt class="docutils literal"><span class="pre">NSDictionary</span></tt> is expected.</li> 989<li>Python <tt class="docutils literal"><span class="pre">list</span></tt> and <tt class="docutils literal"><span class="pre">tuple</span></tt> are proxied using <tt class="docutils literal"><span class="pre">OC_PythonArray</span></tt>, a 990subclass of <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>. Python <tt class="docutils literal"><span class="pre">list</span></tt> or <tt class="docutils literal"><span class="pre">tuple</span></tt> objects 991may be used anywhere an <tt class="docutils literal"><span class="pre">NSArray</span></tt> is expected.</li> 992<li>Python objects that implement the Python buffer API, except for <tt class="docutils literal"><span class="pre">str</span></tt> 993and <tt class="docutils literal"><span class="pre">unicode</span></tt>, are proxied using <tt class="docutils literal"><span class="pre">OC_PythonData</span></tt>, a <tt class="docutils literal"><span class="pre">NSData</span></tt> subclass. 994Objects that implement the Python buffer API such as <tt class="docutils literal"><span class="pre">buffer</span></tt>, 995<tt class="docutils literal"><span class="pre">array.array</span></tt>, <tt class="docutils literal"><span class="pre">mmap.mmap</span></tt>, etc. may be used anywhere a <tt class="docutils literal"><span class="pre">NSData</span></tt> is 996expected.</li> 997</ul> 998<p>These special cases allow for more transparent bridging between Python and 999Objective-C.</p> 1000</div> 1001<div class="section" id="cocoa-for-python-programmers"> 1002<h2>Cocoa for Python programmers<a class="headerlink" href="#cocoa-for-python-programmers" title="Permalink to this headline">¶</a></h2> 1003<p>Cocoa frameworks are mapped onto Python packages with the same name; that is 1004the classes, constants and functions from the AppKit framework are available 1005after you import <tt class="docutils literal"><span class="pre">AppKit</span></tt> in your Python script.</p> 1006<p>These helper modules contain <em>only</em> functions, constants and classes that 1007wrap items in the corresponding framework. All utility functions and classes 1008are located in the <tt class="docutils literal"><span class="pre">PyObjCTools</span></tt> package and <tt class="docutils literal"><span class="pre">objc</span></tt> module. Note that it 1009is possible to use <tt class="docutils literal"><span class="pre">pydoc</span></tt> (or the <tt class="docutils literal"><span class="pre">help()</span></tt>) function with the framework 1010wrappers, but that this is not very useful for the entire module due to the 1011size of these modules.</p> 1012<p>This makes it easier to find documentation for an item: if you import it 1013from the wrapper module for an Objective-C framework the documentation for 1014that item can be found in the documentation for the framework; otherwise the 1015item is documented in the PyObjC documentation.</p> 1016<p>The module <tt class="docutils literal"><span class="pre">PyObjCTools.NibClassBuilder</span></tt> can be used to make working with 1017NIB files more convenient. This module can be used to extract information 1018about classes from NIB files, both as a standalone tool generating source code 1019and during runtime. See the online documentation for this module for more 1020information.</p> 1021<p>PyObjC includes a number of examples that show how to use Cocoa from 1022Python. The <a class="reference external" href="/Examples/00ReadMe.html">PyObjC Example index</a> contains an overview of those examples.</p> 1023<p>More information on Cocoa programming can be found at:</p> 1024<ul class="simple"> 1025<li><a class="reference external" href="https://developer.apple.com/library/mac/navigation/index.html#section=Frameworks&topic=Cocoa%20Layer">Cocoa documentation at the Apple developer website</a></li> 1026<li><a class="reference external" href="https://developer.apple.com/library/mac/navigation/index.html#section=Resource%20Types&topic=Sample%20Code">Cocoa examples at the Apple developer website</a></li> 1027<li>Your local bookstore or library</li> 1028</ul> 1029</div> 1030<div class="section" id="notes-on-specific-tasks"> 1031<h2>Notes on specific tasks<a class="headerlink" href="#notes-on-specific-tasks" title="Permalink to this headline">¶</a></h2> 1032<div class="section" id="working-with-threads"> 1033<h3>Working with threads<a class="headerlink" href="#working-with-threads" title="Permalink to this headline">¶</a></h3> 1034<p>Most of Cocoa, and thus PyObjC, requires an <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> in order to function 1035properly. PyObjC does this automatically on the first thread it is imported from, 1036but other threads will require explicit <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> management. The following 1037practice for working with <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> is recommended:</p> 1038<blockquote> 1039<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 10402 10413</pre></div></td><td class="code"><div class="highlight"><pre> <span class="n">pool</span> <span class="o">=</span> <span class="n">NSAutoreleasePool</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> 1042 <span class="o">...</span> 1043 <span class="k">del</span> <span class="n">pool</span> 1044</pre></div> 1045</td></tr></table></div> 1046</div></blockquote> 1047<p>Typically this will be done at the beginning and end of the thread. It is important 1048to use <tt class="docutils literal"><span class="pre">del</span></tt> before rebinding the <tt class="docutils literal"><span class="pre">pool</span></tt> local to another <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> 1049instance, otherwise it will not have the intended effect.</p> 1050<p>For long running threads and tight loops, it can also be useful to use this pattern 1051in the body of the loop in order to optimize memory usage. For example, <tt class="docutils literal"><span class="pre">NSRunLoop</span></tt> 1052will be create a new <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> at the beginning of each run loop iteration 1053and release it at the end.</p> 1054</div> 1055<div class="section" id="finalizers"> 1056<h3>Finalizers<a class="headerlink" href="#finalizers" title="Permalink to this headline">¶</a></h3> 1057<p>In normal Python, there are two methods for writing finalizers: implementing 1058<tt class="docutils literal"><span class="pre">__del__</span></tt>, and using <tt class="docutils literal"><span class="pre">weakref.ref</span></tt> callbacks. Generally, <tt class="docutils literal"><span class="pre">__del___</span></tt> is 1059discouraged as it does not allow the object to participate in cyclic garbage 1060collection and create uncollectible garbage if not implemented properly. 1061<tt class="docutils literal"><span class="pre">weakref.ref</span></tt> callbacks avoid this restriction as they do not provide a real 1062reference to the object.</p> 1063<p>In Objective-C, there is no cyclic garbage collection, so all Objective-C 1064objects (including subclasses from Python) are already subject to these 1065restrictions. When subclassing an Objective-C class, you may implement 1066<tt class="docutils literal"><span class="pre">dealloc</span></tt> or <tt class="docutils literal"><span class="pre">__del__</span></tt>. If you implement <tt class="docutils literal"><span class="pre">dealloc</span></tt>, ensure that 1067you call the super <tt class="docutils literal"><span class="pre">dealloc</span></tt> at the end. If you implement both 1068<tt class="docutils literal"><span class="pre">__del__</span></tt> and <tt class="docutils literal"><span class="pre">dealloc</span></tt>, the order in which they are called is 1069undefined.</p> 1070<p>It is not currently possible to create a <tt class="docutils literal"><span class="pre">weakref.ref</span></tt> for any Objective-C 1071object. It is probably technically possible to do, but tricky, so it 1072may eventually be implemented in a future version of PyObjC (especially 1073if a future Objective-C runtime supports it).</p> 1074</div> 1075<div class="section" id="copying"> 1076<h3>Copying<a class="headerlink" href="#copying" title="Permalink to this headline">¶</a></h3> 1077<p>It is possible for a Python subclass of an Objective-C class to implement 1078the <tt class="docutils literal"><span class="pre">NSCopying</span></tt> protocol. Some care must be taken when the superclass 1079already implements the protocol.</p> 1080<p>Some <tt class="docutils literal"><span class="pre">NSCopying</span></tt> compliant Objective-C classes copy the template object 1081manually. In those cases the Python subclass must also copy the additional 1082ivars manually.</p> 1083<p>Other <tt class="docutils literal"><span class="pre">NSCopying</span></tt> compliant Objective-C classes use a convenience function 1084that creates a shallow copy of the object and all of its ivars. In those 1085cases the Python subclass will not have to explicitly copy all of the ivars. 1086However, the ivars in the copy will refer to the same objects as the original, 1087and will thus share some state. As with shallow copies in Python, if any of 1088the ivars refer to mutable objects (<tt class="docutils literal"><span class="pre">list</span></tt>, <tt class="docutils literal"><span class="pre">dict</span></tt>, etc.) it may be 1089desirable to explicitly make shallow or deep copies of the mutable ivars.</p> 1090<p>NOTE: PyObjC might introduce a helper class when you inherit from a class 1091that implements <tt class="docutils literal"><span class="pre">NSCopying</span></tt> as an internal implementation detail. 1092External code should not rely on the existance of this class.</p> 1093<p>NOTE2: <tt class="docutils literal"><span class="pre">SomeClass.copyWithZone_</span></tt> should not be implemented unless a 1094superclass already implements <tt class="docutils literal"><span class="pre">copyWithZone:</span></tt>, or else the behavior 1095will be undefined (memory corruption, crashes, etc.).</p> 1096</div> 1097</div> 1098<div class="section" id="building-applications"> 1099<h2>Building applications<a class="headerlink" href="#building-applications" title="Permalink to this headline">¶</a></h2> 1100<p>There are two different recommended ways to build applications with PyObjC.</p> 1101<div class="section" id="py2app-setup-py"> 1102<h3>“py2app” : setup.py<a class="headerlink" href="#py2app-setup-py" title="Permalink to this headline">¶</a></h3> 1103<p>The PyObjC installer includes a copy of the <tt class="docutils literal"><span class="pre">py2app</span></tt> package. This package 1104offers a way to build distutils scripts for building (standalone) 1105applications and plugin bundles.</p> 1106<p>An example <tt class="docutils literal"><span class="pre">setup.py</span></tt> script:</p> 1107<blockquote> 1108<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 11092 11103 11114 11125 11136 11147</pre></div></td><td class="code"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span> 1115<span class="kn">import</span> <span class="nn">py2app</span> 1116 1117<span class="n">setup</span><span class="p">(</span> 1118 <span class="n">app</span> <span class="o">=</span> <span class="p">[</span><span class="s">"iClass.py"</span><span class="p">],</span> 1119 <span class="n">data_files</span> <span class="o">=</span> <span class="p">[</span><span class="s">"English.lproj"</span><span class="p">],</span> 1120<span class="p">)</span> 1121</pre></div> 1122</td></tr></table></div> 1123</div></blockquote> 1124<p>During development you typically invoke it from the command line like this:</p> 1125<blockquote> 1126<div><div class="highlight-sh"><div class="highlight"><pre><span class="nv">$ </span>python setup.py py2app -A 1127</pre></div> 1128</div> 1129</div></blockquote> 1130<p>This will build an application bundle in a folder named <tt class="docutils literal"><span class="pre">dist</span></tt> in the 1131current folder. The <tt class="docutils literal"><span class="pre">-A</span></tt> option tells <tt class="docutils literal"><span class="pre">py2app</span></tt> to add symbolic 1132links for data folders and files and an Alias to your main script, 1133allowing you quickly rebuild the application without doing a full dependency 1134scan, with the additional bonus that you can edit them without rebuild. To 1135build a standalone application, simply do not use the <tt class="docutils literal"><span class="pre">-A</span></tt> option. 1136Note that if you are using a version of Python shipped with your operating 1137system, it will not be included in the application. Otherwise, your 1138application will include stripped down version of the Python runtime that 1139you ran setup.py with.</p> 1140<p>For more information about <tt class="docutils literal"><span class="pre">py2app</span></tt> usage, read through some of the 1141<tt class="docutils literal"><span class="pre">setup.py</span></tt> scripts used by the examples in the <a class="reference external" href="/Examples/00ReadMe.txt">Examples</a> folder. 1142On any <tt class="docutils literal"><span class="pre">setup.py</span></tt> script that imports <tt class="docutils literal"><span class="pre">py2app</span></tt>, you can use the 1143following command to see the list of options:</p> 1144<blockquote> 1145<div><div class="highlight-sh"><div class="highlight"><pre><span class="nv">$ </span>python setup.py py2app --help 1146</pre></div> 1147</div> 1148</div></blockquote> 1149</div> 1150<div class="section" id="ide-approach-xcode"> 1151<h3>“IDE approach” : Xcode<a class="headerlink" href="#ide-approach-xcode" title="Permalink to this headline">¶</a></h3> 1152<p>PyObjC includes a number of Xcode templates that can be used to 1153develop applications, using the same underlying functionality that 1154is in py2app. These templates are used like any other Xcode template, 1155but there are some organizational rules about the template.</p> 1156<p>See <a class="reference external" href="Xcode-Templates.html">the documentation for the templates</a> for more details.</p> 1157</div> 1158</div> 1159</div> 1160 1161 1162 </div> 1163 </div> 1164 </div> 1165 <div class="sphinxsidebar"> 1166 <div class="sphinxsidebarwrapper"> 1167 <h3><a href="index.html">Table Of Contents</a></h3> 1168 <ul> 1169<li><a class="reference internal" href="#">An introduction to PyObjC</a><ul> 1170<li><a class="reference internal" href="#preface">Preface</a></li> 1171<li><a class="reference internal" href="#first-steps">First Steps</a><ul> 1172<li><a class="reference internal" href="#underscores-and-lots-of-them">Underscores, and lots of them</a></li> 1173<li><a class="reference internal" href="#two-phase-instantiation">Two-phase instantiation</a></li> 1174<li><a class="reference internal" href="#objective-c-uses-accessors-everywhere">Objective-C uses accessors everywhere</a></li> 1175</ul> 1176</li> 1177<li><a class="reference internal" href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></li> 1178<li><a class="reference internal" href="#overview-of-the-bridge">Overview of the bridge</a><ul> 1179<li><a class="reference internal" href="#classes">Classes</a></li> 1180<li><a class="reference internal" href="#messages-and-functions">Messages and Functions</a></li> 1181<li><a class="reference internal" href="#reference-counting">Reference counting</a></li> 1182<li><a class="reference internal" href="#protocols">Protocols</a></li> 1183<li><a class="reference internal" href="#cocoa-bindings">Cocoa Bindings</a></li> 1184<li><a class="reference internal" href="#categories">Categories</a></li> 1185</ul> 1186</li> 1187<li><a class="reference internal" href="#accessing-python-objects-from-objective-c">Accessing Python objects from Objective-C</a></li> 1188<li><a class="reference internal" href="#cocoa-for-python-programmers">Cocoa for Python programmers</a></li> 1189<li><a class="reference internal" href="#notes-on-specific-tasks">Notes on specific tasks</a><ul> 1190<li><a class="reference internal" href="#working-with-threads">Working with threads</a></li> 1191<li><a class="reference internal" href="#finalizers">Finalizers</a></li> 1192<li><a class="reference internal" href="#copying">Copying</a></li> 1193</ul> 1194</li> 1195<li><a class="reference internal" href="#building-applications">Building applications</a><ul> 1196<li><a class="reference internal" href="#py2app-setup-py">“py2app” : setup.py</a></li> 1197<li><a class="reference internal" href="#ide-approach-xcode">“IDE approach” : Xcode</a></li> 1198</ul> 1199</li> 1200</ul> 1201</li> 1202</ul> 1203 1204 <h4>Previous topic</h4> 1205 <p class="topless"><a href="index.html" 1206 title="previous chapter">Welcome to PyObjC-Core’s documentation!</a></p> 1207 <h4>Next topic</h4> 1208 <p class="topless"><a href="tutorials/index.html" 1209 title="next chapter">PyObjC Tutorials</a></p> 1210 <h3>This Page</h3> 1211 <ul class="this-page-menu"> 1212 <li><a href="_sources/intro.txt" 1213 rel="nofollow">Show Source</a></li> 1214 </ul> 1215<div id="searchbox" style="display: none"> 1216 <h3>Quick search</h3> 1217 <form class="search" action="search.html" method="get"> 1218 <input type="text" name="q" /> 1219 <input type="submit" value="Go" /> 1220 <input type="hidden" name="check_keywords" value="yes" /> 1221 <input type="hidden" name="area" value="default" /> 1222 </form> 1223 <p class="searchtip" style="font-size: 90%"> 1224 Enter search terms or a module, class or function name. 1225 </p> 1226</div> 1227<script type="text/javascript">$('#searchbox').show(0);</script> 1228 </div> 1229 </div> 1230 <div class="clearer"></div> 1231 </div> 1232 <div class="related"> 1233 <h3>Navigation</h3> 1234 <ul> 1235 <li class="right" style="margin-right: 10px"> 1236 <a href="genindex.html" title="General Index" 1237 >index</a></li> 1238 <li class="right" > 1239 <a href="py-modindex.html" title="Python Module Index" 1240 >modules</a> |</li> 1241 <li class="right" > 1242 <a href="tutorials/index.html" title="PyObjC Tutorials" 1243 >next</a> |</li> 1244 <li class="right" > 1245 <a href="index.html" title="Welcome to PyObjC-Core’s documentation!" 1246 >previous</a> |</li> 1247 <li><a href="index.html">PyObjC-Core 2.5.0b1 documentation</a> »</li> 1248 </ul> 1249 </div> 1250 <div class="footer"> 1251 © Copyright 2009-2012, Ronald Oussoren. 1252 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. 1253 </div> 1254 </body> 1255</html>