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

NSPoint is a tuple of 2 floats, or use AppKit.NSMakePoint(x, y).

NSSize is a tuple of 2 floats, or use AppKit.NSMakeSize(h, w).

NSRect is a tuple of an NSPoint and an NSSize, or use AppKit.NSMakeRect(x, y, h, w).

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.

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 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 NSMutableArray

Class NSNetService

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.

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.