=============================================== Notes on supported APIs and classes on Mac OS X =============================================== .. :author: Ronald Oussoren .. Contents:: TODO: Add documentation about weak linking (see intro.txt). Introduction ------------ 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. Core Objective-C runtime ------------------------ Addressbook framework --------------------- The global functions in this framework are not wrapped, as 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) 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 NSApplication ................... ``NSModalSession`` objects are wrapped as opaque values. Two wrapper objects refer to the same session object if their ``ptr`` attributes are equal. Class NSBezierPath .................. * ``getLineDash:count:phase:`` Use ``getLineDash_count_phase_(0)`` to get the length of the pattern, and then use ``getLineDash_count_phase_(actualCount)`` to fetch all information. Both return ``(pattern, actualCount, phase)``. The ``pattern`` is ``None`` when the input argument is ``0``. * ``appendBezierPathWithGlyphs:count:inFont:`` The first argument is a list of integers, count should be at most the length of the first argument. * ``appendBezierPathWithPoints:count:`` The first argument is a list of points, count should be at most the length of the first argument. * ``setAssociatedPoints:atIndex:`` Implementing this method in Python is not yet supported. Class ``NSBitmapImageRep`` .......................... * ``getBitMapDataPlanes`` This method is not supported (yet) * ``getTIFFCompressionTypes:count:`` This method is not supported (yet) * ``initWithBitmapDataPlanes:pixesWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:`` This method is not supported (yet) Class ``NSFont`` ................ * ``positionsForCompositeSequence:numberOfGlyphs:pointArray:`` This method is not supported (yet) Class ``NSGraphicsContext`` ........................... * ``focusStack`` This method is not supported. * ``setFocusStack`` This method is not supported. * ``graphicsPort`` This method is not yet supported, MacPython doesn't wrap ``CGContextRef`` at the moment. Class ``NSLayoutManager`` ......................... * ``getGlyphs:range:`` This method is not yet supported * ``getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:`` This method is not yet supported * ``getGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:bidiLevels:`` This method is not yet supported * ``rectArrayForCharacterRange:withinSelectedCharacterRange:inTextContainer:rectCount:`` This method is not yet supported * ``rectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:`` This method is not yet supported Class ``NSMatrix`` .................. * ``sortUsingFunction:context:`` Calling this method from Python is supported, overriding it in Python is not. The ``context`` can be an arbitrary python object. Class ``NSMovie`` ................. The return value of ``QTMovie`` and the sole argument of ``initWithMovie:`` are ``Carbon.Qt.Movie`` objects. Class ``NSOpenGLContext`` ......................... * ``getValues:forParameter:`` This method is not yet supported. * ``setValues:forParameter:`` This method is not yet supported. * ``setOffScreen:width:height:rowbytes:`` This method is not yet supported. * ``CGLContextObj`` This method is not yet supported. Class ``NSOpenGLPixelFormat`` ............................. * ``getValues:forAttribute:forVirtualScreen:`` This method is not yet supported Class ``NSQuickDrawView`` ......................... * ``qdPort`` This method returns an instance of type ``Carbon.Qd.GrafPort``. Class ``NSSimpleHorizontalTypesetter`` ...................................... * ``baseOfTypesetterGlyphInfo`` This method is not yet supported * ``layoutGlyphsInHorizontalLineFragment:baseline:`` This method is not yet supported Class ``NSView`` ................ * ``sortSubviewsUsingFunction:context:`` Calling this method from Python is supported, overriding it in Python is not. The ``context`` can be an arbitrary python object. Class ``NSWindow`` .................. * ``graphicsPort`` This method is not yet supported * ``initWithWindowRef:`` This method is not yet supported * ``windowRef`` This method is not yet supported 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::`` 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`` ................. * ``getObjects:`` This method is not supported, accessing the objects using the usual accessor methods is just as efficient as using this method. * ``getObjects:inRange:`` This method is not supported, accessing the objects using the usual accessor methods is just as efficient as using this method. * ``sortedArrayUsingFunction:context:`` and ``sortedArrayUsingFunction:context:hint`` These methods can be called from Python, but Python can not override them. This limitation will be lifted in a future version of PyObjC. The ``context`` can be an arbitrary python object. * ``addObserver:toObjectsAtIndexes:forKeyPath:options:context:`` The context is an integer, not a ``void*``. Class ``NSAutoreleasePool`` ........................... The 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 : 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 : # 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 ``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. * ``encodeValuesOfObjCType:`` Use multiple calls to ``encodeValueOfObjCType:at:`` instead. * ``decodeValuesOfObjCType:`` Use multiple calls to ``decodeValueOfObjCType:at:`` instead. Note that this will not read back data that was written using ``encodeValuesOfObjCType:``. 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`` ................ NSData 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. * ``initWithBytesNoCopy:length:`` This method is not supported, use ``initWithBytes:length:`` instead. * ``initWithBytesNoCopy:length:freeWhenDone:`` This method is not supported, use ``initWithBytes:length:`` instead. * ``dataWithBytesNoCopy:length:`` This method is not supported, use ``dataWithBytes:length:`` instead. * ``dataWithBytesNoCopy:length:freeWhenDone:`` This method is not supported, use ``dataWithBytes:length:`` instead. * ``deserializeAlignedBytesLengthAtCursor:`` This is a deprecated method, see Apple documentation. * ``deserializeBytes:length:atCursor:`` This is a deprecated method, see Apple documentation. * ``deserializeDataAt:ofObjCType:atCursor:context:`` This is a deprecated method, see Apple documentation. * ``deserializeIntAtCursor:`` This is a deprecated method, see Apple documentation. * ``deserializeInts:count:atCursor:`` This is a deprecated method, see Apple documentation. * ``deserializeInts:count:atIndex:`` This is a deprecated method, see Apple documentation. * ``getBytes:``, ``getBytes:length:``, ``getBytes:range:`` Use ``bytes`` instead, and then use subscripting to get the desired range. Class ``NSDecimalNumber`` and the ``NSDecimal`` type .................................................... NSDecimal 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 ``NSDictionary`` ...................... The (undocumented) methods ``getKeys:``, ``getObjects:`` and ``getObjects:andKeys:`` are not supported. Class ``NSException`` ..................... * ``raise:format:``, ``raise:format:arguments:`` These methods are not supported because they accept a variable number of arguments. Use Python's ``%`` operator to format the message. A future version of PyObjC may be able to parse format strings and do the right thing. Class ``NSFault`` ................. The ``extraData`` argument/return value for ``-extraData`` and ``setTargetClassextraData:`` is represented as an integer. Class ``NSIndexSet`` .................... * ``getIndexes:maxCount:inIndexRange:`` The usage is:: (realCount, indices, newRange) = obj.getIndexes_maxCount_inIndexRange( maxCount, inRange) Class ``NSInvocation`` ...................... In 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`` ........................ * ``sortUsingFunction:context:``, ``sortUsingFunction:context:range:`` Calling this method from Python is supported, overriding it in a subclass is not. This limitation will be fixed in a later version of PyObjC. The ``context`` can be an arbitrary Python object. Class ``NSMutableString`` ......................... * ``appendFormat:`` This method is not supported because it accepts a variable number of arguments. Use Python's ``%`` operator to format strings. Class ``NSNetService`` ...................... * ``addresses`` When calling this from Python this methods returns a tuple of address info tuples, like the values returned by ``socket.getpeeraddr()``. Class ``NSObject`` .................. * ``observationInfo``, ``setObservationInfo:`` These methods can be used from Python, but the ``observationInfo`` is represented by an integer instead of ``void*``. This probably makes it impossible to do anything useful with these methods. * ``addObserver:forKeyPath:options:context:`` The context is an integer. * ``observeValueForKeyPath:ofObject:change:context:`` The context is an integer * ``methodForSelector:``, ``instanceMethodForSelector:`` These methods return instances of ``objc.IMP``. The major difference from Objective-C is that the selector argument is omitted. In other words, using an ``objc.IMP`` is the same as using an unbound selector; ``self`` must be passed explicitly as the first argument, and the other arguments are passed as usual. WARNING: This interface is experimental and might change in a future version of PyObjC. Class ``NSScriptObjectSpecifier`` ................................. * ``indicesOfObjectsByEvaluatingWithContainer:count:`` Implementing this in Python is not supported yet. We're looking for a way to avoid leaking the returned buffer, as we cannot return a pointer to an internal data-structure. Class ``NSString`` .................. Objective-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. * ``initWithCharactersNoCopy:length:freeWhenDone:`` This method is unsupported because we can not guarantee that the buffer will be available as long as the string is. Use ``initWithCharacters:`` instead. * ``getCharacters:`` and ``getCharacters:range:`` These methods are not supported at the moment. This limitation will be lifted in a future version of the bridge. * ``getCString:maxLength:range:remainingRange:`` and ``getCString:maxLength:`` Calling these methods from Python is supported, overriding them from Python is not. This limitation will be lifted in a future version of the bridge. * ``getCString:`` This method is not supported. Use ``getCString:maxLength:`` instead (using the length of the string as the maximum length). This limitation will be lifted in a future version of the bridge. * ``stringWithFormat:``, ``initWithFormat:``, ``initWithFormat:locale:``, ``stringByAppendingFormat:`` These methods are not supported because they accept a variable number of arbitrarily typed arguments. Use Python's ``%`` operator to format strings. A future version of PyObjC may be able to parse format strings and do the right thing here. * ``initWithFormat:arguments:``, ``initWithFormat:locale:arguments:`` These are also not supported, with the same workaround. 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. * ``detachNewThreadSelector:toTarget:withObject:`` As with Objective-C, make sure to create an ``NSAutoreleasePool`` in this the detached thread. 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`` ............................ * ``parseClass:`` Class ``NSView`` ................ * ``objectAtPoint:rect:`` Defined in a category on ``NSView``. Class ``NSIBObjectData`` ........................ * ``restoreFromObjectDataInfo:`` * ``snapshotIntoObjectDataInfo:`` Class ``IBObjectContainer`` ........................... * ``decodeObjectToIntMapTableForKey:fromCoder:alwaysCreate:`` * ``decodeObjectToObjectMapTableForKey:fromCoder:alwaysCreate:`` Class ``IBXMLDecoder`` ...................... * ``allocObjectWithClassName:`` Class ``IBSplitScrollView`` ........................... * ``getMinimumX:maximumX:`` 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.