Commits

Ronald Oussoren committed ade7b81

Add HTML documentation to the CVS repository. These are generated files, need
to automate generation (yet another file in Scripts) other than by generating
a release.

Comments (0)

Files changed (13)

pyobjc/Doc/architecture.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+PyObjC Architecture</title>
+<meta name="Author" content="Ronald Oussoren" />
+</head>
+<body>
+<h2>PyObjC Architecture</h2>
+<table>
+<tbody valign="top">
+<tr><th >Author:</th>
+<td>Ronald Oussoren</td></tr>
+</tbody>
+</table>
+<h2><a name="introduction">Introduction</a></h2>
+<p>This document gives a (brief) description of how the PyObjc package is 
+structured. Too bad this document is outdated and incomplete...</p>
+<h2><a name="objective-c-classes-and-objects">Objective-C classes and objects</a></h2>
+<p>Objective-C classes are represented directly as python classes. This allows
+us to implement subclassing of Objective-C classes with the full power that
+new-style classes provide.</p>
+<p>There is one problem with this though, PyTypeObject does not have space to
+store additional information, and is a variable-sized object. This means that
+subclasses of PyType_Type cannot add instance variables. We solve this by
+storing the additional information in a dictionary indexed by the PyTypeObjects
+that represent Objective-C classes.</p>
+<p>Objective-C objects are represented by proxy objects that are instances of
+the classes descriped above.</p>
+<p>TODO: work out how we'll implement subclasses objects and describe here.</p>
+<h2><a name="methods-and-instance-variables">Methods and instance variables</a></h2>
+<p>Methods and instance variables are represented as 'descriptor' objects that
+are attributes of the PyTypeObject describing a class. This way it is possible
+to use the normal python introspection mechanisms to explore an objective-C
+object/class.</p>
+<p>There is also a mechanism to call methods that are not part of the advertised
+interface of a class. This is needed to support classes like NSProxy that 
+forward method invocations to other objects.</p>
+</body>
+</html>

pyobjc/Doc/classes.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Python classes and Objective-C code</title>
+</head>
+<body>
+<h2>Python classes and Objective-C code</h2>
+<!-- This file is formatted using the rules for StructuredText -->
+<!-- Version 0.1 -->
+<h2><a name="introduction">Introduction</a></h2>
+<p>PyObjC is a proxy between Objective-C and Python and allows access to Python
+classes from Objective-C and vice versa. PyObjC also allows you to subclass
+Objective-C classes from Python.</p>
+<h2><a name="accessing-python-objects-from-objective-c">Accessing Python objects from Objective-C</a></h2>
+<p>All Python objects can be accessed from Objective-C through proxy objects. 
+Whenever a Python object crosses the line from Python to Objective-C a proxy
+object is created (of class OC_PythonObject, a subclass of NSProxy). This
+proxy object will forward all method calls from Objective-C to python, and
+will return the results back to Objective-C.</p>
+<p>See the section 'Method protocol' for a description of how PyObjC translates 
+between Python and Objective-C method calls.</p>
+<p>Other than being a plain proxy the OC_PythonObject class also provides an
+Objective-C flavored version of the Python C-API.</p>
+<!-- Is anyone actually using the Objective-C version of the Python C-API? -->
+<p>A number of Python types/classes are treated specially:
+- Python numbers are translated into NSNumber instances
+- Python strings and unicode objects are translated into NSString instances
+- Python dictionaries are proxied using OC_PythonDictionary, a subclass of NSMutableDictionary. This allows you to use a Python dictionary everywhere where an NSDictionary is expected.
+- Python lists or tuples are proxied using OC_PythonArray, a subclas of NSMutableArray. This allows you to use a Python list or tuple everywhere where an NSArray is expected.</p>
+<p>The special cases allow for more transparent bridging between Python and
+Objective-C.</p>
+<h2><a name="accessing-objective-c-objects-from-python">Accessing Objective-C objects from Python</a></h2>
+<p>Objective-C objects are accessed through proxy objects that forward method
+calls from Python to Objective-C. All proxy objects are instances of 
+objc.objc_object, or a subclass of this class.</p>
+<p>See the section 'Method protocol' for a description of how PyObjC translates 
+between Python and Objective-C method calls.</p>
+<p>The only Objective-C class that is not proxied is NSString, instances of this
+class are translated to Python strings or unicode objects (depending on the
+value of the string).</p>
+<h2><a name="accessing-objective-c-classes-from-python">Accessing Objective-C classes from Python</a></h2>
+<p>Objective-C classes are also accessed through proxy objects, but those are
+subclasses of objc.objc_class. The proxies for Objective-C classes are 
+classes in Python.</p>
+<p>Instances are created by calling allocator class methods (like 'alloc' or
+factory methods). Objective-C instances cannot be created by using the class
+as a factory function.</p>
+<p>It is possible to create subclasses from Objective-C classes using the normal
+mechanism. There are some limitations though:</p>
+<ol type="1">
+<li>The Objective-C class must be the first base class</li>
+<li>There can be only 1 Objective-C base class.
+It is not possible to multiple-inherit from two Objective-C classes, this
+limitation is inherited from Objective-C.</li>
+<li>It is not possible to overide or extend an Objective-C method using a mixin.
+This is limitation will be lifted in future versions of PyObjC.</li>
+<li>It is not possible to overide or extend an Objective-C method by adding a new method to the class after creating it.</li>
+</ol>
+<p>PyObjC provides limited support for Objective-C protocols. The type 
+obc.informal_protocol can be used to shadow protocol definitions in Objective-C.
+Instances of this type can be used as a superclass when defining a subclass of
+an existing Objective-C class. The information in an 'informal_protocol' object
+will be used to check if the new class does implement the protocol, and to
+provide information to the bridge that is needed to correctly forward methods.</p>
+<p>A subclass of an Objective-C (proxy) class is not only a Python class, but also
+an Objective-C class. This means that it is possible to create instances of 
+these classes from Objective-C using normal Objective-C syntax, although you
+must locate the class using the function 'objc_lookUpClass' (e.g. defining
+@class MyPythonClass will not work). One of the results of this feature is that
+these classes can be used to implement classes that are defined in Interface
+Builder NIB files.</p>
+<p>Like Python classes Objective-C classes can have instance variables. If you
+define new instance variables in the Python subclass they will only be visible
+in Python, and not in Objective-C. This means that normal Python instance
+variables cannot be used as 'outlets' in interface builder. Those can be 
+defined using special properties: objc.instance_variable or objc.IBOutlet.</p>
+<p>The Objective-C class:</p>
+<pre>
+@interface MyClass : NSObject
+{
+  IBOutlet id my_outlet1;
+  IBOutlet id my_outlet2;
+}
+
+// ...
+@end // MyClass
+</pre>
+<p>can be defined in Python like this:</p>
+<pre>
+class MyClass (NSObject):
+  my_outlet1 = objc.IBOutlet('my_outlet1')
+  my_outlet2 = objc.IBOutlet('my_outlet2')
+
+# ...
+</pre>
+<h2><a name="method-protocol">Method protocol</a></h2>
+<p>There is a straightforward translation from Objective-C method names to
+Python method names: Concatenate all parts of the Objective-C method name
+(without any whitespace) and then replace all colons by underscores.</p>
+<p>Examples:</p>
+<pre>
+(void)myAction:(id)sender     &lt;-&gt;     def `myAction_`(self, sender)
+method:(int)x andY:y          &lt;-&gt;     def `method_andY_`(self, x, y)
+</pre>
+<p>As can be seen in the examples above, Objective-C allows you to specify
+the types of arguments and the return value, while this is not possible in
+Python. This is not a problem when calling existing Objective-C methods, 
+because PyObjC will automaticly read the needed information from the 
+Objective-C runtime, but it can be a problem when defining new Objective-C
+methods in Python.</p>
+<p>PyObjC therefore provides a function to define the signature of a python method
+in subclasses of Objective-C classes. This function, objc.selector, should be
+used whenever you define a method that does not extend or override an existing
+Objective-C method in the superclass.</p>
+<p>The following Objective-C class:</p>
+<blockquote>
+<p>@interface MyClass : NSObject
+{
+}</p>
+<p>-(int)methodWithX:(int)x andY:(float)y;
+-(void)myAction:(id)sender;</p>
+</blockquote>
+<p>can be defined in Python like this:</p>
+<pre>
+class MyClass (NSObject):
+
+        def `methodWithX_andY_`(self, x, y):
+                pass
+
+        `methodWithX_and_Y_` = selector(`methodWithX_andY_`,
+                signature='i@:if')
+
+        def `myAction_`(self, sender):
+                pass
+
+        myAction_ = selector(`myAction_`,
+                signature='v@:')
+</pre>
+<p>The explicit selectors don't really help to increase readability, especially
+given the cryptic signature strings. It is therefore advisable to use other
+methods to define the signature if possible, the most likely way to do this
+is by using existing objc.informal_protocol definitions (like 
+AppKit.NSOutlineViewDataSource).</p>
+<p>There is one instance where you don't have to define the signature: The default
+signature is for a method that returns and object and where all arguments are
+also objects.</p>
+</body>
+</html>

