|
|
||
|
|
|
|
We're hosted on:
Subversion hosting |
PyObjC - Notes on supported APIs and classes on Mac OS X
TODO: Add documentation about weak linking (see intro.txt). IntroductionThis document nees to be verified and split into parts. A generic note: Several methods and functions have a printf-like format string. Almost all formatting is supported by the bridge, except the '%n' specifier and specifiers for "long double" (such as '%Lg'). Neither should be needed when programming in Python. This document describes the restrictions with regard to supported APIs and classes on Mac OS X. In general, classes and global functions are used just as they are in Objective-C (e.g. the Apple developer documentation applies), but in some cases there are special considerations. Global functions that are not useful for Python programs are not callable from Python, as listed below. This document lists the exceptions to the basic rules. If a method uses pointers to return additional values, the Python wrapper for that method returns a tuple containing the original return value and the additional values. It is not necessary to provide values for pointer arguments unless their initial value is used by the method. Additionally, objc.NULL can be passed to denote that these arguments should be NULL rather than a pointer to allocated memory. This document is targeted at the latest supported version of Mac OS X (currently Mac OS X 10.4.x). Unless specifically noted, the same restrictions apply to earlier versions of Mac OS X. Earlier versions of Mac OS X have less extensive APIs, and PyObjC does not provide a compatibility layer except when necessary to support its own operation. This document is not entirely complete, but does cover the most used APIs. Classes not mentioned in this document may very well work properly. Frameworks that do not have PyObjC wrappers can be loaded at runtime using the objc.loadBundle, objc.loadBundleFunctions and objc.loadBundleVariables functions. In a future version of PyObjC, there will be an Objective-C header parser that can be used to automate this process and to generate wrappers. Addressbook frameworkThe global functions in this framework are not wrapped, as the same functionality can be accessed by using the object-oriented interface. AppKit frameworkThe callback methods for the NSSheet API's have a non-default signature and no fixed name. You should therefore explicitly specify the signature. This is done by calling the endSheetMethod function after defining your callback:
class MyClass(NSObject):
def mySheetDidEnd(self, panel, returnCode, contextInfo):
""" Actual implementation goes here """
pass
mySheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
mySheetDidEnd)
In Python 2.4, this may be written using a decorator as such:
class MyClass(NSObject):
@PyObjCTools.AppHelper.endSheetMethod
def mySheetDidEnd(self, panel, returnCode, contextInfo):
""" Actual implementation goes here """
pass
Unless otherwise noted, all contextInfo arguments are passed as integers, not as arbitrary pointers. Class NSApplicationNSModalSession objects are wrapped as opaque values. Two wrapper objects refer to the same session object if their ptr attributes are equal. Class NSBezierPath
Class NSBitmapImageRep
Class NSFont
Class NSGraphicsContext
Class NSLayoutManager
Class NSMatrix
Class NSMovieThe return value of QTMovie and the sole argument of initWithMovie: are Carbon.Qt.Movie objects. Class NSOpenGLContext
Class NSOpenGLPixelFormat
Class NSQuickDrawView
Class NSSimpleHorizontalTypesetter
Class NSView
Class NSWindow
Foundation frameworkNOTE: The list below is mostly based on scripts that find methods that can not be automatically handled by the bridge. We have not yet performed a manual search for such methods in the Cocoa documentation. The -forward:: and performv:: methods are not supported. Normal Python function invocation can be used instead. Structs are wrapped using a struct-like type. Struct members can be accessed using the field names as attributes, or they can be accessed as sequences for backwards compatibility. Class NSArray
Class NSAutoreleasePoolThe bridge automatically manages reference counts for you, but it is still required to make an autorelease pool available. In single-threaded programs that use NSRunLoop or are not long-lived, it is not necessary to explicitly manage NSAutoreleasePool, as NSRunLoop will push and pop one for each iteration, and PyObjC creates a NSAutoreleasePool in the thread it is imported in. When creating a large amount of objects in a loop, it may be useful to manually create a pool to reclaim memory as soon as possible. The proper idiom for this is:
while <test>:
pool = NSAutoreleasePool.alloc().init()
# ... Do work here ...
del pool
The previous pool must be deallocated before a new one is created. For example, the code below will silently leak memory:
while <test>:
# This pool is allocated BEFORE the previous is
# garbage collected, so the stack grows!
pool = NSAutoreleasePool.alloc().init()
# ... Do work here ...
In threads other than the main thread, as with Objective-C applications, it is necessary to create an NSAutoreleasePool as soon as possible before using other Objective-C objects. Class NSCoderThe following methods are not supported in the current version of PyObjC. This limitation will be lifted in a future version of the bridge.
The method decodeBytesWithoutReturnedLength: is not supported, use decodeBytesWithReturnedLength: instead. It is not possible to safely represent the return value of this method in Python. Class NSDataNSData subclasses support the Python buffer protocol, and any Python object that implements the Python buffer protocol (except str and unicode) are wrapped as an NSData subclass.
Class NSDecimalNumber and the NSDecimal typeNSDecimal is wrapped by a Python type. Creating an NSDecimal instance: NSDecimal(value) or NSDecimal(mantisssa, exponent, isNegative). Value can be a string, int or long (not a float because of the representation issues for floats). Converting an NSDecimal to a float or int: aDecimal.as_int() and aDecimal.as_float. Class NSDictionaryThe (undocumented) methods getKeys:, getObjects: and getObjects:andKeys: are not supported. Class NSException
Class NSFaultThe extraData argument/return value for -extraData and setTargetClassextraData: is represented as an integer. Class NSIndexSet
Class NSInvocationIn some versions of Mac OS X, NSInvocation doesn't work properly with structs that contain padding for alignment. Such structs are not used in the Mac OS X API, but may be present in 3rd party code. This leads to problems when forwardInvocation: is used to call a method that has such a struct as one of its arguments. Class NSMutableArray
Class NSMutableString
Class NSNetService
Class NSObject
Class NSScriptObjectSpecifier
Class NSStringObjective-C strings are represented as instances of a subclass of the Python type unicode. Since Python unicode objects are immutable, working with NSMutableString can be tricky. If you need to update the Python representation of the string, use aString.self(), which will be a new Python proxy for the same NSMutableString instance.
class NSThreadIt is safe to call from Objective-C to Python on any thread. It is safe to start new threads using the Python threading API and run non-Cocoa code on those threads.
InterfaceBuilder frameworkI (Ronald) have not found documentation for this framework, therefore the following methods with a "difficult" signature are not supported. Please let me know if there is documentation for this framework. Class IBObjCSourceParser
Class NSView
Class NSIBObjectData
Class IBObjectContainer
Class IBXMLDecoder
Class IBSplitScrollView
PreferencePanes frameworkThis framework seems to define useful classes like NSAuthorization and NSKeychain, but these are not documented and some useful methods have a hard signature. The only documented class, NSPreferencePane, is fully supported. |
|||||||||||||||||||||||||||
| Copyright © 2003 - 2008 The PyObjC Project |
|
|||||||||||||||||||||||||||
