[PyObjC-svn] r2386 - trunk/pyobjc/pyobjc-core/Doc/lib
[email protected] Sun, 03 Jan 2010 08:15:11 -0600
| Newsgroups | gmane.comp.python.pyobjc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: ronaldoussoren
Date: Sun Jan 3 08:15:11 2010
New Revision: 2386
Log:
Add all public items in the objc module to the documentation, even if
most of them are documented as 'TODO'.
Modified:
trunk/pyobjc/pyobjc-core/Doc/lib/module-objc.rst
Modified: trunk/pyobjc/pyobjc-core/Doc/lib/module-objc.rst
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/lib/module-objc.rst (original)
+++ trunk/pyobjc/pyobjc-core/Doc/lib/module-objc.rst Sun Jan 3 08:15:11 2010
@@ -15,11 +15,77 @@
utility functions and types that make it easier to integrate Python
and Objective-C code.
-Accessing classes
-.................
+The module :mod:`objc` defines a number of functions whose names start with
+an underscore. Those functions are private and should not be used, they can
+be removed from release without warning.
-.. function:: lookUpClass(classname)
+NOTE: This document is currently mostly an exhaustive list of stuff and
+needs to be reorganised once I've filled in the technical details.
+
+Debugging
+.........
+
+.. function:: setVerbose(yesOrNo)
+
+ When the argument is :const:`True` the bridge will log more information.
+
+ This currently results in output on the standard error stream whenever
+ an exception is translated from Python to Objective-C.
+
+
+.. function:: getVerbose()
+
+ Returns the current value of the verbose flag.
+
+
+Tweaking behaviour
+..................
+
+.. function:: setUseKVOForSetattr
+
+ TODO
+
+.. function:: setHideProtected(yesOrNo)
+
+ When the argument is :const:`True` protected methods of an Objective-C
+ class will not be included in the output of :func:`dir`. Protected methods
+ are those whose selector starts with an underscore.
+
+ This option is on by default.
+
+.. function:: setStrBrigeEnabled
+ TODO
+
+ This function is not available in Python 3.x
+
+.. function:: getStrBridgeEnabled
+
+ TODO
+
+ This function is not available in Python 3.x
+
+
+Utilities
+..........
+
+.. function:: allocateBuffer
+
+ TODO
+
+.. function:: CFToObject
+
+ TODO
+
+.. function:: ObjectToCF
+
+ TODO
+
+
+Accessing classes and protocols
+...............................
+
+.. function:: lookUpClass(classname)
:param classname: the name of an Objective-C class
:type classname: string
@@ -27,9 +93,102 @@
:raise: :exc:`objc.nosuchclass_error` when the class does not exist
-Utility functions
+.. function:: getClassList()
+
+ :return: a list of a classes known to the Objective-C runtime
+
+
+.. function:: protocolsForClass
+
+ TODO
+
+.. function:: protocolsForProcess
+
+ TODO
+
+.. function:: listInstanceVariables
+
+ TODO
+
+.. function:: getInstanceVariable
+
+ TODO
+
+.. function:: setInstanceVariable
+
+ TODO
+
+.. function:: protocolNamed
+
+ TODO
+
+.. exception:: ProtocolError
+
+ TODO
+
+
+
+
+
+Dynamic modification of classes
+...............................
+
+.. function:: classAddMethods
+
+ TODO
+
+.. function:: classAddMethod
+
+ TODO (Lib/objc/_category)
+
+.. class:: Category
+
+ TODO (Lib/objc/_category)
+
+
+Plugin bundles
+..............
+
+
+.. function:: currentBundle
+
+ TODO
+
+.. function:: registerPlugin
+
+ TODO: Deprecated
+
+.. function:: pluginBundle
+
+ TODO: Deprecated
+
+
+Memory management
.................
+PyObjC automaticly manages Cocoa reference counts for you, the functions
+in this section help in finetuning this behaviour.
+
+.. function:: recycleAutoreleasePool()
+
+ Flush the NSAutoreleasePool that PyObjC creates on import. Use this
+ before entering the application main loop when you do a lot of work
+ before starting the main loop.
+
+.. function:: removeAutoreleasePool()
+
+ Use this in plugin bundles to remove the release pool that PyObjC creates
+ on import. In plugins this pool will interact in unwanted ways with the
+ embedding application.
+
+
+Test support
+............
+
+The functions in this section are present as support code for PyObjC's
+unittests and are not part of the stable API. Please let us know if you
+use these functions in your code.
+
.. function:: splitSignature(typestring)
Split an encoded Objective-C signature string into the
@@ -41,4 +200,515 @@
:rtype: list of byte strings
+.. function:: splitStruct(typestring)
+
+ TODO.
+
+.. function:: repythonify
+
+ TODO
+
+Framework wrappers
+..................
+
+.. function:: setSignatureForSelector
+
+ TODO
+
+.. function:: pyobjc_id
+
+ TODO
+
+.. function:: loadBundle
+
+ TODO
+
+.. function:: registerCFSignature
+
+ TODO
+
+.. function:: loadBundleVariables
+
+ TODO
+
+.. function:: loadSpecialVar
+
+ TODO
+
+.. function:: loadBundleFunctions
+
+ TODO
+
+.. function:: _loadFunctionList
+
+ TODO
+
+.. function:: createOpaquePointerType
+
+ TODO
+
+.. function:: createStructType
+
+ TODO
+
+.. function:: registerMetaDataForSelector
+
+ TODO
+
+.. function:: parseBridgeSupport
+
+ TODO
+
+
+.. function:: registerListType
+
+ TODO (Lib/objc/_bridges)
+
+.. function:: registerMappingType
+
+ TODO (Lib/objc/_bridges)
+
+.. function:: initFrameworkWrapper
+
+ TODO
+
+.. function:: addConvenienceForSelector
+
+ TODO
+
+.. function:: addConvenienceForClass
+
+ TODO
+
+Types
+-----
+
+.. class:: objc_class
+
+ TODO: the meta class for Objective-C classes
+
+.. class:: objc_object
+
+ TODO: the root class for Objective-C classes
+
+.. class:: pyobjc_unicode
+
+ TODO: proxy for :ctype:`NSString*`
+
+.. class:: selector
+
+ TODO: an Objective-C method reference
+
+.. class:: FSRef
+
+ TODO: proxy for :ctype:`FSRef`
+
+.. class:: FSSPec
+
+ TODO: proxy for :ctype:`FSSpec`
+
+.. class:: ivar
+
+ TODO: an instance variable reference
+
+.. class:: informal_protocol
+
+ TODO: add section about protocols
+
+.. class:: formal_protocol
+
+ TODO: add section about protocols
+
+
+.. class:: varlist
+
+ TODO: a varlist is a list of indeteriminate length
+
+.. class:: function
+
+ TODO: a global function in a framework.
+
+.. class:: IMP
+
+ TODO: proxy for :ctype:`IMP`
+
+.. class:: super
+
+ This is a subclass of :class:`super <__builtin__.super>` that works
+ properly for Objective-C classes as well as regular Python classes.
+
+ The statement :samp:`from {Framework} import \*` will replace the
+ regular :class:`super <__builtin__.super>` by this class.
+
+Constants
+---------
+
+.. data:: nil
+
+ Alias for :const:`None`, for easier translation of existing Objective-C
+ code.
+
+.. data:: YES
+
+ Alias for :const:`True`, for easier translation of existing Objective-C
+ code.
+
+.. data:: NO
+
+ Alias for :const:`False`, for easier translation of existing Objective-C
+ code.
+
+.. data:: NULL
+
+ TODO: add description of pass by reference arguments and the
+ difference between None and NULL
+
+.. data:: MAC_OS_X_VERSION_MAX_ALLOWED
+
+ The value of ``MAC_OS_X_VERSION_MAX_ALLOWED`` when PyObjC was
+ compiled.
+
+.. data:: MAC_OS_X_VERSION_MIN_REQUIRED
+
+ The value of ``MAC_OS_X_VERSION_MIN_REQUIRED`` when PyObjC was
+ compiled.
+
+.. data:: MAC_OS_X_VERSION_10_N
+
+ There are currently 6 constants of this form, for ``N`` from 1 to 6,
+ and these have the same value as the Objective-C constant of the same
+ name.
+
+.. data:: platform
+
+ This always has the value ``"MACOSX"``.
+
+
+
+Objective-C type strings
+------------------------
+
+The Objective-C runtime and the PyObjC bridge represent the types of
+instance variables and methods arguments and return values as a string
+with a compact representation. The Python representation of that string is
+a byte string (that is type :class:`bytes` in Python 3.x and :class:`str`
+in Python 2.x).
+
+Basic types
+............
+
+The representation for basic types is a single character, the table below
+lists symbolic constants in the for those constants.
+
+======================== =================================================
+Name Objective-C type
+======================== =================================================
+:const:`_C_ID` :ctype:`id` (an Objective-C instance)
+------------------------ -------------------------------------------------
+:const:`_C_CLASS` an Objective-C class
+------------------------ -------------------------------------------------
+:const:`_C_SEL` a method selector
+------------------------ -------------------------------------------------
+:const:`_C_CHR` :ctype:`char`
+------------------------ -------------------------------------------------
+:const:`_C_UCHR` :ctype:`unsigned char`
+------------------------ -------------------------------------------------
+:const:`_C_SHT` :ctype:`short`
+------------------------ -------------------------------------------------
+:const:`_C_USHT` :ctype:`unsigned short`
+------------------------ -------------------------------------------------
+:const:`_C_BOOL` :ctype:`bool` (or :ctype:`_Bool`)
+------------------------ -------------------------------------------------
+:const:`_C_INT` :ctype:`int`
+------------------------ -------------------------------------------------
+:const:`_C_UINT` :ctype:`unsigned int`
+------------------------ -------------------------------------------------
+:const:`_C_LNG` :ctype:`long`
+------------------------ -------------------------------------------------
+:const:`_C_ULNG` :ctype:`unsigned long`
+------------------------ -------------------------------------------------
+:const:`_C_LNG_LNG` :ctype:`long long`
+------------------------ -------------------------------------------------
+:const:`_C_ULNG_LNG` :ctype:`unsigned long long`
+------------------------ -------------------------------------------------
+:const:`_C_FLT` :ctype:`float`
+------------------------ -------------------------------------------------
+:const:`_C_DBL` :ctype:`double`
+------------------------ -------------------------------------------------
+:const:`_C_VOID` :ctype:`void`
+------------------------ -------------------------------------------------
+:const:`_C_UNDEF` "other" (such a function)
+------------------------ -------------------------------------------------
+:const:`_C_CHARPTR` C string (:ctype:`char*`)
+------------------------ -------------------------------------------------
+:const:`_C_NSBOOL` :ctype:`BOOL`
+------------------------ -------------------------------------------------
+:const:`_C_UNICHAR` :ctype:`UniChar`
+------------------------ -------------------------------------------------
+:const:`_C_CHAR_AS_TEXT` :ctype:`char` when uses as text or a byte array
+------------------------ -------------------------------------------------
+:const:`_C_CHAR_AS_INT` :ctype:`int8_t` (or :ctype:`char` when
+ used as a number)
+======================== =================================================
+
+The values :const:`_C_NSBOOL`, :const:`_C_UNICHAR`, :const:`_C_CHAR_AS_TEXT`
+and :const:`_C_CHAR_AS_INT` are inventions of PyObjC and are not used in
+the Objective-C runtime.
+
+Complex types
+..............
+
+More complex types can be represented using longer type strings:
+
+* a pointer to some type is :const:`_C_PTR` followed by the type string
+ of the pointed-to type.
+
+* a bitfield in a structure is represented as :const:`_C_BFLD` followed
+ by an integer with the number of bits.
+
+ Note that PyObjC cannot convert bitfields at this time.
+
+* a C structure is represented as :const:`_C_STRUCT_B` followed by the
+ struct name, followed by :const:`'='`, followed by the encoded types of
+ all fields followed by :const:`_C_STRUCT_E`. The field name (including the
+ closing equals sign) is optional.
+
+* a C union is represented as :const:`_C_UNION_B` followed by the
+ struct name, followed by :const:`'='`, followed by the encoded types of
+ all fields followed by :const:`_C_UNION_E`. The field name (including the
+ closing equals sign) is optional.
+
+ Note that PyObjC cannot convert C unions at this time.
+
+* a C array is represented as :const:`_C_ARY_B` followed by an integer
+ representing the number of items followed by the encoded element type,
+ followed by :const:`_C_ARY_E`.
+
+* The C construct 'const' is mapped to :const:`_C_CONST`, that is a
+ :ctype:`const char*` is represented as ``_C_CONST + _C_CHARPTR``.
+
+Additional annotations for method and function arguments
+........................................................
+
+Method arguments can have prefixes that closer describe their functionality.
+Those prefixes are inheritted from Distributed Objects are not used by the
+Objective-C runtime, but are used by PyObjC.
+
+* When a pointer argument is an input argument it is prefixed by
+ :const:`_C_IN`.
+
+* When a pointer argument is an output argument it is prefixed by
+ :const:`_C_OUT`.
+
+* When a pointer argument is an input and output argument it is prefixed
+ by :const:`_C_INOUT`.
+
+* Distributed objects uses the prefix :const:`_C_BYCOPY` to tell that a
+ value should be copied to the other side instead of sending a proxy
+ reference. This is not used by PyObjC.
+
+* Distributed objects uses the prefix :const:`_C_ONEWAY` on the method return
+ type to tell that the method result is not used and the caller should not
+ wait for a result from the other side. This is not used by PyObjC.
+
+When a pointer argument to a function prefixed by :const:`_C_IN`,
+:const:`_C_OUT` or :const:`_C_INOUT` the brige assumes that it is a pass by
+reference argument (that is, a pointer to a single value), unless other
+information is provided to the bridge.
+
+TODO: Write how to write Objective-C code to ensure that the right prefixes
+are added by the compiler.
+
+Special encoded types
+.....................
+
+The table below shows constants for a number of C types that are used
+in Cocoa but are not basic C types.
+
+ ======================= ==============================
+ Constant Objective-C type
+ ======================= ==============================
+ :const:`_C_CFTYPEID` :ctype:`CFTypeID`
+ ----------------------- ------------------------------
+ :const:`_C_NSInteger` :ctype:`NSInteger`
+ ----------------------- ------------------------------
+ :const`:_C_NSUInteger` :ctype:`NSUInteger`
+ ----------------------- ------------------------------
+ :const:`_C_CFIndex` :ctype:`CFIndex`
+ ----------------------- ------------------------------
+ :const:`_C_CGFloat` :ctype:`CGFloat`
+ ----------------------- ------------------------------
+ :const:`_sockaddr_type` :ctype:`struct sockaddr`
+ ======================= ==============================
+
+
+Context pointers
+----------------
+
+A number of Objective-C APIs have one argument that is a context pointer,
+which is a :ctype:`void*`. In Objective-C your can pass a pointer to an
+arbitrary value, in Python this must be an integer.
+
+PyObjC provides a :data:`context` object that can be used to allocate
+unique integers and map those to objects.
+
+(NOTE: The markup below here is probably incorrect)
+
+.. function:: context.register(value)
+
+ Add a value to the context registry.
+
+ :param value: An arbitrary object
+ :return: A unique integer that's suitable to be used as a context pointer
+
+.. function:: context.unregister(value):
+
+ Remove an object from the context registery, this object must be have
+ been added to the registry before.
+
+ :param value: An object in the context registry
+
+.. function:: context.get
+
+ Retrieve an object from the registry given the return value from
+ ``context.register``.
+
+
+Descriptors
+-----------
+
+.. function:: IBOutlet([name])
+
+ Creates an instance variable that can be used as an outlet in
+ Interface Builder. When the name is not specified the bridge will
+ use the name from the class dictionary.
+
+ The code block below defines an instance variable named "button" and
+ makes that available as an outlet in Interface Builder.
+
+ .. code-block:: python
+
+ class SomeObject (NSObject):
+
+ button = IBOutlet()
+
+.. function:: IBAction
+
+ Mark an method as an action for use in Interface Builder.
+
+ Usage:
+
+ .. code-block:: python
+
+ class SomeObject (NSObject):
+
+ @IBAction
+ def saveDocument_(self, sender):
+ pass
+
+
+.. function:: instancemethod
+
+ Explicitly mark a method as an instance method. Use this when
+ PyObjC incorrectly deduced that a method should be a class method.
+
+ Usage:
+
+ .. code-block:: python
+
+ class SomeObject (NSObject):
+
+ @instancemethod
+ def alloc(self):
+ pass
+
+
+
+.. function:: accessor
+
+ Use this decorator on the definition of accessor methods to ensure
+ that it gets the right method signature in the Objective-C runtime.
+
+.. function:: typedAccessor(valueType)
+
+ Use this decorator on the definition of accessor methods to ensure
+ that it gets the right method signature in the Objective-C runtime.
+
+ The ``valueType`` is the encoded string for a single value.
+
+.. function:: typedSelector
+
+ Use this decorator to explicitly set the type signature for a method.
+
+ An example:
+
+ .. code-block:: python
+
+ @typedSelector(b'I@:d')
+ def makeUnsignedIntegerOfDouble_(self, d):
+ return d
+
+.. function:: namedSelector(name [, signature])
+
+ Use this decorator to explictly set the Objective-C method name instead
+ of deducing it from the Python name. You can optionally set the method
+ signature as well.
+
+.. function:: callbackFor(callable, argIndex=-1)
+
+ Use this decorator to tell that this function is the callback for
+ an (Objective-C) API.
+
+ TODO: further describe
+
+.. function:: selectorFor
+
+ Decorator to tell that this is the "callback" selector for another
+ API.
+
+ TODO: further describe
+
+.. function:: synthesize
+
+ Use this to synthesize a property with getter and setter methods.
+
+ TODO: futher describe
+
+
+Interacting with ``@synchronized`` blocks
+-----------------------------------------
+
+PyObjC provides an API that implements locking in the same way as the
+``@synchronized`` statement in Objective-C.
+
+.. code-block:: python
+
+ with object_lock(anNSObject):
+ pass
+
+.. class:: object_lock(value)
+
+ This class represents the mutex that protects an Objective-C object
+ for the ``@synchronized`` statement. This can be used as a context
+ manager for the ``with`` statement, but can also be used standalone.
+
+ .. method:: lock
+
+ Acquire the object mutex
+
+ .. method:: unlock
+
+ Release the object mutex
+
+
+Archiving Python and Objective-C objects
+----------------------------------------
+
+Python and Objective-C each provide a native object serialization method,
+the :mod:`pickle` module in Python and the ``NSCoding`` protocol in Objective-C.
+
+It is possible to use an ``NSKeyedArchiver`` to store any Python object that
+can be pickled in an Objective-C serialized data object.
+Due to technical details it is not possible to pickle an Objective-C object,
+unless someone explicitly implements the pickle protocol for such an object.
------------------------------------------------------------------------------
This SF.Net email is sponsored by the Verizon Developer Community
Take advantage of Verizon's best-in-class app development support
A streamlined, 14 day to market process makes app distribution fast and easy
Join now and get one step closer to millions of Verizon customers
http://p.sf.net/sfu/verizon-dev2dev