Notes on supported APIs and classes on Mac OS X

Contents

TODO: Add documentation about weak linking (see intro.txt).

Introduction

This document describes the restrictions w.r.t. supported APIs and classes on Mac OS X. In general you can use classes and global functions just like in Objective-C (e.g. the Apple developer documentation applies), but in some cases there are special considerations.

We also do not provide access to global functions that are not useful for Python programs, those functions are 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. You don't have to pass values for those arguments, unless the method uses the values you pass in.

This document is targeted at the latest supported version of Mac OS X (currently Mac OS X 10.3.x); unless specifically noted the same restrictions apply to earlier versions of Mac OS X. Earlier versions of the OS have less extensive APIs, PyObjC does not provide a compatibility layer.

Frameworks not listed below are not wrapped by PyObjC, they can still be accessed although without access to constants and global functions defined by those frameworks.

This document is not entirely complete, but does cover the most used APIs.

Core objective-C runtime

Class Protocol

Addressbook framework

We do not provide access to the global functions in this framework, because the same functionality can be accessed by using the object-oriented interface.

AppKit framework

The 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)

Unless otherwise noted, all contextInfo arguments are passed as integers, not as arbitrary pointers.

Class NSApplication

NSModalSession objects are wrapped as opaque values. You can check if two wrapper objects refer to the same session object by comparing their ptr attributes.

Class NSBezierPath

Class NSBitmapImageRep

Class NSFont

Class NSGraphicsContext

Class NSLayoutManager

Class NSMatrix

Class NSMovie

The return value of QTMovie and the sole argument of initWithMovie: are QT.Movie objects. Using these methods requires the use of MacPython 2.3.

Class NSOpenGLContext

Class NSOpenGLPixelFormat

Class NSQuickDrawView

Class NSSimpleHorizontalTypesetter

Class NSView

Class NSWindow

Foundation framework

NOTE: 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:: method is not supported. It's functionality can be accessed using the python function apply. The performv:: method is also not supported, with a similar work-around.

Structs are wrapped using a struct-like type. They can be accessed using the field-names from Objective-C, or you can access them as sequences. Accessing them as sequences is necessary for backward compatibility and is deprecated.

Class NSArray

Class NSAutoreleasePool

The bridge automatically manages reference counts for you, but you're still required to make an autorelease pool available.

In simple, single-threaded GUI programs you don't have to do anything for this, because NSRunLoop does this for you and PyObjC creates an initial pool for the main thread.

If you create lots of Cocoa objects in a loop it can 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

That is, you must ensure that the previous pool is deallocated before you create a new one, the code below will silently leak memory:

while <test>:
        pool = NSAutoreleasePool.alloc().init()

        # ... Do work here ...

Class NSCoder

The 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 NSData

Class NSDecimalNumber and the NSDecimal type

NSDecimal is wrapped by a Python type. This type does not (yet) support mathematical operators, but does support explicit conversion to and from Python numbers.

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 NSDictionary

The (undocumented) methods getKeys:, getObjects: and getObjects:andKeys: are not supported.

Class NSException

Class NSFault

The extraData argument/return value for -extraData and setTargetClassextraData: is represented as an integer.

Class NSIndexSet

Class NSInvocation

In some versions of Mac OS X, NSInvocation doesn't work properly with structs that contain padding. Such structs are not used in the Mac OS X API, but may be present in 3th 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 NSSet

Class NSString

Objective-C strings are usually represented as instances of a subclass of the Python type unicode. It is possible to access the "real" Objective-C string by using the method NSString. This should only be necessary when dealing with mutable strings, or when you want to access methods that don't have a Python equivalent.

class NSThread

It 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 framework

I (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 framework

This 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.

ScreenSaver framework

Class ScreenSaverDefaults

This class is fully supported.

Class ScreenSaverView

This class is fully supported.