=============================================== 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 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 .............. * ``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 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 .................. * ``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 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. * ``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.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 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`` ................. * ``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. * ``addObserver:toObjectsAtIndexes:forKeyPath:options:context:`` The context is an integer, not a ``void*``. 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 : 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 : 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. * ``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 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. 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`` ..................... * ``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. 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. 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`` ........................ * ``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 with Objective-C is that you don't have to, or even can, pass the selector to the IMP. In other words, the interface is the same as for unbound instance methods: you have to pass ``self`` and the method arguments. 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 ``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 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 arguments. Use Python's ``%`` operator to format strings. * ``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:`` Make sure that you've either created a thread from Python using the ``thread`` or ``threading`` module, or called ``objc.enableThreading`` before using this API. This is necessary to enable threading in the Python interpreter. We don't do this by default because this has a negative performance impact. 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. ScreenSaver framework --------------------- Class ``ScreenSaverDefaults`` ............................. This class is fully supported. Class ``ScreenSaverView`` ......................... This class is fully supported.