============================================== Notes on supported APIs and classes on MacOS X ============================================== .. :author: Ronald Oussoren .. 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 .............. * ``descriptionForClassMethod:``, ``descriptionForInstanceMethod`` These methods are not supported, protocols are hardly ever used explicitly in Cocoa therefore this should not be a problem. 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 .................. * ``getLineDash:count:phase:`` This method is not supported, I (Ronald) could not find a way to detect the required size for the pattern buffer. * ``appendBezierPathWithGlyphs:count:inFont:`` The first argument is a list of integers, count should be at most the lenght of the first argument. * ``appendBezierPathWithPoints:count:`` The first argument is a list of points, count should be at most the lenght 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:bitPerSample: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 QT.Movie objects. Using these methods requires the use of MacPython 2.3. 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. Class ``NSOpenGLPixelFormat`` ............................. * ``getValues:forAttribute:forVirtualScreen:`` This method is not yet supported * ``initWithAttributes:`` This method is not yet supported Class ``NSQuickDrawView`` ......................... * ``qdPort`` This method returns an instance from a type Carbon.QuickDraw. This requires MacPython. 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 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`` ................. * ``initWithObjects:``, ``arrayWithObjects:`` These methods are not supported, use ``initWithArray:`` instead. * ``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 you cannot override them from Python. This limitation will be lifted in a future version of PyObjC. The ``context`` can be an arbitrary python object. Class ``NSBundle`` .................. * ``bundleForClass:`` This method does not work correctly for classes defined in Python, these all seem be defined in the ``mainBundle()``. As a workaround you can use the function ``objc.pluginBundle(name)`` to find the NSBundle for your Python based bundle. See Examples/PrefPane for an example of its usage. 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 that won't work if your trying to 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`` ................ * ``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 depricated method, see Apple documentation. * ``deserializeBytes:length:atCursor:`` This is a depricated method, see Apple documentation. * ``deserializeDataAt:ofObjCType:atCursor:context:`` This is a depricated method, see Apple documentation. * ``deserializeIntAtCursor:`` This is a depricated method, see Apple documentation. * ``deserializeInts:count:atCursor:`` This is a depricated method, see Apple documentation. * ``deserializeInts:count:atIndex:`` This is a depricated method, see Apple documentation. * ``getBytes:``, ``getBytes:length:``, ``getBytes:range:`` Use ``bytes`` instead, and then use subscripting to get the desired range. 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`` ........................ * ``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 ``NSNetService`` ...................... * ``addresses`` When calling this from Python this methods returns a tuple of adress-info tuples, like the values returned by ``socket.getpeeraddr()``. 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 datastructure. Class ``NSSet`` ............... * ``initWithObjects:``, ``setWithObjects:`` This method is not supported, use ``initWithArray:`` instead. 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. * ``initWithCharactersNoCopy:length:freeWhenDone:`` This method is unsupported because we cannot guarantee that the buffer wil 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 liften 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 liften 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 liften in a future version of the bridge. 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 catagory 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 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.