Ronald Oussoren avatar Ronald Oussoren committed 4820d33

Move the documentation to sphinx, thanks to Virgil Dupras for
the patch.

Comments (0)

Files changed (40)

pyobjc-core/Doc/06tutorial/index.txt

-=======================================
-Creating your first PyObjC application.
-=======================================
-
-WARNING: This tutorial assumes you're using Xcode 2.5 and is therefore not 
-entirely valid with Xcode 3 (that is MacOS 10.5).
-
-In this tutorial you will learn how to create your first Python Cocoa
-application: a simple dialog that allows you to convert amounts of money from
-one currency to another.  Definitely easier to do with a calculator, but in the
-process of following the tutorial you will learn which bits of Apple's Cocoa
-documentation apply to PyObjC and which bits are different, and how to adapt
-the different bits to PyObjC from Objective-C.
-
-To follow the tutorial you need:
-
- * PyObjC 1.3.1
- * py2app 0.2 or later (included in the binary installer for PyObjC)
- * Python 2.3 or later (note: PyObjC is NOT compatible with MacPython-OS9)
- * Mac OS X 10.2 or later
- * Xcode Tools (was Developer Tools for Mac OS X 10.2)
-
-If you do not have a ``/Developer`` folder, then you do not have Xcode Tools
-installed.  See `Getting the Xcode Tools`_.
-
-.. _`Getting the Xcode Tools`: http://developer.apple.com/tools/download/
-
-Getting Started
----------------
-
-1. Create a work directory ``src``.  Check which Python you have installed
-   PyObjC for, by running ``python`` and checking that ``import Foundation``
-   works.  If it does not work it could be that you have installed PyObjC for
-   ``/usr/local/bin/python`` but Apple's ``/usr/bin/python`` comes first in
-   your ``$PATH``.  Make sure you use the right python whereever it says
-   ``python`` in this tutorial.
-   
-2. Start Interface Builder, select *Cocoa Application*
-   in the new file dialog, save this file as ``src/MainMenu.nib``.
-   
-3. Proceed with the instructions as lined out in Apple's
-   `Developing Cocoa Objective-C Applications: a Tutorial`_, `chapter 3`_,
-   just after the section "*Creating the Currency Converter Interface*".
-   Work through "Defining the Classes of Currency Converter", "Connecting
-   ConverterController to the Interface", and stop at
-   "*Implementing the Classes of Currency Converter*", as we are going to do
-   this in Python, not Objective-C.  Your nib file should now be the same as
-   step3-MainMenu.nib_.
-   
-.. _`Developing Cocoa Objective-C Applications: a Tutorial`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/index.html
-.. _`chapter 3`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/index.html?http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/chapter03/chapter_3_section_1.html
-.. _step3-MainMenu.nib: step3-MainMenu.nib.zip
-   
-4. Create the skeleton Python script by running the ``nibclassbuilder`` script.
-   ``nibclassbuilder`` will parse the NIB file and create a skeleton module for
-   you.  Invoke it as follows (from the ``src`` directory):
-
-   .. sourcecode:: sh
-   
-       $ python -c "import PyObjCScripts.nibclassbuilder" MainMenu.nib > CurrencyConverter.py
-               
-   Depending on your installation, the ``nibclassbuilder`` script may be on your ``$PATH``.
-   If so, it can be invoked as such:
-
-   .. sourcecode:: sh
-
-       $ nibclassbuilder MainMenu.nib > CurrencyConverter.py
-   
-   The result of this can be seen in step4-CurrencyConverter.py_.
-
-.. _step4-CurrencyConverter.py: step4-CurrencyConverter.py.html
-               
-Testing the user interface
---------------------------
-
-5. Now we need to create an build script for CurrencyConverter.  To do this,
-   create a file named ``setup.py`` with the following contents:
-
-   .. sourcecode:: python
-      :linenos:
-   
-        from distutils.core import setup
-        import py2app
-
-        setup(
-            app=['CurrencyConverter.py'],
-            data_files=['MainMenu.nib'],
-        )
-
-   The result of this can be seen in step5-setup.py_.
-
-.. _step5-setup.py: step5-setup.py.html
-   
-6. Run the setup script to create a temporary application bundle for
-   development:
-
-   .. sourcecode:: sh
-
-        $ python setup.py py2app -A
-      
-   Note that we use the ``-A`` argument to create an alias bundle at 
-   ``dist/CurrencyConverter.app``.  Alias bundles contain an alias to the
-   main script (``CurrencyConverter.py``) and symlinks to the data files
-   (``MainMenu.nib``), rather than including them and their dependencies
-   into a standalone application bundle.  This allows us to keep working on
-   the source files without having to rebuild the application.  This alias
-   bundle is similar to a ZeroLink executable for Xcode - it is for
-   DEVELOPMENT ONLY, and will not work on other machines.
-   
-7. Run the program.  This can be done in three ways:
-
-   - double-click ``dist/CurrencyConverter`` from the Finder
-     (you won't see the .app extension)
-
-   - open it from the terminal with:
-
-     .. sourcecode:: sh
-   
-        $ open dist/CurrencyConverter.app
-       
-   - run it directly from the Terminal, as::
-
-     .. sourcecode:: sh
-   
-        $ ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
-       
-   The last method is typically the best to use for development: it leaves
-   stdout and stderr connected to your terminal session so you can see what
-   is going on if there are errors, and it allows you to interact with ``pdb``
-   if you are using it to debug your application.  Note that your application
-   will likely appear in the background, so you will have to cmd-tab or click
-   on its dock icon to see its user interface.
-   
-   The other methods cause stdout and stderr to go to the Console log, which
-   can be viewed with ``/Applications/Utilities/Console.app``.
-   
-   When you run your script as it is now it should behave identically as when
-   you tested your interface in Interface Builder in step 3, only now the
-   skeleton is in Python, not Objective-C.
-   
-
-Writing the code
-----------------
-
-8.  Time to actually write some code.  Open ``CurrencyConverter.py`` in your
-    favorite text editor.  Follow Apple's documentation again, chapter 3,
-    section "Implementing Currency Converter's Classes".  To translate this
-    Objective C code to Python syntax, we will need to do some name mangling of
-    the selectors.  See *An introduction to PyObjC* for the details, but the
-    short is that:
-
-    .. sourcecode:: objective-c
-
-        [anObject modifyArg: arg1 andAnother: arg2]
-
-   translates into the following Python code, by replacing the colons in the
-   selector with underscores, and passing the arguments as you would with a
-   normal Python method call:
-
-   .. sourcecode:: python
-
-        anObject.modifyArg_andAnother_(arg1, arg2)
-   
-   Note that we don't do this mangling for ``Converter.convertAmount()``: this
-   method is only called by other Python code, so there is no need to go
-   through the name mangling.  Also, if we would want to make this method
-   callable from ObjC code we may have to tell the PyObjC runtime system about
-   the types of the arguments, so it could do the conversion.  This is beyond
-   the scope of this first tutorial, *An introduction to PyObjC* has a little
-   more detail on this.
-   
-   The application should now be fully functional, try it.  The results of what
-   we have up to now can be seen in step8-CurrencyConverter.py_.
-   
-.. _step8-CurrencyConverter.py: step8-CurrencyConverter.py.html
-   
-Extending the functionality
----------------------------
-
-9.  We are going to add one more goodie, just to show how you edit an existing
-    application.  The main problem, which may be obvious, is that we cannot run
-    ``nibclassbuilder`` again because we would destroy all the code we wrote in
-    steps 5 and 8, so we do this by hand.  What we are going to do is add an
-    "invert rate" command, because I always get this wrong: instead of typing
-    in the exchange rate from dollars to euros I type in the rate to convert
-    from euros to dollars.
-   
-    Open ``MainMenu.nib`` in Interface Builder.  Select the *Classes* view and
-    then select the ``ConverterController`` class.  In the info panel select
-    the *Attributes* from the popup.  Select the *Actions* tab, and add an
-    action ``invertRate:``.  You have now told Interface Builder that instances
-    of the ``ConverterController`` class have grown a new method
-    ``invertRate_()``.
-   
-    In the ``MainMenu.nib main`` window open the *MainMenu* menubar.  Select
-    the ``Edit`` menu.  Make sure the *Menus* palette is open and selected,
-    drag a separator to the ``Edit`` menu and then drag an ``Item`` there.
-    Double-click the item and set the text to ``Invert Exchange Rate``.
-   
-    Make the connection by control-dragging from the new
-    ``Invert Exchange Rate`` menu item to the ``ConverterController`` instance
-    in the Instances tab in the ``MainMenu.nib`` main window.
-
-    *NOTE:* you drag to the *instance* of ``ConverterController``, not to the
-    class.
-
-    In the *Info* panel, *Connections* section, select ``invertRate:`` and
-    press *Connect*. 
-   
-10. We know our program can't invert rates yet, because we haven't actually
-    written the code to do it, but we are going to try it anyway, just to see
-    what sort of spectacular crash we get.  Alas, nothing spectacular about it:
-    when the NIB is loaded the Cocoa runtime system tries to make the
-    connection, notices that we have no ``invertRate_()`` method in our
-    ``ConverterController`` class and it gives an error message:
-
-    .. sourcecode:: sh
-       
-       $ ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter 
-       2004-12-09 03:29:09.957 CurrencyConverter[4454] Could not connect the action 
-       invertRate: to target of class ConverterController
-   
-    Moreover, it has disabled the ``Invert Exchange Rate`` menu command and
-    continues, so the program works as it did before, only with one more
-    (disabled) menu item.
-   
-Debugging
----------
-
-11. Writing the code is easy: add a method ``invertRate_(self, sender)`` that
-    gets the float value of ``rateField``, inverts it and puts it back.  We
-    deliberately forget to test for divide by zero.  We run the program again,
-    and now the menu entry is enabled.  After trying it with a couple of
-    non-zero exchange rates we try it with an exchange rate of zero (or empty,
-    which is the same).  We get a dialog box giving the Python exception, and
-    offering the choice of continuing or quitting. 
-    
-    To debug this application with pdb, start the application with the
-    following command line:
-
-    .. sourcecode:: sh
-
-        $ env USE_PDB=1 ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
-
-    When running in this mode, we will get a ``pdb.post_mortem(...)`` console
-    in the terminal instead of the alert panel.  You can see this in action if
-    you try and invert an exchange rate of ``0``.
-      
-12. Fix the final bug by testing for ``rate == 0.0`` in ``invertRate_()``.
-    The result is in the step12-src_ directory.
-    
-.. _step12-src: step12-src.zip
-   
-Creating a redistributable application
---------------------------------------
-
-Your application is finished, and you want to run it on other computers, or
-simply just move it to the ``Applications`` folder (or anywhere else) and
-insulate it from the original source code.
-
-This can be done with the following steps from the ``src`` directory:
-
- .. sourcecode: sh
-
-    $ rm -rf dist
-    $ python setup.py py2app
-
-Now the application bundle located at ``dist/CurrencyConverter.app`` is a fully
-standalone application that should run on any computer running the same major
-version of Mac OS X or later.  This means that applications built on
-Mac OS X 10.2 are compatible with Mac OS X 10.3, but NOT vice versa.  If you
-are not using an Apple-supplied version of Python, a subset of your Python
-installation will be included in this application.
-
-For more complicated examples of py2app usage to do things such as change the
-application's icon, see the Examples or the py2app documentation.

pyobjc-core/Doc/06tutorial/step12-src/CurrencyConverter.py

-from Foundation import NSObject, NSObject
-from PyObjCTools import NibClassBuilder, AppHelper
-
-NibClassBuilder.extractClasses("MainMenu")
-
-
-# class defined in MainMenu.nib
-class Converter(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-
-    def convertAmount(self, amt, rate):
-        return amt * rate
-
-# class defined in MainMenu.nib
-class ConverterController(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-    # The following outlets are added to the class:
-    # converter
-    # dollarField
-    # rateField
-    # totalField
-
-    def convert_(self, sender):
-        amt = self.dollarField.floatValue()
-        rate = self.rateField.floatValue()
-
-        total = self.converter.convertAmount(rate, amt)
-        self.totalField.setFloatValue_(total)
-        self.rateField.selectText_(self)
-
-    def awakeFromNib(self):
-        self.rateField.window().makeKeyAndOrderFront_(self)
-        self.rateField.selectText_(self)
-
-    def invertRate_(self, sender):
-        rate = self.rateField.floatValue()
-        if rate != 0.0:
-            rate = 1.0 / rate
-        self.rateField.setFloatValue_(rate)
-
-if __name__ == "__main__":
-    AppHelper.runEventLoop()

pyobjc-core/Doc/06tutorial/step12-src/English.lproj/MainMenu.nib/classes.nib

-{
-    IBClasses = (
-        {CLASS = Converter; LANGUAGE = ObjC; SUPERCLASS = NSObject; }, 
-        {
-            ACTIONS = {convert = id; invertRate = id; }; 
-            CLASS = ConverterController; 
-            LANGUAGE = ObjC; 
-            OUTLETS = {
-                converter = id; 
-                dollarField = NSTextField; 
-                rateField = NSTextField; 
-                totalField = NSTextField; 
-            }; 
-            SUPERCLASS = NSObject; 
-        }, 
-        {CLASS = FirstResponder; LANGUAGE = ObjC; SUPERCLASS = NSObject; }
-    ); 
-    IBVersion = 1; 
-}

pyobjc-core/Doc/06tutorial/step12-src/English.lproj/MainMenu.nib/info.nib

-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>IBDocumentLocation</key>
-	<string>485 378 356 240 0 0 1280 1002 </string>
-	<key>IBEditorPositions</key>
-	<dict>
-		<key>29</key>
-		<string>52 213 318 44 0 0 1280 1002 </string>
-	</dict>
-	<key>IBFramework Version</key>
-	<string>286.0</string>
-	<key>IBOpenObjects</key>
-	<array>
-		<integer>29</integer>
-		<integer>21</integer>
-	</array>
-	<key>IBSystem Version</key>
-	<string>6I32</string>
-</dict>
-</plist>
Add a comment to this file

pyobjc-core/Doc/06tutorial/step12-src/English.lproj/MainMenu.nib/objects.nib

Binary file removed.

pyobjc-core/Doc/06tutorial/step12-src/setup.py

-from distutils.core import setup
-import py2app
-
-setup(
-    app=['CurrencyConverter.py'],
-    data_files=['English.lproj'],
-)

pyobjc-core/Doc/06tutorial/step3-MainMenu.nib/classes.nib

-{
-    IBClasses = (
-        {CLASS = Converter; LANGUAGE = ObjC; SUPERCLASS = NSObject; }, 
-        {
-            ACTIONS = {convert = id; }; 
-            CLASS = ConverterController; 
-            LANGUAGE = ObjC; 
-            OUTLETS = {
-                converter = id; 
-                dollarField = NSTextField; 
-                rateField = NSTextField; 
-                totalField = NSTextField; 
-            }; 
-            SUPERCLASS = NSObject; 
-        }, 
-        {CLASS = FirstResponder; LANGUAGE = ObjC; SUPERCLASS = NSObject; }
-    ); 
-    IBVersion = 1; 
-}

pyobjc-core/Doc/06tutorial/step3-MainMenu.nib/info.nib

-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>IBDocumentLocation</key>
-	<string>363 297 356 240 0 0 1680 1028 </string>
-	<key>IBEditorPositions</key>
-	<dict>
-		<key>29</key>
-		<string>74 219 318 44 0 0 1680 1028 </string>
-	</dict>
-	<key>IBFramework Version</key>
-	<string>349.0</string>
-	<key>IBOpenObjects</key>
-	<array>
-		<integer>21</integer>
-		<integer>29</integer>
-	</array>
-	<key>IBSystem Version</key>
-	<string>7F44</string>
-</dict>
-</plist>
Add a comment to this file

pyobjc-core/Doc/06tutorial/step3-MainMenu.nib/objects.nib

Binary file removed.

pyobjc-core/Doc/06tutorial/step4-CurrencyConverter.py

-import objc
-from Foundation import *
-from AppKit import *
-from PyObjCTools import NibClassBuilder, AppHelper
-
-
-NibClassBuilder.extractClasses("MainMenu")
-
-
-# class defined in MainMenu.nib
-class Converter(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-    pass
-
-
-# class defined in MainMenu.nib
-class ConverterController(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-    # The following outlets are added to the class:
-    # converter
-    # dollarField
-    # rateField
-    # totalField
-
-    def convert_(self, sender):
-        pass
-
-
-
-if __name__ == "__main__":
-    AppHelper.runEventLoop()

pyobjc-core/Doc/06tutorial/step5-setup.py

-from distutils.core import setup
-import py2app
-
-setup(
-    app=['CurrencyConverter.py'],
-    data_files=['MainMenu.nib'],
-)

pyobjc-core/Doc/06tutorial/step8-CurrencyConverter.py

-import objc
-from Foundation import *
-from AppKit import *
-from PyObjCTools import NibClassBuilder, AppHelper
-
-NibClassBuilder.extractClasses("MainMenu")
-
-
-# class defined in MainMenu.nib
-class Converter(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-
-    def convertAmount(self, amt, rate):
-        return amt * rate
-
-# class defined in MainMenu.nib
-class ConverterController(NibClassBuilder.AutoBaseClass):
-    # the actual base class is NSObject
-    # The following outlets are added to the class:
-    # converter
-    # dollarField
-    # rateField
-    # totalField
-
-    def convert_(self, sender):
-        amt = self.dollarField.floatValue()
-        rate = self.rateField.floatValue()
-
-        total = self.converter.convertAmount(rate, amt)
-        self.totalField.setFloatValue_(total)
-        self.rateField.selectText_(self)
-
-    def awakeFromNib(self):
-        self.rateField.window().makeKeyAndOrderFront_(self)
-        self.rateField.selectText_(self)
-
-if __name__ == "__main__":
-    AppHelper.runEventLoop()

pyobjc-core/Doc/07tutorial_embed/index.txt

-=============================================================
-Tutorial - Adding Python code to an existing ObjC application
-=============================================================
-
-In this tutorial we are going to take an existing ObjC application and
-add Python and PyObjC to it.  One of the reasons why you may want to do
-this is because some things are much simpler in Python than in ObjC, mainly
-due to the rich library Python has.
-
-To follow the tutorial you need:
-
- * PyObjC 1.3.1
- * py2app 0.2 or later (included in the binary installer for PyObjC)
- * Python 2.3 or later (note: PyObjC is NOT compatible with MacPython-OS9)
- * Mac OS X 10.3 or later
- * Xcode Tools
-
-If you do not have a ``/Developer`` folder, then you do not have Xcode Tools
-installed.  See `Getting the Xcode Tools`_.
-
-.. _`Getting the Xcode Tools`: http://developer.apple.com/tools/download/
-
-The application we are going to modify is Apple's SimpleComboBox example.
-This example shows you how to use combo boxes, but that is not what interests
-us right now: the application pretends to be a database application that allows
-you to keep notes (such as track list) for your CD collection.  With such an
-application it feels silly that even though you want to type notes on
-the CD you are currently playing in iTunes you still have to retype
-album title, artist and genre.  This is what we are going to fix: we
-are going to add a button "ask iTunes", which will use Python's
-AppleScript support to ask iTunes about the currently playing track
-and fill in the fields for you.  
-
-Follow these steps:
-
-1. Make a copy of ``/Developer/Examples/AppKit/SimpleComboBox`` to work on.
-   Let's call this ``SimpleComboBoxPlus``:
-
-   .. sourcecode: sh
-   
-      $ cp -R /Developer/Examples/AppKit/SimpleComboBox SimpleComboBoxPlus
-
-  From this point on, all shell commands take place from this
-  ``SimpleComboBoxPlus`` folder.
-    
-2. Open it in Xcode, build it, and see what it does.
-
-3. Open ``CDInfoDocument.nib``.  Select the Class View, ``NSObject``, subclass
-   as ``ITunesCommunication``.  Give the class an ``askITunes:`` action.
-   Instantiate the class as object ``ITunesCommunication``.  This wll be the
-   class that we write in Python.
-   
-4. Go to the object view again, open the Window.
-
-5. Move the text box down a bit to make space, add a button "ask iTunes".
-
-6. Connect this button to the ``askITunes:`` action of the
-   ``ITunesCommunication`` object.
-    
-7. We now need to write the code implementing the ``ITunesCommunication``
-    class.  As this tutorial is about using PyObjC in existing ObjC programs
-    and not about PyObjC itself, we are going to skip writing the code and
-    simply copy ``ITunesCommunication_1.py`` to ``ITunesCommunication.py``.
-
-8. Now we need to create the build script for our plugin, create a file named
-   ``setup.py`` with the following contents:
-
-
-   .. sourcecode:: python
-
-        from distutils.core import setup
-        import py2app
-
-        setup(
-            plugin = ['ITunesCommunication.py']
-        )   
-
-   You may also copy this file from ``setup.py``. 
-
-9. Run the setup script to create a temporary plugin bundle for development:
-
-   .. sourcecode: sh
-
-        $ python setup.py py2app -A
-
-   Note that we use the ``-A`` argument to create an alias plugin bundle at
-   ``dist/ITunesCommunication.py``.  Alias bundles contain an alias to the
-   main script (``ITunesCommunication.py``) and symlinks to the data files
-   (none in this case).  This allows us to keep working on the source files
-   without having to rebuild the application.  This alias bundle is similar
-   to a ZeroLink executable in Xcode - it is for DEVELOPMENT ONLY, and will
-   not work on other machines.
-
-10. Add ``dist/ITunesCommunication.plugin`` to the Resources folder in your
-    Xcode project.  You can do this by ctrl-clicking the Resources folder
-    and choosing "Add Existing Files...".  Make sure to choose
-    "Create Folder References for any added folders".
-
-11. Open ``main.m``, it is in the "Other Sources" folder in your Xcode
-    project, and change the main(...) function to the following:
-
-    .. sourcecode:: objective-c
-
-        int main(int argc, const char *argv[]) {
-            NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
-            NSString *pluginPath = [[NSBundle mainBundle]
-                                        pathForResource:@"ITunesCommunication"
-                                                 ofType:@"plugin"];
-            NSBundle *pluginBundle = [NSBundle bundleWithPath:pluginPath];
-            [pluginBundle load];
-            [pool release];
-            return NSApplicationMain(argc, argv);
-        }
-
-
-    You may also copy a full main.m from ``main.m``.  This code ensures
-    that our ITunesCommunication plugin is loaded before the nib
-    files.
-
-12. Build and run.  When you press the "Ask iTunes" the "CD Title" and
-    "Band Name" fields will be filled with one of the best albums of the last
-    few years :-)
-    
-13. Now we need to make the program talk to iTunes.  The current MacPython
-    interface to the Open Scripting Architecture requires an extra step when
-    compared to AppleScript: you need to manually generate a Python package
-    that wraps all the AppleScript terminology for an application.  To make
-    matters more complicated iTunes is one of those special cases where the
-    standard way to generate this package (start the application, ask it for
-    its terminology) does not work, so we have to actually look into the
-    bowels of ``iTunes.app``.  This leads to the following hefty command line
-    which you should run in the ``SimpleComboBoxPlus`` directory:
-
-    .. sourcecode:: sh
-    
-        $ cd SimpleComboBoxPlus
-        $ pythonw -c "from gensuitemodule import main;main()" \
-            --output iTunes --creator hook --resource \
-            /Applications/iTunes.app/Contents/Resources/iTunes.rsrc
-    
-14. Finally, add the code to ``ITunesCommunication.py`` to actually communicate
-    with iTunes.  We cop out and copy it from ``ITunesCommunication_2.py``.
-    
-15. Build and run.  If you press the button when iTunes is playing the Title
-    and Band names will be filled, otherwise they will be cleared.  In a real
-    application you would disable the "Ask iTunes" button unless iTunes was
-    active.  All that is left as an exercise to the reader.
-
-16. To make this application redistributable, perform the following commands
-    to make the plugin redistributable:
-
-    .. sourcecode:: sh
-
-        $ rm -rf dist
-        $ python setup.py py2app
-
-    Then, from Xcode, clean your project (shift-cmd-K), switch to Deployment
-    mode, and rebuild.
- 
-A minor variation
------------------
-
-There a several projects that improve upon the built-in AppleScript support
-(or to be more precise "application scripting support").  One of those is
-`AppScript`_.
-
-.. _`AppScript`: http://freespace.virgin.net/hamish.sanderson/appscript.html
-
-When you have this module installed you can replace the contents of
-``ITunesCommuncation.py`` with ``ITunesCommunication_AppScript.py``,
-and you can skip step 13 entirely.

pyobjc-core/Doc/07tutorial_embed/src/ITunesCommunication_1.py

-#
-#  ITunesCommunication.py
-#  PyObjC2Test
-#
-#  Created by Jack Jansen on Tue Jun 17 2003.
-#  Copyright (c) 2003 __MyCompanyName__. All rights reserved.
-#
-
-import objc
-from Foundation import *
-from AppKit import *
-
-from PyObjCTools import NibClassBuilder
-
-# We tell NibClassBuilder to examine and remember all
-# classes from the CDInfoDocument NIB file. This way,
-# we can subclass our ITunesCommunication from AutoBaseClass
-# later on, and its actual baseclass will be ITunesCommunication
-# from the NIB file.
-# Since the NIB files are in the application, NOT the plugin, we
-# need to specify this explicitly.  Typicaly, NIB files would be in the
-# plugins.
-NibClassBuilder.extractClasses("CDInfoDocument", bundle=NSBundle.mainBundle())
-
-class ITunesCommunication(NibClassBuilder.AutoBaseClass):
-    def init(self):
-        self = super(ITunesCommunication, self).init()
-        if self is None:
-            return None
-        # subclass specific initialization here
-        # nib not loaded yet
-        return self
-
-    def askITunes_(self, obj):
-        # obj is the button the user pressed. We can go from here
-        # to the document (an instance of CDInfoDocument)
-        document = obj.window().windowController().document()
-        document.setBandName_(u"Uit de Sloot")
-        document.setCDTitle_(u"En Snel Een Beetje")
-        document.setMusicGenre_(u"Punkrock")

pyobjc-core/Doc/07tutorial_embed/src/ITunesCommunication_2.py

-#
-#  ITunesCommunication.py
-#  PyObjC2Test
-#
-#  Created by Jack Jansen on Tue Jun 17 2003.
-#  Copyright (c) 2003 __MyCompanyName__. All rights reserved.
-#
-
-import objc
-from Foundation import *
-from AppKit import *
-
-from PyObjCTools import NibClassBuilder
-
-import iTunes
-
-# We tell NibClassBuilder to examine and remember all
-# classes from the CDInfoDocument NIB file. This way,
-# we can subclass our ITunesCommunication from AutoBaseClass
-# later on, and its actual baseclass will be ITunesCommunication
-# from the NIB file.
-# Since the NIB files are in the application, NOT the plugin, we
-# need to specify this explicitly.  Typicaly, NIB files would be in the
-# plugins.
-NibClassBuilder.extractClasses("CDInfoDocument", bundle=NSBundle.mainBundle())
-
-class ITunesCommunication(NibClassBuilder.AutoBaseClass):
-    def init(self):
-        self = super(ITunesCommunication, self).init()
-        if self is None:
-            return None
-        # subclass specific initialization here
-        # nib not loaded yet
-        self.itunes = iTunes.iTunes()
-        return self
-
-    def getITunesInfo(self):
-        curtrk = self.itunes.current_track
-        try:
-            current_track = self.itunes.get(curtrk)
-        except iTunes.Error:
-            NSRunAlertPanel(
-                u'iTunes Communication Error',
-                u'iTunes failed to return the current track',
-                None,
-                None,
-                None)
-            return None
-        album = self.itunes.get(current_track.album)
-        artist = self.itunes.get(current_track.artist)
-        genre = self.itunes.get(current_track.genre)
-        return album, artist, genre
-
-    def askITunes_(self, obj):
-        # obj is the button the user pressed. We can go from here
-        # to the document (an instance of CDInfoDocument)
-        document = obj.window().windowController().document()
-        # Try to get the iTunes info
-        info = self.getITunesInfo()
-        if info is None:
-            return
-        album, artist, genre = info
-        document.setCDTitle_(album)
-        document.setBandName_(artist)
-        document.setMusicGenre_(genre)

pyobjc-core/Doc/07tutorial_embed/src/ITunesCommunication_AppScript.py

-#######
-
-#
-#  ITunesCommunication.py
-#  PyObjC2Test
-#
-#
-# This is a variation on the ITunesCommuncation that uses a the 'appscript'
-# module for the inter-application communication.
-
-import objc
-from Foundation import *
-from AppKit import *
-
-from PyObjCTools import NibClassBuilder
-
-from appscript import *
-
-# We tell NibClassBuilder to examine and remember all
-# classes from the CDInfoDocument NIB file. This way,
-# we can subclass our ITunesCommunication from AutoBaseClass
-# later on, and its actual baseclass will be ITunesCommunication
-# from the NIB file.
-# Since the NIB files are in the application, NOT the plugin, we
-# need to specify this explicitly.  Typicaly, NIB files would be in the
-# plugins.
-NibClassBuilder.extractClasses("CDInfoDocument", bundle=NSBundle.mainBundle())
-
-class ITunesCommunication(NibClassBuilder.AutoBaseClass):
-    def init(self):
-        self = super(ITunesCommunication, self).init()
-        if self is None:
-            return None
-        return self
-
-    def getITunesInfo(self):
-        try:
-            track = app('iTunes.app').current_track.get()
-        except Exception:
-            NSRunAlertPanel(
-                u'iTunes Communication Error',
-                u'iTunes failed to return the current track',
-                None,
-                None,
-                None)
-        else:
-            return track.album.get(), track.artist.get(), track.genre.get()
-
-    def askITunes_(self, obj):
-        # obj is the button the user pressed. We can go from here
-        # to the document (an instance of CDInfoDocument)
-        document = obj.window().windowController().document()
-        # Try to get the iTunes info
-        info = self.getITunesInfo()
-        if info is None:
-            return
-        album, artist, genre = info
-        document.setCDTitle_(album)
-        document.setBandName_(artist)
-        document.setMusicGenre_(genre)

pyobjc-core/Doc/07tutorial_embed/src/main.m

-#import <AppKit/AppKit.h>
-
-int main(int argc, const char *argv[]) {
-    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
-    NSString *pluginPath = [[NSBundle mainBundle] pathForResource:@"ITunesCommunication" ofType:@"plugin"];
-    NSBundle *pluginBundle = [NSBundle bundleWithPath:pluginPath];
-    [pluginBundle load];
-    [pool release];
-    return NSApplicationMain(argc, argv);
-}

pyobjc-core/Doc/07tutorial_embed/src/setup.py

-from distutils.core import setup
-import py2app
-
-setup(
-    plugin = ['ITunesCommunication.py']
-)

pyobjc-core/Doc/10PyObjCTools.txt

-===============================
-PyObjCTools: The PyObjC Toolbox
-===============================
-
-Introduction
-------------
-
-The package ``PyObjCTools`` contains a number of (basically unrelated) modules
-with useful functionality. These have been placed inside a module to avoid
-cluttering the global namespace.
-
-The rest of this document provides documentation for these modules, but lets
-start with a short overview.
-
-* ``PyObjCTools.AppHelper``
-
-Utility functions for use with the ``AppKit`` module.
-
-* ``PyObjCTools.Conversion``
-
-Functions for converting between Cocoa and pure Python data structures.
-
-* ``PyObjCTools.KeyValueCoding``
-
-A Python API for working with `Key-Value Coding`__. 
-
-.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
-
-* ``PyObjCTools.NibClassBuilder``
-
-Module containing a magic super-class that can read information about the
-actual super-class and implemented actions and outlets from a NIB file.
-
-* ``PyObjCTools.MachSignals``
-
-Module to make it possible to integrate signal handling into the main
-runloop.
-
-* ``PyObjCTools.Debugging``
-
-Allows logging of NSException stack traces.  This module should only be used
-during development.
-
-* ``PyObjCTools.Signals``
-
-Module that tries to print useful information when the program gets a fatal
-exception. This module should only be used during development.
-
-* ``PyObjCTools.XcodeSupport``
-
-Used by the PyObjC Xcode templates to derive py2app options from an Xcode
-project file.
-
-
-``PyObjCTools.AppHelper``
-.........................
-
-This module exports functions that are useful when working with the
-``AppKit`` framework (or more generally, run loops).
-
-* ``callAfter(func, *args, **kwargs) -> None``
-
-  Call a function on the main thread.  Returns immediately.
-
-* ``callLater(delay, func, *args, **kwargs) -> None``
-
-  Call a function on the main thread after a delay.  Returns immediately.
-
-* ``endSheetMethod(method) -> selector``
-
-  Convert a method to a form that is suitable to use as the delegate callback
-  for sheet methods.
-
-* ``stopEventLoop() -> None``
-
-  Stops the event loop (if started by ``runConsoleEventLoop``) or sends the
-  ``NSApplication`` a ``terminate:`` message.
-
-* ``runConsoleEventLoop(argv=None, installInterrupt=False, mode=NSDefaultRunLoopMode) -> None``
-
-  Run a ``NSRunLoop`` in a stoppable way (with ``stopEventLoop``).
-
-* ``runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert, installInterrupt=None, pdb=None, main=NSApplicationMain) -> None``
-
-  Run the event loop using ``NSApplicationMain`` and ask the user if we should
-  continue if an exception is caught.
-
-  This function doesn't return unless it throws an exception.
-
-
-``PyObjCTools.Conversion``
-.............................
-
-Functions for converting between Cocoa and pure Python data structures.
-
-* ``propertyListFromPythonCollection(pyCol, conversionHelper=None) -> ocCol``
-
-  Convert a Python collection (dictionary, array, tuple, string) into an 
-  Objective-C collection.
-
-  If conversionHelper is defined, it must be a callable.  It will be called 
-  for any object encountered for which ``propertyListFromPythonCollection()``
-  cannot automatically convert the object.   The supplied helper function 
-  should convert the object and return the converted form.  If the conversion 
-  helper cannot convert the type, it should raise an exception or return None.
-
-* ``pythonCollectionFromPropertyList(ocCol, conversionHelper=None) -> pyCol``
-
-  Converts a Foundation based collection-- a property list-- into a Python 
-  collection.  Like ``propertyListFromPythonCollection()``, ``conversionHelper``
-  is an optional callable that will be invoked any time an encountered object 
-  cannot be converted.
-
-``PyObjCTools.KeyValueCoding``
-..............................
-
-A module for working with Key-Value Coding in Python. Key-Value Coding is
-explained `on the Apple website`__
-
-.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
-
-This module provides a Python interface to some of that functionality. The
-interface is modeled on the ``getattr`` and ``setattr`` functions.
-
-* ``getKey(object, key) -> value``
-
-    Get the attribute referenced by 'key'. The key is used
-    to build the name of an attribute, or attribute accessor method.
-
-    The following attributes and accesors are tried (in this order):
-
-    - Accessor 'getKey'
-    - Accesoor 'get_key'
-    - Accessor or attribute 'key'
-    - Accessor or attribute 'isKey'
-    - Attribute '_key'
-
-    If none of these exist, raise KeyError
-
-* ``getKeyPath(object, keypath) -> value``
-
-  Like ``getKey`` but using a key path. The ``keypath`` is a sequence of keys
-  separated by dots. It calls ``getKey`` to follow the path and returns the
-  final value.
-
-* ``setKey(object, key, value) -> None``
-
-  Set the value of ``key`` to ``value``.
-
-  The following values are used for setting the value for a key named ``key``
-  (first match wins):
-
-  - Call ``object.set_key(value)``
-
-  - Call ``object.setKey(value)``
-
-  - Call ``object._set_key(value)``
-
-  - Call ``object._setKey(value)``
-
-  - Check if ``_key`` is an attribute and if so, set its value
-
-  - Try to set the attribute ``key``.
-
-  Raises ``KeyError`` if the key cannot be changed.
-
-* ``setKeyPath(object, keypath, value) -> None``
-
-  The same as ``setKey``, but now using a key path. A key path is a sequence
-  of keys separated by dots. The ``getKey`` function is used to traverse 
-  the path up to the last item, and then ``setKey`` is used to change the value.
-
-PyObjCTools.NibClassBuilder
-...........................
-
-Extracting class definitions from nibs
-++++++++++++++++++++++++++++++++++++++
-
-The module maintains a global set of class definitions, extracted from
-nibs. To add the classes from a nib to this set, use the ``extractClasses()``
-function. It can be called in two ways:
-
-- ``extractClasses(nibName, bundle=<current-bundle>)``
-
-  This finds the nib by name from a bundle. If no bundle
-  if given, the ``objc.currentBundle()`` is searched.
-
-- ``extractClasses(path=pathToNib)``
-
-  This uses an explicit path to a nib.
-
-``extractClasses()`` can be called multiple times for the same bundle: the
-results are cached so no almost extra overhead is caused.
-
-Using the class definitions
-+++++++++++++++++++++++++++
-
-The module contains a "magic" base (super) class called ``AutoBaseClass``.
-Subclassing ``AutoBaseClass`` will invoke some magic that will look up the
-proper base class in the class definitions extracted from the nib(s).
-If you use multiple inheritance to use Cocoa's "informal protocols",
-you *must* list ``AutoBaseClass`` as the first base class. For example::
-
-    class PyModel(AutoBaseClass, NSTableSource):
-        ...
-
-
-The ``NibInfo`` class
-+++++++++++++++++++++
-
-The parsing of nibs and collecting the class definition is done by the
-``NibInfo`` class. You normally don't use it directly, but it's here if you
-have special needs.
-
-The command line tool
-+++++++++++++++++++++
-
-When run from the command line, this module invokes a simple command
-line program, which you feed paths to nibs. This will print a Python
-template for all classes defined in the nib(s). For more documentation,
-see the commandline_doc variable, or simply run the program without
-arguments. It also contains a simple test program.
-
-PyObjCTools.Signals
-...................
-
-This module provides two functions that can be useful while investigating
-random crashes of a PyObjC program. These crashes are often caused by 
-Objective-C style weak references or incorrectly implemented protocols.
-
-- ``dumpStackOnFatalSignal()``
-
-  This function will install signal handlers that print a stack trace and
-  then re-raise the signal.
-
-- ``resetFatalSignals()``
-
-  Restores the signal handlers to the state they had before the call to
-  dumpStackOnFatalSignal.
-
-This module is not designed to provide fine grained control over signal 
-handling. Nor is it intended to be terribly robust. It may give useful
-information when your program gets unexpected signals, but it might just
-as easily cause a crash when such a signal gets in. 

pyobjc-core/Doc/21protocols.txt

-=======================
-PyObjC protocol support
-=======================
-
-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:
-
- .. sourcecode:: objective-c
-
-	@protocol NSFoo <NSSomeProtocol>
-	-(int)doesIt;
-	@end
-
-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.
-
-Informal protocols are defined as categories on NSObject with no implementation:
-
- .. sourcecode:: objective-c
-
-	@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 (i.e. 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
-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
-registry used by the class builder, so it is not necessary to explicitly
-state that a class implements an informal protocol.
-
-Formal protocols and PyObjC
----------------------------
-
-PyObjC also has an explicit representation for formal protocols. 
-
-Formal protocols are represented as instances of ``objc.formal_protocol``. 
-Unlike informal protocols, it is necessary to explicitly declare
-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.
-
-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')
-
-	class MyLockingObject(NSObject, 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
-
-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

pyobjc-core/Doc/22fsref-fsspec.txt

-Support for ``FSRef`` and ``FSSpec``
-====================================
-
-PyObjC has its own wrappers for the types ``FSRef`` and ``FSSpec``, and also
-supports the wrappers for these types in ``Carbon.File``.
-
-Type ``objc.FSRef``
--------------------
-
-This type represents an opaque ``FSRef`` structure.
-
-New instances are created using the ``from_pathname`` method:
-
- .. sourcecode: pycon
-
-   >>> ref = objc.FSRef.from_pathname("/Libray")
-   >>> isinstance(ref, objc.FSRef)
-   True
-
-Instances of ``objc.FSRef`` are opaque and don't provide access to 
-specific fields in the structure. The following methods and properties
-are available to access an instance:
-
-* ``aref.data``
-
-  A bytestring containing the value of the ``FSRef`` object.
-
-* ``aref.as_pathname()``
-
-  Returns the POSIX path for the ``FSRef`` object.
-
-* ``aref.as_carbon()``
-
-  Returns a ``Carbon.File.FSRef`` instance for the ``FSRef`` object.
-
-  NOTE: This method is only available when ``Carbon`` support is
-  enabled in the Python build.
-
-NOTE: ``Carbon.File.FSRef`` instances can be used as the argument
-of functions that have an ``FSRef`` structure as one of their
-arguments.
-
-Type ``objc.FSSpec``
---------------------
-
-This type represents an opaque ``FSSpec`` structure. It is not possible
-to create ``FSSpec`` instances in Python code.
-
-Instances of ``objc.FSSpec`` are opaque and don't provide access to 
-specific fields in the structure. The following methods and properties
-are available to access an instance:
-
-* ``aref.data``
-
-  A bytestring containing the value of the ``FSRef`` object.
-
-* ``aref.as_carbon()``
-
-  Returns a ``Carbon.File.FSRef`` instance for the ``FSRef`` object.
-
-  NOTE: This method is only available when ``Carbon`` support is
-  enabled in the Python build.
-
-NOTE: ``Carbon.File.FSSpec`` instances can be used as the argument
-of functions that have an ``FSSpec`` structure as one of their
-arguments.

pyobjc-core/Doc/23xcode.txt

-============================
-PyObjC with InterfaceBuilder
-============================
-
-PyObjC can be used with InterfaceBuilder, the best way to use Interface Builder
-depends on the version of Xcode you are using.
-
-XCode 3 on MacOSX 10.5
-----------------------
-
-When you're running MacOSX 10.5, with Xcode 3 or later, Interface Builder has
-builtin support for Python and can extract class, action and outlet definitions
-from Python source code. 
-
-To define a class that will be picked up by Inteface Builder:
-
- .. sourcecode:: python
-
-     class MyModel (NSObject):
-
-          window = objc.IBOutlet()
-
-	  @objc.IBAction
-	  def doSomething_(self, sender):
-	      pass
-
-Inteface Builder obviously has to know about the source files that contain
-your Python classes. There are two ways to accomplisch this, depending on 
-whether or not you use Xcode. If you use Xcode Interface Builder will 
-automaticly pick up all source code that's added to your project and it will
-also automaticly detect changes to those sources. 
-
-If you do not use Xcode you can add new source files to Interface Builder using
-the "File -> Read Class Files ..." menu. This will scan the sources, but will
-not automaticly detect changes to those sources, use the menu 
-"File -> Reload All Class Files" to reload the class definitions.
-
-XCode 2 on MacOSX 10.4
-----------------------
-
-*This section is fairly minimal because I've stopped using Xcode 2 and do all 
-my development on OSX 10.5*
-
-The version of Xcode that ships with Xcode 2 does not support Python code,
-which means that you will have to define your classes twice: one times in 
-actual (Python) code, and then again in Interface Builder.
-
-Deprecation note: ``PyObjCTools.NibClassBuilder``
-.................................................
-
-The module ``PyObjCTools.NibClassBuilder`` allows you to remove some of the
-duplication in class definitions between Python and Interface Builder. This
-module was used a lot before Xcode 3 was released, but is now deprecated and
-doesn't work with NIB files created in Xcode 3.
-
-Please migrate to manual class definitions (as described in the section about
-Xcode 3) as soon as possible. This is slightly more work, but ensures that your
-code will work with later versions of Xcode and PyObjC.

pyobjc-core/Doc/24blocks.txt

-===========================
-PyObjC support for "Blocks"
-===========================
-
-Introduction
-------------
-
-Objective-C has the concept of "blocks", which are basically anonymous inline
-functions. The syntax for them is like this::
-
-	^{ printf("x is %d\n", 42); }
-
-This is a literal for a block that takes no arguments and prints a value when
-called.
-
-Blocks are only suppored when PyObjC is compiled using an Objective-C compiler
-that also supports blocks. 
-
-Calling blocks from Python
---------------------------
-
-The Python representation for a block is a callable object, that is you can
-call the block just like you call any other function object.
-
-PyObjC manages the memory for blocks, it is not necessary to manage the reference
-counts of blocks in your code.
-
-Limitations
-...........
-
-It is not possible to call arbitrary blocks because PyObjC needs to store some
-additional metadata for a block. This means it is only possible to call blocks
-where the bridge knows the call signature, which means:
-
-* Block was returned from a method for which we know the signature of 
-  returned blocks. PyObjC ships with metadata that covers all of Cocoa.
-
-* When a block is stored in a Cocoa datastructure, such as an NSArray, and that
-  is the only reference to the block PyObjC will loose the additional information
-  that is needed to call the block.
-
-It is possible to retrieve and set the call signature of a block using the 
-``__block_signature__`` attribute on blocks.
-
-
-Implementing blocks in Python
------------------------------
-
-It is very easy to use Objective-C methods that have a block as one of their
-arguments: just pass an arbitrary callable. PyObjC will automaticly wrap your
-callable in the right low-level datastructure.
-
-One of the side-effects of this is that the variour storage classes that are
-defined for block-related variables are not relevant for Python users. Blocks
-behave just like regular functions.
-
-Metadata for blocks
--------------------
-
-The current implementation of blocks doesn't allow for full introspection, which means
-that PyObjC must be taught about the signatures of blocks. This section how that
-is done, but note that you only have to do this for your own code that defines methods 
-that have block arguments or return values. The PyObjC wrappers for the various frameworks
-already contain the required metadata. 
-
-FIXME: The last two sentences aren't very clear.
-
-This metadata is an extension to the "bridgesupport" format as defined by Apple.
-
-If an argument or return value is a block the metadata should contain an "block_pointer"
-attribute, with a value of "true". The element then has subelements describing the 
-signature of block (excluding the implict block parameter). 
-
-As an example::
-
-   <arg index="0" block_pointer="true">
-      <retval type="v" />
-      <arg type="@" />
-      <arg type="B" />
-   </arg>
-
-This metadata describes an argument that is a block of type ``(void(^)(id,BOOL)``.

pyobjc-core/Doc/49structure.txt

-============================================
-(Developers) Structure of the PyObjC package
-============================================
-
-Introduction
-------------
-
-This document gives an overview of the PyObjC for developers (of the package).
-
-One of the sections describes how all of it works, and some of the limitations.
-
-This document is a incomplete, it should be updated.
-
-
-Methods
--------
-
-Classes are scanned for methods when the Python wrapper for a class is created.
-We then create Python wrappers for those methods.  This way users can use the
-normal Python introspection methods to check which methods are available.
-
-There are several occasions when these method tables are rescanned, because
-classes can grow new methods when categories are loaded into the runtime.
-Additionally, it is known that some Cocoa frameworks in Mac OS X change
-their method tables when the first instance is created.
-
-Subclassing
------------
-
-It is possible to subclass Objective-C classes from Python.  These classes
-end up in a structure containing both a Python type object and an Objective-C
-class.  Instances of these classes also contain both a Python instance and
-an Objective-C object.
-
-The first Python subclass of an Objective-C class introduces a new instance
-variable in the Objective-C object to store the pointer to the Python half of
-the cluster.  This variable is always referenced by name.  The Python half is 
-a subclass of ``objc_object`` that already contains a pointer to an Objective-C 
-object.  This first subclass also introduces a number of class and instance
-methods that the PyObjC bridge uses to maintain the illusion of a single
-object on both sides.  Check class-builder.m for details.
-
-
-Directory structure
--------------------
-
-Doc/
-  Documentation
-
-Examples/
-  Example scripts and applets.
-
-Lib/
-  The pure Python parts of the packages that comprise PyObjC.  
-
-Modules/
-  Extension modules related to the packages in 'Lib'.
-
-libffi-src/
-  A local copy of libffi, the Foreign Function Interface library used by
-  PyObjC.
-
-Reference counts
-----------------
-
-The Objective-C rules for reference counts are pretty easy: A small number
-of class methods (``alloc``, ``allocWithZone:``, ``copy``, ...) transfer
-object ownership to the caller.  For all other objects you have to call
-``retain`` if you want to keep a reference.  This includes all factory
-methods, such as ``[NSString stringWithCString:"bla"]``!
-
-When programming Cocoa in Python, you rarely need to worry about
-reference counts: the ``objc`` module makes this completely transparent to
-user.  This is mostly implemented in ``[de]pythonify_c_value``.  Additonal
-code is needed when calling methods that transfer ownership of their return
-value (as described above) and when updating a instance variable in an
-Objective-C object (retain new and release old, in that order).  Both are
-implemented.
-
-Strings
--------
-
-Python ``unicode`` instances are proxied by the ``OC_PythonUnicode`` subclass
-of ``NSString``.  This is a proxy, and will maintain the identity of the
-original ``unicode`` instance.
-
-``NSString`` instances are represented in Python as a subtype of ``unicode``:
-``objc.pyobjc_unicode``.  This performs a conversion, because Python's
-``unicode`` type is immutable, but it also maintains a *reference* to the
-original ``NSString``.  ``NSString`` and ``NSMutableString`` methods are
-available from the ``objc.pyobjc_unicode`` object, though they do not show up
-via Python's introspection mechanisms.  In order to get the latest Python
-representation of a ``NSMutableString``, use the return value of its ``self()``
-method.
-
-Python ``str`` instances are proxied by the ``OC_PythonString`` subclass of
-``NSString``.  This is a proxy, and will maintain the identity of the
-original ``str`` instance.  ``OC_PythonString`` will use the default encoding
-of ``NSString``, so its results might be surprising if you are using non-ASCII
-text.  It is recommended that you use ``unicode`` whenever possible.  In order
-to help you determine where you are not using ``unicode``, it is possible
-to trigger an ``objc.PyObjCStrBridgeWarning`` warning whenever a ``str``
-instance crosses the bridge:
-
-
- .. sourcecode:: python
-
-      import objc
-      objc.setStrBridgeEnabled(False)
-
-To promote these to an exception, do the following:
-
- .. sourcecode:: python
-
-      import objc
-      import warnings
-      warnings.filterwarnings('error', objc.PyObjCStrBridgeWarning)

pyobjc-core/Doc/50coding-style.txt

-====================================
-(Developers) Coding style for PyObjC 
-====================================
-
-:authors: Ronald Oussoren,
-          Bill Bumgarner
-:contact: pyobjc-dev@lists.sourceforge.net
-:URL: http://pyobjc.sourceforge.net/
-:copyright: 2002 The PyObjC Project
-
-.. contents::
-
-Introduction
-------------
-
-This document describes the coding style for PyObjC.  Please use this style for
-new code and try apply this style to existing code while working on it.
-
-The management summary: 4-space indents in Python code, 1-TAB indents in C
-code.
-
-Python code
------------
-
-The coding style for core Python is used (see `PEP 8`_).  For consistency with
-Cocoa we use mixed-case identifiers (like ``lookUpClass``).
-
-PyObjC extensions to Apple frameworks should be clearly marked as such, 
-preferably by prefixing names with ``PyObjC`` or ``pyobjc``.  This should make
-it clear to users where they should look for documentation of an item: The
-Apple documentation or ours.
-
-.. _`PEP 8`: http://www.python.org/peps/pep-0008.txt
-
-C code
-------
-
-The coding style for core Python is used (see `PEP 7`_).  We use ``PyObjC`` 
-instead of ``Py`` as the prefix for globally visible symbols.
-
-All (Objective-)C files in ``Modules/objc/`` should include ``"pyobjc.h"`` as
-their first include.  The (Objective-)C files in the wrappers for frameworks
-should include ``"pyobjc-api.h"`` and should not use other include-files in
-``Modules/objc`` other than ``pyobjc-api.h`` and ``wrapper-const-table.h``.
-
-.. _`PEP 7`: http://www.python.org/peps/pep-0007.txt
-
-Documentation
--------------
-
-All items exported by the objc module and all PyObjC extensions to Apple
-frameworks (the AppKit and Foundation modules) should be documented using
-docstrings.
-
-All documentation-- both standalone documents and docstrings-- should be
-marked up using reStructuredText_ [ReST].
-
-ReST in DocStrings
-++++++++++++++++++
-
-reStructuredText_ can be used in doc strings.   ReST in DocStrings works
-exactly like a standalone ReST document, but the ReST is broken up slightly
-differently.
-
-To format the DocStrings to be ReST compatible, make the following
-changes/additions to the source.  These examples were taken from source found
-in the DocUtils source tree. 
-
-(1) Add appropriate ReST style fields to the top of the document as comments::
-
-        # Author: David Goodger
-        # Contact: goodger@users.sourceforge.net
-        # Copyright: This module has been placed in the public domain.
-
-(2) Add a module level variable that indicates that ReST is used to format
-    the text contained in the docstrings::
-
-        __docformat__ = 'reStructuredText'
-    
-(3) Format all other DocStrings as one normally would in Python.   Use ReST
-    style markup where appropriate.   For example, bulleted lists and
-    sections might commonly appear in the module or class docstrings.   The
-    docstrings for individual methods may use example blocks, hyperlinks, or
-    any other ReST markup.
-        
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-

pyobjc-core/Doc/54wrapping.txt

-=====================================================
-(Developers) How to wrap an Objective-C class library
-=====================================================
-
-.. :author: Ronald Oussoren
-
-Introduction
-------------
-
-This document describes how you can wrap on Objective-C class library using
-a Python module or package.  This document assumes that your class library is
-located in a framework.
-
-Wrapping can be pretty easy for most classes, but you may have to write some
-C code for specific methods.
-
-The basics
-----------
-
-The code for loading a framework and exporting its classes is pretty simple:
-
- .. sourcecode: python
-
-    import objc
-    objc.loadBundle("MyFramework", globals(), 
-       bundle_path=objc.pathForFramework(u'/path/to/MyFramework.framework'))
-    del objc
-
-In general you should not load frameworks this way, but you should write a
-package or module to do this for you (e.g. place this code in
-``MyFramework.py`` or ``MyFramework/__init__.py``.  This makes it possible to 
-``import MyFramework`` which is much more convenient.
-
-If your class library does not require helper functions for some methods this
-is all that is needed.
-
-It is currently necessary to import the wrapper modules for all frameworks that
-are used by your framework.  Not doing this may lead to subtle bugs in other
-parts of the code.  This is a limitation of PyObjC that will be 
-lifted in a future version.
-
-Wrapping global functions and constants
----------------------------------------
-
-The code above only provides wrappers for Objective-C classes, if the library
-also defines global functions and/or constants you'll have to write an 
-extension module to make these available to Python.
-
-You can use the PyObjC C-API (to be documented) when writing this module.  With
-some luck you can adapt the scripts in ``Scripts/CodeGenerators`` to generate
-this module for you.  These scripts are both very rough and tuned for the Apple
-headers, so YMMV.
-
-Note that we currently do not install the ``pyobjc-api.h`` header, you'll have
-to copy it from the source-tree until we do.  This header is not installed 
-because the interface is not yet stable, please let us know if you want to
-use the API.
-
-Pointer arguments
------------------
-
-Methods with pointer arguments (other then arguments that are equivalent to 
-an 'id') require more work.  If the pointer arguments are used to pass a single 
-value to/from a function ('pass-by-reference arguments') you'll just have to 
-provide more specific method signatures.  In other cases you'll have to write
-custom wrappers for these methods.
-
-Check ``Modules/Foundation`` for examples of these custom wrappers.
-
-Pass-by-reference arguments
-...........................
-
-Pass-by-reference arguments can be 'in' (data passed into the function), 
-'out' (data is returned from the function) or 'inout' (data is passed into 
-and then returned from  the function). 
-
-Given the following class interface:
-
- .. sourcecode: objective-c
-
-   @interface ClassName {}
-
-   -(void)selector:(id*)outArgument withArguments:(NSArray*)data;
-
-   @end
- 
-The compiler will generate a method signature for this method and this can 
-be accessed from Python using the property 'signature' of Objective-C methods. 
-You can also just make up the signature, which is quite easy once you get the
-hang of it.  The signature for this method is 'v@:^@@'.  See `Type Encodings`_
-for the list of valid encoding characters for the Apple Objective-C runtime.
-
-.. _`Type Encodings`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/RuntimeOverview/chapter_4_section_6.html
-
-Let's say the first argument is an output parameter.  Output parameters are 
-denoted in the signature string using the character 'o' before the actual
-argument signature.  The 'correct' signature for method is therefore 'v@:o^@@'.
-The following code tells the bridge about this better method signature:
-
- .. sourcecode: python
-
-   import objc
-   objc.setSignatureForSelector("ClassName", "selector:withArguments:",
-   	"v@:o^@:@")
-
-To annotate method signatures you'll have to add a single character before all
-'^' characters in the signature of a method.  The characters are:
-
-- output parameter: o
-
-- input parameter: n
-
-- input-output parameter: N
-
-***NOTE:*** The bridge currently supports two other ways to describe metadata,
-which aren't properly documented at the moment.
-
-special wrappers
-................
-
-If the method has pointer arguments that are not pass-by-reference arguments,
-or if the default method wrappers are not suitable for other reasons, you'll
-have to write custom wrappers.  For every custom wrapper you'll have to write
-three functions: 1 to call the method from Python, 1 to call the superclass
-implementation of the method from Python and 1 to call a Python implementation
-of the method from Objective-C.
-
-You also must write a custom wrapper when the method has a variable number
-of arguments.  It is often advisable to documented varargs method as 
-unsupported, or to support them only using a fixed number of arguments.
-
-For now it is best to check the source code for the wrappers for the Cocoa 
-class library for more information.  We'll add documentation for this in the
-future.
-
-protocols
-.........
-
-If the framework defines any (informal) protocols you should add 
-``objc.informal_protocol`` objects for those protocols to your module.  These
-can be defined in a submodule, as long as you arrange for that module to be
-loaded whenever someone imports your package.

pyobjc-core/Doc/blocks.rst

+===========================
+PyObjC support for "Blocks"
+===========================
+
+Introduction
+------------
+
+Objective-C has the concept of "blocks", which are basically anonymous inline
+functions. The syntax for them is like this:
+
+.. sourcecode:: objective-c
+
+	^{ printf("x is %d\n", 42); }
+
+This is a literal for a block that takes no arguments and prints a value when
+called.
+
+Blocks are only suppored when PyObjC is compiled using an Objective-C compiler
+that also supports blocks. 
+
+Calling blocks from Python
+--------------------------
+
+The Python representation for a block is a callable object, that is you can
+call the block just like you call any other function object.
+
+PyObjC manages the memory for blocks, it is not necessary to manage the reference
+counts of blocks in your code.
+
+Limitations
+...........
+
+It is not possible to call arbitrary blocks because PyObjC needs to store some
+additional metadata for a block. This means it is only possible to call blocks
+where the bridge knows the call signature, which means:
+
+* Block was returned from a method for which we know the signature of 
+  returned blocks. PyObjC ships with metadata that covers all of Cocoa.
+
+* When a block is stored in a Cocoa datastructure, such as an NSArray, and that
+  is the only reference to the block PyObjC will loose the additional information
+  that is needed to call the block.
+
+It is possible to retrieve and set the call signature of a block using the 
+``__block_signature__`` attribute on blocks.
+
+
+Implementing blocks in Python
+-----------------------------
+
+It is very easy to use Objective-C methods that have a block as one of their
+arguments: just pass an arbitrary callable. PyObjC will automaticly wrap your
+callable in the right low-level datastructure.
+
+One of the side-effects of this is that the variour storage classes that are
+defined for block-related variables are not relevant for Python users. Blocks
+behave just like regular functions.
+
+Metadata for blocks
+-------------------
+
+The current implementation of blocks doesn't allow for full introspection, which means
+that PyObjC must be taught about the signatures of blocks. This section how that
+is done, but note that you only have to do this for your own code that defines methods 
+that have block arguments or return values. The PyObjC wrappers for the various frameworks
+already contain the required metadata. 
+
+FIXME: The last two sentences aren't very clear.
+
+This metadata is an extension to the "bridgesupport" format as defined by Apple.
+
+If an argument or return value is a block the metadata should contain an "block_pointer"
+attribute, with a value of "true". The element then has subelements describing the 
+signature of block (excluding the implicit block parameter). 
+
+As an example:
+
+.. sourcecode:: xml
+
+   <arg index="0" block_pointer="true">
+      <retval type="v" />
+      <arg type="@" />
+      <arg type="B" />
+   </arg>
+
+This metadata describes an argument that is a block of type ``(void(^)(id,BOOL)``.

pyobjc-core/Doc/dev/coding-style.rst

+=======================
+Coding style for PyObjC 
+=======================
+
+:authors: Ronald Oussoren,
+          Bill Bumgarner
+:contact: pyobjc-dev@lists.sourceforge.net
+:URL: http://pyobjc.sourceforge.net/
+:copyright: 2002 The PyObjC Project
+
+Introduction
+------------
+
+This document describes the coding style for PyObjC.  Please use this style for
+new code and try apply this style to existing code while working on it.
+
+The management summary: 4-space indents in Python code, 1-TAB indents in C
+code.
+
+Python code
+-----------
+
+The coding style for core Python is used (see `PEP 8`_).  For consistency with
+Cocoa we use mixed-case identifiers (like ``lookUpClass``).
+
+PyObjC extensions to Apple frameworks should be clearly marked as such, 
+preferably by prefixing names with ``PyObjC`` or ``pyobjc``.  This should make
+it clear to users where they should look for documentation of an item: The
+Apple documentation or ours.
+
+.. _`PEP 8`: http://www.python.org/peps/pep-0008.txt
+
+C code
+------
+
+The coding style for core Python is used (see `PEP 7`_).  We use ``PyObjC`` 
+instead of ``Py`` as the prefix for globally visible symbols.
+
+All (Objective-)C files in ``Modules/objc/`` should include ``"pyobjc.h"`` as
+their first include.  The (Objective-)C files in the wrappers for frameworks
+should include ``"pyobjc-api.h"`` and should not use other include-files in
+``Modules/objc`` other than ``pyobjc-api.h`` and ``wrapper-const-table.h``.
+
+.. _`PEP 7`: http://www.python.org/peps/pep-0007.txt
+
+Documentation
+-------------
+
+All items exported by the objc module and all PyObjC extensions to Apple
+frameworks (the AppKit and Foundation modules) should be documented using
+docstrings.
+
+All documentation-- both standalone documents and docstrings-- should be
+marked up using reStructuredText_ [ReST].
+
+ReST in DocStrings
+++++++++++++++++++
+
+reStructuredText_ can be used in doc strings.   ReST in DocStrings works
+exactly like a standalone ReST document, but the ReST is broken up slightly
+differently.
+
+To format the DocStrings to be ReST compatible, make the following
+changes/additions to the source.  These examples were taken from source found
+in the DocUtils source tree. 
+
+(1) Add appropriate ReST style fields to the top of the document as comments::
+
+        # Author: David Goodger
+        # Contact: goodger@users.sourceforge.net
+        # Copyright: This module has been placed in the public domain.
+
+(2) Add a module level variable that indicates that ReST is used to format
+    the text contained in the docstrings::
+
+        __docformat__ = 'reStructuredText'
+    
+(3) Format all other DocStrings as one normally would in Python.   Use ReST
+    style markup where appropriate.   For example, bulleted lists and
+    sections might commonly appear in the module or class docstrings.   The
+    docstrings for individual methods may use example blocks, hyperlinks, or
+    any other ReST markup.
+        
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+

pyobjc-core/Doc/dev/structure.rst

+===============================
+Structure of the PyObjC package
+===============================
+
+Introduction
+------------
+
+This document gives an overview of the PyObjC for developers (of the package).
+
+One of the sections describes how all of it works, and some of the limitations.
+
+This document is a incomplete, it should be updated.
+
+
+Methods
+-------
+
+Classes are scanned for methods when the Python wrapper for a class is created.
+We then create Python wrappers for those methods.  This way users can use the
+normal Python introspection methods to check which methods are available.
+
+There are several occasions when these method tables are rescanned, because
+classes can grow new methods when categories are loaded into the runtime.
+Additionally, it is known that some Cocoa frameworks in Mac OS X change
+their method tables when the first instance is created.
+
+Subclassing
+-----------
+
+It is possible to subclass Objective-C classes from Python.  These classes
+end up in a structure containing both a Python type object and an Objective-C
+class.  Instances of these classes also contain both a Python instance and
+an Objective-C object.
+
+The first Python subclass of an Objective-C class introduces a new instance
+variable in the Objective-C object to store the pointer to the Python half of
+the cluster.  This variable is always referenced by name.  The Python half is 
+a subclass of ``objc_object`` that already contains a pointer to an Objective-C 
+object.  This first subclass also introduces a number of class and instance
+methods that the PyObjC bridge uses to maintain the illusion of a single
+object on both sides.  Check class-builder.m for details.
+
+
+Directory structure
+-------------------
+
+Doc/
+  Documentation
+
+Examples/
+  Example scripts and applets.
+
+Lib/
+  The pure Python parts of the packages that comprise PyObjC.  
+
+Modules/
+  Extension modules related to the packages in 'Lib'.
+
+libffi-src/
+  A local copy of libffi, the Foreign Function Interface library used by
+  PyObjC.
+
+Reference counts
+----------------
+
+The Objective-C rules for reference counts are pretty easy: A small number
+of class methods (``alloc``, ``allocWithZone:``, ``copy``, ...) transfer
+object ownership to the caller.  For all other objects you have to call
+``retain`` if you want to keep a reference.  This includes all factory
+methods, such as ``[NSString stringWithCString:"bla"]``!
+
+When programming Cocoa in Python, you rarely need to worry about
+reference counts: the ``objc`` module makes this completely transparent to
+user.  This is mostly implemented in ``[de]pythonify_c_value``.  Additonal
+code is needed when calling methods that transfer ownership of their return
+value (as described above) and when updating a instance variable in an
+Objective-C object (retain new and release old, in that order).  Both are
+implemented.
+
+Strings
+-------
+
+Python ``unicode`` instances are proxied by the ``OC_PythonUnicode`` subclass
+of ``NSString``.  This is a proxy, and will maintain the identity of the
+original ``unicode`` instance.<