1. Ronald Oussoren
  2. pyobjc

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.

  • Participants
  • Parent commits 9858f93
  • Branches default

Comments (0)

Files changed (13)

File pyobjc/Doc/architecture.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/classes.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/coding-style.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/index.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/intro.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/libffi.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/structure.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/tutorial/tutorial.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/users.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/warts.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Doc/wrapping.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/Install.html

View file
  • Ignore whitespace
+<?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>

File pyobjc/ReadMe.html

View file
  • Ignore whitespace
+<?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>