Source

pyobjc / pyobjc / Doc / wrapping.html

Full commit
<?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>