pyobjc/Doc/coding-style.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Coding style for PyObjC</title>
+<meta name="Author" content="Ronald Oussoren" />
+<meta name="Author" content="Bill Bumgarner" />
+<meta name="Contact" content="pyobjc-dev@lists.sourceforge.net" />
+<meta name="copyright" content="2002 The PyObjC Project" />
+<title>
+Contents</title>
+</head>
+<body>
+<h2>Coding style for PyObjC</h2>
+<table>
+<tbody valign="top">
+<tr><th >Author:</th>
+<td>Ronald Oussoren</td></tr>
+<tr><th >Author:</th>
+<td>Bill Bumgarner</td></tr>
+<tr><th >Contact:</th>
+<td><a href="mailto:pyobjc-dev@lists.sourceforge.net">pyobjc-dev@lists.sourceforge.net</a></td></tr>
+<tr><th>URL:</th><td><a href="http://pyobjc.sourceforge.net/">http://pyobjc.sourceforge.net/</a><br />
+</td>
+</tr>
+<tr><th >Copyright:</th>
+<td>2002 The PyObjC Project</td></tr>
+</tbody>
+</table>
+<h2>Contents</h2>
+<ul>
+<li><a href="#introduction" id="id1" name="id1">Introduction</a></li>
+<li><a href="#python-code" id="id2" name="id2">Python code</a></li>
+<li><a href="#c-code" id="id3" name="id3">C code</a></li>
+<li><a href="#documentation" id="id4" name="id4">Documentation</a><ul>
+<li><a href="#rest-in-docstrings" id="id5" name="id5">ReST in DocStrings</a></li>
+</ul>
+</li>
+</ul>
+<h2><a href="#id1" name="introduction">Introduction</a></h2>
+<p>This document describes the coding style for PyObjC. Please use this style for
+new code and try apply this style to existing code while working on it.</p>
+<h2><a href="#id2" name="python-code">Python code</a></h2>
+<p>The coding style for core Python is used (see <a href="http://www.python.org/peps/pep-0008.txt">PEP 8</a>). For consistency with
+Cocoa we use mixed-case identifiers (like <code><span>lookUpClass</span></code>).</p>
+<p>PyObjC extensions to Apple frameworks should be clearly marked as such, 
+preferably by prefixing names with <code><span>PyObjC</span></code> or <code><span>pyobjc</span></code>. This should make it
+clear to users where they should look for documentation of an item: The Apple
+documentation or ours.</p>
+<p>The entire <code><span>objc</span></code> module is an &quot;extension&quot; and all items exported from that
+module should be documented in our documentation.</p>
+<h2><a href="#id3" name="c-code">C code</a></h2>
+<p>The coding style for core Python is used (see <a href="http://www.python.org/peps/pep-0007.txt">PEP 7</a>). We use <code><span>PyObjC</span></code> instead
+of <code><span>Py</span></code> as the prefix for globally visible symbols.</p>
+<h2><a href="#id4" name="documentation">Documentation</a></h2>
+<p>All items exported by the objc module and all PyObjC extensions to Apple
+frameworks (the AppKit and Foundation modules) should be documented using
+docstrings.</p>
+<p>All documentation-- both standalone documents and docstrings-- should be
+marked up using <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> [ReST].</p>
+<h3><a href="#id5" name="rest-in-docstrings">ReST in DocStrings</a></h3>
+<p><a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> can be used in doc strings.   ReST in DocStrings works
+exactly like a standalone ReST document, but the ReST is broken up slightly
+differently.</p>
+<p>To format the DocStrings to be ReST compatible, make the following
+changes/additions to the source.  These examples were taken from source found
+in the DocUtils source tree.</p>
+<ol type="1">
+<li>Add appropriate ReST style fields to the top of the document as comments:<pre>
+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.1 $
+# Date: $Date: 2003/04/06 17:59:37 $
+# Copyright: This module has been placed in the public domain.
+</pre>
+</li>
+<li>Add a module level variable that indicates that ReST is used to format
+the text contained in the docstrings:<pre>
+__docformat__ = 'reStructuredText'
+</pre>
+</li>
+<li>Format all other DocStrings as one normally would in Python.   Use ReST
+style markup where appropriate.   For example, bulleted lists and
+sections might commonly appear in the module or class docstrings.   The
+docstrings for individual methods may use example blocks, hyperlinks, or
+any other ReST markup.</li>
+</ol>
+</body>
+</html>

