Ronald Oussoren  committed e0881bc

Added basic documentation on how to wrap you're own class libraries

  • Participants
  • Parent commits c57092c

Comments (0)

Files changed (1)

File pyobjc/Doc/wrapping.txt

+How to wrap an Objective-C class library
+.. This file is formatted using the rules for StructuredText
+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.
+Wrapping can be pretty easy for most classes, but you may have to write some
+C code for specific methods.
+The basics
+The code for loading a framework and exporting its classes is pretty simple:
+   import Foundation
+   _clslist = Foundation.load_bundle('/path/to/MyFramework.framework')
+   _gl = globals()
+   for _cls in _clslist:
+   	gl[_cls.__name__] = _cls 
+   del _clslist, _cls, _gl, Foundation
+If your class library does not require helper functions for some methods this
+is all that is needed.
+Wrapping global functions and constants
+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.
+You can use the PyObjC C-API (to be documented) when writing this module.
+Pointer arguments
+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.
+Pass-by-reference arguments
+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). 
+Given the following class interface:
+   @interface ClassName {}
+   -(void)selector:(id*)outArgument withArguments:(NSArray*)data;
+   @end
+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@:^@@'.
+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.
+   import objc
+   objc.set_signature_for_selector("ClassName", "selector:withArguments:",
+   	"v@:o^@:@")
+To anotate method signatures you'll have to add a single character before all
+'^' characters in the signature of a method. The characters are:
+- output parameter: o
+- input parameter: i
+- input-output parameter: O
+special wrappers
+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.
+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
+NOTE: It is likely that there will be changes w.r.t. the special wrappers.