===============================================
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 nees to be verified and split into parts.

A generic note:

  Several methods and functions have a printf-like format string. Almost
  all formatting is supported by the bridge, except the '%n' specifier and
  specifiers for "long double" (such as '%Lg'). Neither should be needed when
  programming in Python.

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 <test>:
		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 <test>:
                # 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.
