pyobjc / pyobjc-framework-Quartz / Doc / api-notes-Quartz.txt

API Notes: Quartz frameworks


This document describes special considerations for the PyObjC based Quartz

Quartz vs. CoreGraphics

The PyObjC bindings for the Quartz related frameworks, including CoreGraphics
and QuartzComposer are in the Python package "Quartz". When you use the
system version of Python there's also a package named "CoreGraphics".  This
is Apple's closed-source binding of CoreGraphics, which is not a direct
mapping of the Quartz API's but includes some convenience APIs that are not 
present in the C API. 

The PyObjC bindings for Quartz are not compatible with the CoreGraphics 
Python package by Apple.


The prefered way to import from packages in these bindings is::

   from Quartz import *

It is also possible to import directly from subwrappers (such
as ``Quartz.CoreGraphics``), but it better to import from the toplevel
to ensure you'll get all relevant definitions.


The ``userinfo`` for ``CGDataConsumerCreate``, ``CGDataProviderCreate``,
``CGDataProviderCreateDirect``, ``CGDataProviderCreateDirectAccess``,
``CGDataProviderCreateSequential``, ``CGDataProviderCreateWithData``,
``CGFunctionCreate``, ``CGRegisterScreenRefreshCallback``, 
``CGReleaseScreenRefreshRects``, ``CGScreenRegisterMoveCallback``,
``CGScreenUnregisterMoveCallback``, ``CGUnregisterScreenRefreshCallback``,
``CGPDFDictionaryApplyFunction``, ``CGPathApply``, ``CGPatternCreate``,
``CGEventTapCreate``, ``CGEventTapCreateForPSN``, ``CGPDFOperatorTableSetCallback`` and ``CGPSConverterCreate``  can be any Python object.

The function arguments for these functions can be any Python callable, 
including bound methods. Functions mentioned earlier that have a struct with
callback functions take in tuple with those callbacks in Python.

``CGEventTapCreate`` and ``CGEventTapCreateForPSN`` leak some memory when they
are called. This is needed to avoid memory management problems. It is therefore
advisable not to call these functions, are at least call them a small number
of times.

``CGPatternCreate``: the callback argument is a single function: the ``drawPattern`` callback.

``CGDataProviderCreateWithData``: the release callback can be ``None``. If it is not ``None`` it 
must be a function with 1 argument: the ``info`` object.

``CGPDFOperatorTableSetCallback`` is not supported at the moment.


This function is not supported because the lowlevel "CMProfileRef" type is
not wrappped by PyObjC.


This value isn't actually a constant and can therefore not be wrapped by
PyObjC. Use ``CGMainDisplayID()`` instead.

``CGWindowListCreate``, ``CGWindowListCreateDescriptionFromArray``, ``CGWindowListCreateImageFromArray``

This function is documented to return a "CFArray of CGWindowID". This specific type cannot be represented by
PyObjC, therefore the (manually wrapped) function returns a tuple of CGWindowID values instead.

For the same reason ``CGWindowListCreateDescriptionFromArray``, ``CGWindowListCreateImageFromArray`` are
manually wrapped and take a tuple of WindowID values as an argument.


The easiest way to use this function is to pass ``None`` as the buffer argument, that way Quartz will create the
buffer for you. If you do want direct access to the buffer you'll have to create a writable buffer, for example
like so::

    bytes = array.array('B', (0 for i in xrange(100*80*4)))
    ctx = CGBitmapContextCreate(bytes, 100, 80, 8, 400, CGColorSpaceCreateDeviceRGB(), kCGImageAlphaPremultipliedLast)

This creates a context for a 100 pixels by 80 pixels image with a RGBA colorspace.

Note that there limitations on the kinds of context's you can create, see the Apple documentation about supported
pixel formats for the details on that.


This function has an output buffer of indetermined size. You cannot pass ``None`` as the value of that buffer but have
to explicitly specify a writable output buffer (such an ``array.array`` or the right type and size).

Low-level PDF support

Low-level PDF support in the CoreGraphics framework (such as the ``PDFArrayRef``
type) are barely supported by PyObjC and these API's are currently not covered 
by PyObjC's testsuite.

Adding support for these API's is on the todo-list, but adding proper support
requires work because the ``PDFArrayRef`` type (and simular types) is not
a CoreFoundation based type.


The API's related to CGPSConverter are not supported at the moment.


* ``-render:toBitmap:rowBytes:bounds:format:colorSpace``

  You must pass a writable buffer of the right size to this method (such as 
  a properly sized instance of ``array.array``.


This function requires a manual wrapper and is not supported yet.


This function requires a manual wrapper and is not supported yet.


This function requires a manual wrapper and is not supported yet.


Pixel format attributes of this type are not supported.