pyobjc/Doc/index.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+PyObjC documentation index</title>
+</head>
+<body>
+<h2>PyObjC documentation index</h2>
+<p>The documentation for PyObjC is lacking at the moment, and is high on our
+TODO list.</p>
+<ul>
+<li><a href="intro.html">An introduction to PyObjC</a></li>
+<li><a href="tutorial/tutorial.html">Creating your first PyObjC application (tutorial)</a></li>
+<li><a href="users.html">Userguide for PyObjC</a></li>
+<li><a href="classes.html">Python classes and Objective-C code</a></li>
+<li><a href="coding-style.html">Coding style for PyObjC</a></li>
+<li><a href="libffi.html">Using LibFFI with PyObjC</a></li>
+<li><a href="architecture.html">PyObjC Architecture</a></li>
+<li><a href="structure.html">Structure of the PyObjC package</a></li>
+<li><a href="wrapping.html">How to wrap an Objective-C class library</a></li>
+<li><a href="warts.html">Odd features</a></li>
+</ul>
+</body>
+</html>

pyobjc/Doc/intro.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+An introduction to PyObjC</title>
+<title>
+Contents</title>
+</head>
+<body>
+<h2>An introduction to PyObjC</h2>
+<!-- :authors: Ronald Oussoren
+:contact: pyobjc-dev@lists.sourceforge.net
+:URL: http://pyobjc.sourceforge.net/
+:copyright: 2003 The PyObjC Project -->
+<h2>Contents</h2>
+<ul>
+<li><a href="#work-in-progress" id="id1" name="id1">WORK IN PROGRESS</a></li>
+<li><a href="#preface" id="id2" name="id2">Preface</a></li>
+<li><a href="#objective-c-for-pyobjc-users" id="id3" name="id3">Objective-C for PyObjC users</a></li>
+<li><a href="#overview-of-the-bridge" id="id4" name="id4">Overview of the bridge</a></li>
+<li><a href="#cocoa-for-python-programmers" id="id5" name="id5">Cocoa for Python programmers</a></li>
+<li><a href="#building-applications" id="id6" name="id6">Building applications</a><ul>
+<li><a href="#pure-python-buildapp-py" id="id7" name="id7">&quot;Pure python&quot; :  buildapp.py</a></li>
+<li><a href="#ide-approach-project-builder" id="id8" name="id8">&quot;IDE approach&quot; : Project builder</a></li>
+</ul>
+</li>
+</ul>
+<h2><a href="#id1" name="work-in-progress">WORK IN PROGRESS</a></h2>
+<p>This document is work in progress and thin on details.</p>
+<h2><a href="#id2" name="preface">Preface</a></h2>
+<p>PyObjC is a bridge between Python and Objective-C. It allows you to write 
+Python scripts that reuse and extend existing Objective-C class libraries, 
+most importantly the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa library</a> by <a href="http://www.apple.com/">Apple</a>.</p>
+<p>This document describes how to use Objective-C class libraries from Python
+scripts and how to interpret the documentation of those libraries, from the 
+point of view of a Python programmer.</p>
+<h2><a href="#id3" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<p>Objective-C is an object-oriented programming language that is an extention 
+of C and borrows heavily from Smalltalk. It features single inheritance with
+(in theory) multiple root classes and dynamic dispatch of methods. This is
+basicly the same as python with single inheritance.</p>
+<p>An important difference between Python and Objective-C is that the latter is
+not a pure object-oriented language. Some values are not objects, but values
+of plain C types, such as <code><span>int</span></code> and <code><span>double</span></code>. These basic C types can also
+be used as the types of arguments and the return value of methods.</p>
+<p>Object allocation and initialization are explicit and seperate actions in 
+Objective-C. The former is done by the class-method <code><span>alloc</span></code>, while the
+latter is done by instance-methods whose name customarily starts with <code><span>init</span></code>.</p>
+<p>For more information about Objective-C see:</p>
+<ul>
+<li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
+</ul>
+<h2><a href="#id4" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<p>Objective-C classes are visible as Python classes and can be subclassed just
+like normal Python classes. The major differences between normal Python classes
+and Objective-C classes are the way you create instances and the fact that 
+Objective-C classes have <i>odd</i> names.</p>
+<p>As described in <a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 
+objects is a two-stage process. You first call the class method <code><span>alloc</span></code>, and
+then call some variation of <code><span>init</span></code> to initialize the objects. The newly
+created object is the result of the call to <code><span>init</span></code>. Most classes have 
+convienence class methods that combine the calls to <code><span>alloc</span></code> and <code><span>init</span></code>.</p>
+<p>Objective-C methods are bridged to python callables. Because Objective-C method 
+names can contain colons it is necessary to translate methods names. The rules
+for translation are:</p>
+<ul>
+<li>Concatenate all elements of the method name: <code><span>someMethod:withFoo:andBar:</span></code></li>
+<li>Then convert all colons to underscores: <code><span>someMethod_withFoo_andBar_</span></code></li>
+</ul>
+<p>The bridged method usually has the same number of arguments as the orginal 
+method and also returns the same as the original method. In special 
+circumstances the method interface may be different from the Objective-C 
+interface, those methods are document in 'some other document'. Furthermore,
+some methods have pass-by-reference arguments (that is a pointer to a single
+value that is used to transfer data to (in), from (out) or to-and-from (inout)
+the method. The arguments that are passed to methods is present as normal 
+arguments in the bridged method (e.g. if the method has an <code><span>int*</span></code> argument
+the bridged method has has an integer argument).  Data that is passed from the
+function results in additional return values from the function.</p>
+<p>When the bridge cannot automaticly deduce the right signature for a method, or
+if you want to add a method whose name cannot be transformed into python (
+for example a methodname containing <code><span>$</span></code>), you'll have to add explicit hints
+to your code. You do this by calling the function <code><span>objc.selector</span></code> and using
+the result instead of your method definition:</p>
+<pre>
+class MyObject (NSObject):
+        def someMethod_(self, arg):
+                pass
+
+        someMethod_ = objc.selector(someMethod_, ...)
+</pre>
+<p>The other arguments of <code><span>objc.selector</span></code> (not shown in the example) provide
+additional information about the method to the bridge, see the online 
+documentation for more information about this function. It is almost never
+necessary to use this technique.</p>
+<p>The need for additional hints to the bridge often arises from implementing an
+(informal) protocol in Python. Because the methods compromising the protocol
+are probably not implemented in the superclass the bridge often cannot deduce 
+the correct method signatures for the methods you implemented. To avoid the
+need for using <code><span>objc.selector</span></code> and to make it explicit that your implementing
+an (informal) protocol the bridge has explicit support for these (informal)
+protocols.</p>
+<p>To tell the bridge that your implementing an informal protocol you use an
+<code><span>informal_protocol</span></code> object as a mixin:</p>
+<pre>
+class MyModel (NSObject, anInformalProtocol):
+        pass
+</pre>
+<p>The <code><span>AppKit</span></code> and <code><span>Foundation</span></code> modules define <code><span>informal_protocol</span></code> objects 
+for most (informal) protocols and defined by these frameworks (both the 
+explicitly documented protocols and the protocols used to communicate between
+an object and its delegate).</p>
+<h2><a href="#id5" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
+<p>Cocoa frameworks are mapped onto Python packages with the same name, that is
+the classes, constants and functioins from the AppKit framework are available
+after you import <code><span>AppKit</span></code> in your Python script.</p>
+<p>The module <code><span>PyObjCTools.NibClassBuilder</span></code> can be used to make working with 
+NIB files more convenient. This module can be used to extract information 
+about classes from NIB files, both as a standalone tool generating source code 
+and during runtime. See the online documentation for this module for more
+information.</p>
+<p><strong>TODO</strong>:</p>
+<ul>
+<li>Links to example PyObjC scripts.</li>
+</ul>
+<p>More information on Cocoa programming can be found at:</p>
+<ul>
+<li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa documentation at the Apple developer website</a></li>
+<li><a href="http://developer.apple.com/samplecode/Sample_Code/Cocoa.htm">Cocoa examples at the Apple developer website</a></li>
+<li><a href="http://www.stepwise.com/">stepwise.com</a></li>
+<li>Your local bookstore or library</li>
+</ul>
+<h2><a href="#id6" name="building-applications">Building applications</a></h2>
+<p>There are two different ways to build applications with PyObjC. There are no
+major advantages to using either one of them, use the one that is most 
+convenient to you.</p>
+<h3><a href="#id7" name="pure-python-buildapp-py">&quot;Pure python&quot; :  buildapp.py</a></h3>
+<p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module will be part
+of the Python 2.3 MacPython release and is a to build distutil-style scripts 
+for building (standalone) applications.</p>
+<p>An example <code><span>buildapp.py</span></code> script:</p>
+<pre>
+from bundlebuilder import buildapp
+buildapp(
+        name = 'iClass',
+        mainprogram = &quot;main.py&quot;,
+        resources = [&quot;English.lproj&quot;, &quot;datasource.py&quot; ],
+        nibname = &quot;MainMenu&quot;,
+)   
+</pre>
+<p>The online documentation for <code><span>bundlebuilder</span></code> contains more information on 
+building <code><span>buildapp.py</span></code> scripts.</p>
+<h3><a href="#id8" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
+<p>PyObjC includes a number of Project Builder templates that can be used to 
+build (standalone) applications.</p>
+<p><strong>TODO</strong>:</p>
+<ul>
+<li>Expand this section, input needed as I don't use Project Builder</li>
+<li>Add link to documentation about our templates</li>
+<li>Add link to documentation for Project Builder</li>
+</ul>
+</body>
+</html>

pyobjc/Doc/libffi.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Using LibFFI with PyObjC</title>
+<meta name="Author" content="Ronald Oussoren" />
+</head>
+<body>
+<h2>Using LibFFI with PyObjC</h2>
+<table>
+<tbody valign="top">
+<tr><th >Author:</th>
+<td>Ronald Oussoren</td></tr>
+</tbody>
+</table>
+<p>PyObjC uses libffi to dynamicly call into Objective-C. We use libffi instead of
+NSInvocation because the former makes it possible to call superclass methods,
+and to generate stubs for use in Objective-C method tables on the fly.</p>
+<p>It is currently possible to build a non-ffi build of PyObjC, but that is not
+supported and will be removed as we use features from libffi to further 
+improve the brigde.</p>
+</body>
+</html>

pyobjc/Doc/structure.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Structure of the PyObjC package</title>
+</head>
+<body>
+<h2>Structure of the PyObjC package</h2>
+<!-- This document is in structured text markup to enable easy translation to 
+HTML. -->
+<h2><a name="introduction">Introduction</a></h2>
+<p>This document gives an overview of the PyObjC for developers (of the package).</p>
+<p>One of the sections describes how all of it works, and some of the limitation.</p>
+<h2><a name="methods">Methods</a></h2>
+<p>Classes are scanned for methods when the python wrapper for a class is created.
+We then create python wrappers for those methods. This way users can use the
+normal python introspection methods to check which methods are available.</p>
+<p>Sadly enough some classes in the Cocoa frameworks on Mac OSX grow new methods
+when the first instance of those classes is created. We therefore have added 
+some additional code that rescans the method tables on several occasions.</p>
+<h2><a name="subclassing">Subclassing</a></h2>
+<p>It is possible to subclass objective-C classes in python and this results in a hybrid Python/Objective-C class. Instances of these classes consist of a cluster of 2 objects, a Python object and an Objective-C object.</p>
+<p>The reference count (or retainCount in objective-C speak) is stored in the 
+Python object, mostly because that is the only way to maintain a single 
+reference count for the cluster. The pointers from the python half of the 
+cluster to the objective-C half, and the pointers the other way around, are
+not counted in the reference count. If those would be counted we would
+introduce cycles that are not detectable by the cycle-breaking garbage 
+collector in python and all python/objective-C hybrids would be immortal.</p>
+<p>The first python subclass of an objective-C class introduces a new instance
+variable in the objective-C object to store the pointer to the python half of
+the cluster. This variable is always referenced by name.  The python half is 
+a subclass of objc_object that already contains a pointer to an objective-C 
+object.</p>
+<p>The first python subclass of an objective-C class also introduces a number of
+methods (both class methods and instance methods) that allow us to maintain the
+illusion of a single object. Check class-builder.m for details.</p>
+<h2><a name="directory-structure">Directory structure</a></h2>
+<dl>
+<dt>Doc/</dt>
+<dd><p>Documentation</p>
+</dd>
+<dt>Examples/</dt>
+<dd><p>Example scripts and applets.</p>
+</dd>
+<dt>Lib/</dt>
+<dd><p>Python modules that will be installed in the library. Currently contains
+the packages 'objc', 'Cocoa' and 'AddressBook'</p>
+</dd>
+<dt>Modules/</dt>
+<dd><p>Extension modules related to the packages in 'Lib'. This directory contains
+both the core module 'objc._objc' and a number of extension modules that
+help in wrapping all of Cocoa.</p>
+</dd>
+<dt>Scripts/</dt>
+<dd><p>Scripts used during building and/or development of PyObjC.</p>
+</dd>
+<dt>Tools/</dt>
+<dd><p>Scripts that are usefull for users of PyObjC</p>
+</dd>
+</dl>
+<h2><a name="reference-counts">Reference counts</a></h2>
+<p>The Objective-C rules for reference counts are pretty easy: A small number
+of class methods (alloc, allocWithZone:, copy, ...) transfer object ownership
+to the caller. For all other objects you have to call 'retain' if you want
+to keep a reference. This includes all factory methods (e.g. 
+[String stringWithCString:&quot;bla&quot;])!</p>
+<p>The objc module tries to make the management of reference counts completely
+transparent for the user of the module. This is mostly solved in 
+[de]pythonify_c_value. Additonal code is needed when calling methods that
+transfer ownership of their return value (as described above) and when updating
+a instance variable in an Objective-C object (retain new and release old, 
+in that order). Both are implemented.</p>
+<h2><a name="strings">Strings</a></h2>
+<p>We currently automaticly convert from Python strings to NSStrings (and back). 
+This may not be the smartest thing to do because NSString has a number of 
+methods that don't have an equivalent in Python.</p>
+<p>Converting a Python string to objective-C and back currently converts the 
+string to Unicode. If may be usefull to try to convert to a normal string
+(using [NSString dataUsingEncoding:allowLossyConversion:]) and only return
+a Unicode object if that fails.</p>
+<p>When translating from NSString to a Python unicode object (and back) we first 
+translate to a UTF8 encoding. This way we don't have to worry about any
+differences in the representation of Unicode strings in Python and objective-C
+(Python has two different represenations, selection is at compile-time)</p>
+</body>
+</html>

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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Creating your first PyObjC application.</title>
+</head>
+<body>
+<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>PyObjC</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>
+<pre>
+$ setenv PYLIB /Library/Frameworks/Python.framework/Versions/Current/lib/python2.3
+</pre>
+<p>or if you use bash as your shell:</p>
+<pre>
+$ export PYLIB=/Library/Frameworks/Python.framework/Versions/Current/lib/python2.3
+</pre>
+<p>For Apple's <code><span>/usr/bin/python</span></code> set the variable to <code><span>/usr/lib/python2.2</span></code>.</p>
+</li>
+<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;. Stop when you get
+to the section &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>
+<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
+</pre>
+<p>The result of this can be seen in <a href="step4-CurrencyConverter.py">step4-CurrencyConverter.py</a>.</p>
+</li>
+</ol>
+<ol start="5" type="1">
+<li>Next we need to add a little more boilerplate code to <code><span>CurrencyConverter.py</span></code>. At some point
+in the future this will become simpler, but for now we need to add a main program
+that jumps through various hoops to get the application started.
+The results of this can be seen in <a href="step5-CurrencyConverter.py">step5-CurrencyConverter.py</a>.</li>
+</ol>
+<blockquote>
+<p><i>XXXX Implementation Note:</i> NibClassBuilder should do this for you, at least
+optionally.</p>
+</blockquote>
+<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
+</pre>
+<p>There are a few things to note:</p>
+<ul>
+<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>
+</ul>
+</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
+</pre>
+</li>
+<li>run it directly from the Terminal, as:<pre>
+$ ./build/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
+</pre>
+</li>
+</ul>
+<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>
+</li>
+</ol>
+<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]
+</pre>
+<p>the Python name will be <code><span>modifyArg_andAnother_</span></code> and you invoke it as:</p>
+<pre>
+object.modifyArg_andAnother_(arg1, arg2)
+</pre>
+<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>
+</li>
+</ol>
+<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>
+<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
+</pre>
+<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>
+</li>
+</ol>
+<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,
+etc.</p>
+</li>
+<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>
+</ol>
+<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>
+</body>
+</html>

