============================================== 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 ---------------- 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 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. 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`` ................. * ``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 ``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 ``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`` .................... * ``getIndexes:maxCount:inIndexRange:`` The usage is:: (realCount, indices, newRange) = obj.getIndexes_maxCount_inIndexRange( maxCount, inRange) 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`` ........................ * ``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 ``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 usefull 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 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. 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. * ``detachNewThreadSelector:toTarget:withObject:`` This method can safely be used when using Python 2.3 or later, on earlier releases this will crash the interpreter. 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 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.