Commits

Ronald Oussoren committed 848782e

Initial documentation for struct and opaque pointer wrappers

  • Participants
  • Parent commits 8a197c5

Comments (0)

Files changed (2)

File pyobjc-core/Doc/index.rst

    xcode
    blocks
    objc-gc
+   type-wrapper
    metadata/index
    api/index
    dev/index

File pyobjc-core/Doc/type-wrapper.rst

+Generated types for C types
+===========================
+
+.. py:currentmodule:: objc
+
+.. _type-struct::
+Structure types
+---------------
+
+Structure are generated by :func:`objc.createStructType` and represent
+a C structure, such as *NSPoint* or *CGRect*.
+
+Structure types are all separate types, directly inheriting from :type:`object`,
+and behave like a mutable variant of :func:`collections.namedtuple`.
+
+The rest of this section describes :class:`StructureType`, which defines the
+API of the structure types but does not exist as a real type.
+
+.. class::  StructureType(\**kwds)
+
+   A structure type.
+
+   .. data:: _fields
+      A tuple with the field names for this structure. Every name
+      in *_fields* is present as an attribute of instances of the type.
+
+   .. data:: __typestr__
+      The type encoding for this structure type
+
+   .. method:: __getitem__(idx)
+      Return the *idx*-th element of the object. This also supports
+      slices.
+
+   .. method:: __setitem__(idx, value)
+      Set the *idx*-th element of the object. This also supports
+      slice, but the assignment is not allowed to change the number
+      of elements.
+
+   .. method:: copy()
+      Returns a deep copy of the structure, that is all field values
+      that are instances of a structure types are copied as well.
+
+   .. method:: __pyobjc_copy__()
+      An alias for :meth:`copy`, for use by PyObjC.
+
+   .. method:: _replace(\**kwds)
+      First create a copy of the object, then use the keyword arguments
+      to replace the values of some attributes.
+
+   .. method:: _asdict()
+      Returns a dictionary where the keys are the values in :data:`_fields`
+      and the values are the corresponding attribute values.
+
+
+.. _type-opaque::
+Opaque pointer types
+--------------------
+
+Opaque pointer are created by :func:`objc.createOpaquePointerType` and represent
+opaque pointers or handles, such as values of type 'NSZone*'. Opaque pointers do
+not have further structure or behavior, they just exist as blobs of data that are
+returned from and passed to Objective-C functions or methods.
+
+The rest of this section describes :class:`OpaquePointerType`, which defines the
+API of the opaque pointer types but does not exist as a real type.
+
+.. class::  OpaquePointerType(cobject=None, c_void_p=None)
+   
+   An opaque pointer type. Values are usually created by the PyObjC bridge,
+   but can be created manually using one of the keyword arguments:
+
+   * *cobject*: A PyCapsule object with name "objc.__opaque__" that represents 
+     an opaque pointer value.
+   * *c_void_p*: An instance of :type:`ctypes.c_void_p` or 
+     :type:`int <__builtin__.int>` that represents an opaque pointer value.
+
+   .. data:: __typestr__
+      The type encoding for the opaque pointer type
+
+   .. data:: __pointer__
+      An integer with the raw pointer value
+
+   .. method:: __c_void_p__()
+      Returns a :type:`ctypes.c_void_p` instance with the raw pointer value
+
+   .. method:: __cobject__()
+      Returns a PyCapsule object with name "objc.__opaque__" representing
+      the raw pointer value.