TODO: Add documentation about weak linking (see intro.txt).
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.
descriptionForClassMethod:
, descriptionForInstanceMethod
These methods are not supported, protocols are hardly ever used explicitly
in Cocoa therefore this should not be a problem.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.
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.
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.
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.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)NSFont
positionsForCompositeSequence:numberOfGlyphs:pointArray:
This method is not supported (yet)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.NSLayoutManager
getGlyphs:range:
This method is not yet supportedgetGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:
This method is not yet supportedgetGlyphsInRange:glyphs:characterIndexes:glyphInscriptions:elasticBits:bidiLevels:
This method is not yet supportedrectArrayForCharacterRange:withinSelectedCharacterRange:inTextContainer:rectCount:
This method is not yet supportedrectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:
This method is not yet supportedNSMatrix
sortUsingFunction:context
Calling this method from Python is supported, overriding it in Python
is not. The context
can be an arbitrary python object.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.
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.NSOpenGLPixelFormat
getValues:forAttribute:forVirtualScreen:
This method is not yet supported
initWithAttributes:
This method is not yet supported
NSQuickDrawView
qdPort
This method returns an instance from a type Carbon.QuickDraw. This requires MacPython.
NSSimpleHorizontalTypesetter
baseOfTypesetterGlyphInfo
This method is not yet supportedlayoutGlyphsInHorizontalLineFragment:baseline:
This method is not yet supportedNSView
sortSubviewsUsingFunction:context:
Calling this method from Python is supported, overriding it in Python
is not. The context
can be an arbitrary python object.NSWindow
graphicsPort
This method is not yet supportedinitWithWindowRef:
This method is not yet supportedwindowRef
This method is not yet supportedNOTE: 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.
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.
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.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.
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.NSDictionary
The (undocumented) methods getKeys:
, getObjects:
and
getObjects:andKeys:
are not supported.
NSFault
The extraData
argument/return value for -extraData
and
setTargetClassextraData:
is represented as an integer.
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.
NSNetService
addresses
When calling this from Python this methods returns a tuple of adress-info
tuples, like the values returned by socket.getpeeraddr()
.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.NSSet
initWithObjects:
, setWithObjects:
This method is not supported, use initWithArray:
instead.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.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.
IBObjCSourceParser
parseClass:
NSView
objectAtPoint:rect:
Defined in a catagory on NSView
.NSIBObjectData
restoreFromObjectDataInfo:
snapshotIntoObjectDataInfo:
IBObjectContainer
decodeObjectToIntMapTableForKey:fromCoder:alwaysCreate:
decodeObjectToObjectMapTableForKey:fromCoder:alwaysCreate:
IBXMLDecoder
allocObjectWithClassName:
IBSplitScrollView
getMinimumX:maximumX:
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.
ScreenSaverDefaults
This class is fully supported.
ScreenSaverView
This class is fully supported.