pyobjc/Doc/users.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Userguide for PyObjC</title>
+</head>
+<body>
+<h2>Userguide for PyObjC</h2>
+<!-- This file is formatted using the rules for StructuredText -->
+<h2><a name="introduction">Introduction</a></h2>
+<p>This is the user guide for PyObjC. It describes how to use this package to
+implement Python scripts that use Objective-C classes and objects. It also
+describes the limitations of this Package.</p>
+<p>The last section describes the C API of this package and why you may want to
+use it.</p>
+<h2><a name="overview">Overview</a></h2>
+<p>Using PyObjC is pretty simple, as it strives to make the bridge completely
+transparent. On the lowest level you can import the 'objc' module and use that
+to locate classes (objc.lookUpClass). For most users it is more usefull to
+just import 'Foundation' and 'AppKit' and use the familiar Cocoa classes
+and functions.</p>
+<p>Objective-C classes are make available as new-style classes, and can be queried
+using the normal introspection techniques.</p>
+<p>Methodnames for Objective-C classes are constructed as follows: Concatenate all 
+elements of the selector and replace colons by underscores.</p>
+<p>The order of arguments is the same as in Objective-C, with one exception: If
+a method as output-only arguments those arguments are not present in the python
+version of the method. If a method has output parameters (either input-output
+or output-only) the values of these parameters are passed back in the return
+value of the python version. The return value of methods with output parameters
+is a tuple where the first element is the return-value of the Objective-C 
+method (or None if it is a method returning 'void') and the other elements are
+the values of output arguments.</p>
+<h2><a name="informal-protocols">(Informal) Protocols</a></h2>
+<p>Cocoa defines a number of formal and informal protocols that specify the 
+methods that should be defined by a class if it wants to be used in particular
+roles (such as the data source for an NSTableView).</p>
+<p>The type objc.informal_protocol can be used to specify the selectors used by
+those (informal) protocols in Objective-C. Instances of objc.informal_protocol 
+are used when defineing subclasses of Objective-C classes and signal that the 
+class implements the given protocol.</p>
+<p>The AppKit and Foundation modules export a number of usefull protocols, 
+corresponding to the protocols defined in the Cocoa documentation. It is 
+essential to use these protocol definitions as mixins when defining classes that
+conform to the protocol. This not only helps catching typos when developing
+classes, but also provides information to the bridge that is essential for
+correct operation of the bridge.</p>
+<h2><a name="building-an-application">Building an application</a></h2>
+<p>There are two different ways to build application bundles. The resulting 
+applications are functionally equivalent, although not identical.</p>
+<p>If Apple's developer tools are installed you can use one of the PyObjC 
+project templates to build your application. (TODO: Add link to documentation
+on the templates). The <code><span>TableModel2</span></code> example uses Project Builder.</p>
+<p>If is also possible to build application bundles using bundlebuilder, using
+scripts that are simular to the <code><span>setup.py</span></code> script used by distutils. The
+<code><span>TableModel</span></code> example uses this method. For more documentation, see the
+online documentation of module <code><span>bundlebuilder</span></code>.</p>
+<h2><a name="limitations">Limitations</a></h2>
+<p>The objc module automaticly wraps classes and objects. This works correctly in
+the easy case where there are no methods with variable arguments or 
+pass-by-reference arguments. If there are, the core module needs some help.</p>
+<p>For this reason it is best to not use just the core API when your working with
+this module, but to use packages like 'Foundation' that provide the help 
+needed and might also wrap other functionality (constants, functions) in a framework.</p>
+<p>The current version of the module does not provide support for threading. It
+might be possible to create threads using the 'thread' module if you manually
+create an NSAutoreleasePool for the thread. This has not been tested. The
+Cocoa threading classes should not be used because they don't update the 
+state of the Python interpreter when creating a new thread.</p>
+<h2><a name="c-api">C API</a></h2>
+<h3><a name="id1">Introduction</a></h3>
+<p>The PyObjC package provides a C API that can be used when you're wrapping 
+functions that deal with Objective-C objects or classes. It can also be used
+to provide functions that help to wrap problematic objective-C methods (like 
+those that take a variable number of arguments).</p>
+<p>This API is used by the 'Cocoa' package (part of the PyObjC distribution) to
+wrap the entire Cocoa API.</p>
+<h3><a name="how-to-use-it">How to use it</a></h3>
+<p>You <code><span>#include</span></code> &quot;pyobjc-api.h&quot; in your module implementation. In the module
+initialisation function you then call <code><span>ObjC_ImportModule(mymodule)</span></code>. After
+this you can use the functions and constants defined in the API.</p>
+<h3><a name="constants">Constants</a></h3>
+<p>TODO</p>
+<h3><a name="functions">Functions</a></h3>
+<p>TODO</p>
+<h3><a name="id2">Limitations</a></h3>
+<p>We currently assume that extension module contain at most 1 file that uses
+the PyObjC API.</p>
+</body>
+</html>

