Commits

lakka committed 33536d8

Updating protocols

  • Participants
  • Parent commits 83f4daa

Comments (0)

Files changed (1)

File pyobjc-core/Doc/advanced/protocols.rst

 Introduction
 ------------
 
-Apple makes use of both formal and informal protocols in the Cocoa framework.
-Formal protocols are those protocols that are implemented using Objective-C
-protocols:
+Apple makes use of both formal and informal protocols in the Cocoa framework
+to specify methods that should be implemented by a class if it is to be used
+in a specific role. For example, a class to be used as a data source for an
+``NSTableView`` must conform to the ``NSTableViewDataSource`` protocol.
 
- .. sourcecode:: objective-c
+A ``Formal protocol`` is implemented in Objective-C as follows:
 
-	@protocol NSFoo <NSSomeProtocol>
-	-(int)doesIt;
-	@end
+.. sourcecode:: objective-c
 
-Conforming to a formal protocol requires the interface of a class to explicitly
-declare that it implements that protocol, and the implementation must implement
-all methods of the protocol.
+    @protocol NSFoo <NSSomeProtocol>
+    -(int)doesIt;
+    @end
 
-Informal protocols are defined as categories on NSObject with no implementation:
+Conforming to a formal protocol requires the interface of a class to
+explicitly declare that it implements that protocol, and the implementation
+must implement all methods of the protocol.
 
- .. sourcecode:: objective-c
+Informal protocols however are defined as `categories` on NSObject with no
+implementation:
 
-	@interface NSObject(FooDelegate)
-	-(void)optionalFooDelegateMethod;
-	@end
+.. sourcecode:: objective-c
 
-Conforming to an informal protocol is much like conforming to a protocol in Python,
-the class simply implements the methods as documented.  In most cases, informal
-protocols are comprised entirely of optional methods (i.e. NSApplicationDelegate)
-and a check is made (i.e. ``-[NSObject respondsToSelector:]``) before sending
-the message to the target.
+    @interface NSObject(FooDelegate)
+    -(void)optionalFooDelegateMethod;
+    @end
+
+Conforming to an informal protocol is much like conforming to a protocol in
+Python: the class simply implements the methods as documented. In most cases,
+informal protocols are comprised entirely of optional methods (eg
+``NSApplicationDelegate``) and a check is made (i.e. ``-[NSObject
+respondsToSelector:]``) before sending the message to the target.
 
 Informal protocols and PyObjC
 -----------------------------
 
-PyObjC has an explicit representation for informal protocols.  This makes
-it possible to use the protocol description to provide better error messages and
+PyObjC has an explicit representation for informal protocols. This makes it
+possible to use the protocol description to provide better error messages and
 to automaticly deduce the method signatures for classes that implement an
 informal protocol.
 
 Informal protocols are represented using instances of 
-``objc.informal_protocol``.  These instances are automaticly added to a
+``objc.informal_protocol``.  These instances are automatically added to a
 registry used by the class builder, so it is not necessary to explicitly
 state that a class implements an informal protocol.
 
+PyObjC will automatically use the information in the ``informal_protocol``
+objects to add the right method signatures to methods, and to warn about
+classes that partially implement a protocol. The only people who have to be
+concerned about these objects are the maintainers of wrappers around
+Objective-C frameworks: they have to keep these protocol wrappers up-to-date.
+
+
 Formal protocols and PyObjC
 ---------------------------
 
 conformance to formal protocols.  However, all formal protocols in Cocoa
 are also described using ``objc.informal_protocol`` objects.
 
-XXX: is this necessary? we could also use the same strategy as for informal
-protocols, and drop the informal_protocol wrappers for formal protocols.
+.. todo:: is this necessary? we could also use the same strategy as for
+    protocols, and drop the informal_protocol wrappers for formal
+    protocols.
 
-In python 2.x declaring conformance to a formal protocol is done by using 
-the formal protocol as a mix-in, and by implementing its methods:
+Declaring conformance to a formal protocol is done by using the formal
+protocol as a mix-in, and by implementing its methods::
 
- .. sourcecode:: python
-    :linenos:
+    NSLocking = objc.protocolNamed('NSLocking')
 
-	NSLocking = objc.protocolNamed('NSLocking')
+    class MyLockingObject(NSObject, NSLocking):
+        def lock(self):
+            pass
 
-	class MyLockingObject(NSObject, NSLocking):
-		def lock(self):
-			pass
+        def unlock(self):
+            pass
 
-		def unlock(self):
-			pass
+.. todo:: Change this example, and the text below: the pyobjc_classMethods hack is no longer
+    necessary.
 
-In python 3.x  you don't use the protocols as mix-ins, but specify them as
-a keyword argument:
+The class now formally implements the ``NSLocking`` protocol. This can be
+verified using the Objective-C introspection methods::
 
- .. sourcecode:: python
-    :linenos:
-
-	NSLocking = objc.protocolNamed('NSLocking')
-
-	class MyLockingObject(NSObject, protocols=[NSLocking]):
-		def lock(self):
-			pass
-
-		def unlock(self):
-			pass
-
-XXX: Change this example when the pyobjc_classMethods hack is no longer necessary.
-
-The class now formally implements the ``NSLocking`` protocol, this can be
-verified using the Objective-C introspection methods:
-
-  .. sourcecode:: pycon
-
-	>>> MyLockingObject.pyobjc_classMethods.conformsToProtocol_(NSLocking)
-	1
+    >>> MyLockingObject.pyobjc_classMethods.conformsToProtocol_(NSLocking)
+    1
 
 This is useful for API's that require (and check) the implementation of formal
 protocols.
 
-XXX: might also be useful for Distributed Objects, create an example
+.. todo:: might also be useful for Distributed Objects, create an example
+
+.. todo:: document how protocols are created: protocolNamed
+
+.. seealso:: `Apple's documentation on Protocols <http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocProtocols.html>`_