Notes on supported APIs and classes on MacOS 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 MacOS X. In general you can use classes and global functions just like in Objective-C (e.g. the Apple developer documentaton applies), but in some cases there are special considerations.

We also do not provide access to global functions that are not usefull for Python programs, those functions are listed below.

This document list the examples 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 target at the latest supported version of MacOS X (currenlty MacOS X 10.2.x), unless specifically noted the same restrictions apply to earlier versions of MacOS 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 that 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 automaticly 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 simular 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 depericated.

Class NSArray

Class NSBundle

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 NSFault

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

Class NSIndexSet

Class NSInvocation

In some versions of MacOS X, NSInvocation doesn't work properly with structs that contain padding. Such structs are not used in the MacOS 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 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

When you're using Python 2.3 or later it is save to call from Objective-C to Python on any thread. Otherwise you must be sure that the current thread has acquired the GIL. This means you shouldn't use API's that will call back on an arbitrary thread unless you're using Python 2.3 or later. It is safe to start new threads using the Python threading API and run non-Cocoa code on those threads, PyObjC contains code that acquires the GIL whenever the runloop in the main thread runs.

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 usefull classes like NSAuthorization and NSKeychain, but these are not documented and some usefull 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.