pyobjc/Doc/warts.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Odd features</title>
+</head>
+<body>
+<h2>Odd features</h2>
+<!-- :author: Ronald Oussoren -->
+<p>The mapping from Objective-C onto Python is almost complete, but the following
+things should be kept in mind:</p>
+<ul>
+<li>Objective-C only has single inheritance. You can use multiple inheritance in
+the python code, but only to mix in 'fully python' classes. Do <i>not</i> use 
+multiple inheritance, this feature may not survive beyond 0.9.</li>
+<li>In objective-C it is valid to call methods on nil, these calls will be
+ignored. The nil 'object' is mapped to None and None will not ignore method
+calls, but will most likely raise an AttributeError. You'll have to remember
+this when translating from Objective-C to python.</li>
+<li>Some Cocoa classes store references to objects while not increasing the 
+reference count. One of those is NSOutlineView. A side-effect of this is that
+you <i>must</i> use subclasses of NSObject in your NSOutlineView model.</li>
+</ul>
+</body>
+</html>

pyobjc/Doc/wrapping.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+How to wrap an Objective-C class library</title>
+</head>
+<body>
+<h2>How to wrap an Objective-C class library</h2>
+<!-- :author: Ronald Oussoren -->
+<h2><a name="introduction">Introduction</a></h2>
+<p>This document describes how you can wrap on Objective-C class library using
+a Python module or package.  This document assumes that your class library is
+located in a framework.</p>
+<p>Wrapping can be pretty easy for most classes, but you may have to write some
+C code for specific methods.</p>
+<h2><a name="the-basics">The basics</a></h2>
+<p>The code for loading a framework and exporting its classes is pretty simple:</p>
+<pre>
+import objc
+objc.loadBundle(&quot;MyFramework&quot;, globals(), 
+   bundle_path='/path/to/MyFramework.framework')
+del objc
+</pre>
+<p>If your class library does not require helper functions for some methods this
+is all that is needed.</p>
+<h2><a name="wrapping-global-functions-and-constants">Wrapping global functions and constants</a></h2>
+<p>The code above only provides wrappers for Objective-C classes, if the library
+also defines global functions and/or constants you'll have to write an 
+extension module to make these available to Python.</p>
+<p>You can use the PyObjC C-API (to be documented) when writing this module.</p>
+<h2><a name="pointer-arguments">Pointer arguments</a></h2>
+<p>Methods with pointer arguments (other then arguments that are equivalent to 
+an 'id') require more work. If the pointer arguments are used to pass a single 
+value to/from a function ('pass-by-reference arguments') you'll just have to 
+provide more specific method signatures. In other cases you'll have to write
+custom wrappers for these methods.</p>
+<h3><a name="pass-by-reference-arguments">Pass-by-reference arguments</a></h3>
+<p>Pass-by-reference arguments can be 'in' (data passed into the function), 
+'out' (data is returned from the function) or 'inout' (data is passed into 
+and then returned from  the function).</p>
+<p>Given the following class interface:</p>
+<pre>
+@interface ClassName {}
+
+-(void)selector:(id*)outArgument withArguments:(NSArray*)data;
+
+@end
+</pre>
+<p>The compiler will generate a method signature for this method and this can 
+be accessed from Python using the property 'signature' of Objective-C methods. 
+You can also just make up the signature, which is quite easy once you get the
+hang of it. The signature for this method is 'v@:^@@'.</p>
+<p>Let's say the first argument is an output parameter. Output parameters are 
+denoted in the signature string using the character 'o' before the actual
+argument signature. The 'correct' signature for method is therefore 'v@:o^@@'.
+The following code tells the brigde about this better method signature:</p>
+<pre>
+import objc
+objc.set_signature_for_selector(&quot;ClassName&quot;, &quot;selector:withArguments:&quot;,
+     &quot;v@:o^@:@&quot;)
+</pre>
+<p>To anotate method signatures you'll have to add a single character before all
+'^' characters in the signature of a method. The characters are:</p>
+<ul>
+<li>output parameter: o</li>
+<li>input parameter: i</li>
+<li>input-output parameter: O</li>
+</ul>
+<h3><a name="special-wrappers">special wrappers</a></h3>
+<p>If the method has pointer arguments that are not pass-by-reference arguments,
+or if the default method wrappers are not suitable for other reasons, you'll
+have to write custom wrappers. For every custom wrapper you'll have to write
+three functions: 1 to call the method from Python, 1 to call the superclass
+implementation of the method from Python and 1 to call a Python implementation
+of the method from Objective-C.</p>
+<p>For now it is best to check the source code for the wrappers for the Cocoa 
+class library for more information. We'll add documentation for this in the
+future.</p>
+<p>NOTE: It is likely that there will be changes w.r.t. the special wrappers.</p>
+</body>
+</html>

pyobjc/Install.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Installation Instructions</title>
+</head>
+<body>
+<h2>Installation Instructions</h2>
+<!-- :authors: Bill Bumgarner, Ronald Oussoren -->
+<h2><a name="building-the-package">Building the package</a></h2>
+<p>If you're using the sources from CVS you should first download a copy of 
+libffi from <a href="http://sourceforge.net/project/showfiles.php?group_id=14534">the PyObjC download site</a>.  Extract this in a convenient location
+and update the variable <code><span>LIBFF_SOURCES</span></code> at the top of setup.py.  The released
+version of PyObjC includes a compatible version of libffi.</p>
+<p>PyObjC is build and installed using the distutils package included with Python
+2.0 and beyond.  This package provides a single interface for building and
+packaging the module.   To see usage documentation for the module,
+issue the <code><span>--help</span></code> command:</p>
+<pre>
+% python setup.py --help
+</pre>
+<p>To see an inventory of building and packaging commands, issue the
+command:</p>
+<pre>
+% python setup.py --help-commands
+</pre>
+<p>The following command will build and install the pyobjc module:</p>
+<pre>
+% python setup.py install
+</pre>
+<p>The setup.py system can also be used to create source and binary
+distribution archives automatically.</p>
+<p>Use <code><span>sudo</span></code> to install the pyobjc module into a the Apple supplied
+python's site-packages directory on OS X 10.2 and greater:</p>
+<p>% sudo python setup.py install</p>
+<p>If you have multiple versions of python installed on your system, the
+above will only install pyobjc for whatever version of python is the
+default on the command line.   Make sure you are installing python
+against the correct version of python.</p>
+<h2><a name="examples">Examples</a></h2>
+<p>The examples directory contains a number of projects that demonstrate
+various features of the PyObjC bridge. The scripts at the top level of
+the examples directory were mostly written to test a particular
+feature of the bridge (or document a bug until a fix could be found).</p>
+<p>CurrencyConverter and TableModel are both examples of standalone
+Cocoa-Python applications.  To build and execute:</p>
+<pre>
+% cd TableModel
+% python buildapp.py build
+</pre>
+<p>The WebServicesTool and TableModel2 are both examples of Cocoa-Python
+applications created via the Cocoa-Python project template found in
+the <code><span>Project</span> <span>Templates</span></code> directory.  Use Project Builder to build the
+applications.</p>
+<h2><a name="project-templates">Project Templates</a></h2>
+<p>The <code><span>Project</span> <span>Templates</span></code> directory contains project templates for
+project builder.  Currently, there is one project builder template;  a
+Cocoa-Python Application project template.   When installed, this adds
+a project to Project Builder's project menu that allows new Cocoa
+applications implemented entirely in Python to be created from within
+Project Builder (in the same fashion as any other project).</p>
+<p>To install, simply copy the project template into the Project Builder
+project templates directory (or create a symlink).</p>
+<p>More information on project templates can be found in the Project
+Builder documentation and/or release notes.</p>
+</body>
+</html>

pyobjc/ReadMe.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">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Welcome to PyObjC</title>
+</head>
+<body>
+<h2>Welcome to PyObjC</h2>
+<!-- :authors: Ronald Oussoren, Bill Bumgarner -->
+<p>The PyObjC package provides the glue needed to interface the Python interpreter with the Objective-C language. At its core is the <code><span>objc</span></code> module makes 
+Objective-C objects and classes available as first-class Python citizens, it is 
+not only possible to use Objective-C objects but you can also subclass 
+Objective-C classes.</p>
+<p>To make it easier to use the core <code><span>objc</span></code> module this package also provides 
+a number of modules that are wrappers for the Cocoa frameworks Foundation and
+AppKit. These modules not only give you access to the classes in these 
+frameworks but also to the functions and constants in those modules.</p>
+<p>Read <a href="Doc/index.html">the documentation</a> for more information on how to use this package. The
+<a href="Install.html">installation manual</a> describes how to install this package.</p>
+<p>The latest information can always be found at:</p>
+<blockquote>
+<p><a href="http://pyobjc.sourceforge.net/">http://pyobjc.sourceforge.net/</a></p>
+</blockquote>
+<p>b.bum                Ronald Oussoren
+<a href="mailto:bbum@codefab.com">bbum@codefab.com</a>     <a href="mailto:oussoren@cistron.nl">oussoren@cistron.nl</a></p>
+</body>
+</html>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.