[Python-checkins] r57055 - in doctools/trunk: Doc-26/contents.rst Doc-26/howto/index.rst Doc-26/howto/pythonmac.rst Doc-26/library/aepack.rst Doc-26/library/aetools.rst Doc-26/library/aetypes.rst Doc-26/library/autogil.rst Doc-26/library/carbon.rst Doc-26/library/colorpicker.rst Doc-26/library/easydialogs.rst Doc-26/library/filesys.rst Doc-26/library/framework.rst Doc-26/library/gensuitemodule.rst Doc-26/library/ic.rst Doc-26/library/index.rst Doc-26/library/mac.rst Doc-26/library/macos.rst Doc-26/library/macosa.rst Doc-26/library/macostools.rst Doc-26/library/macpath.rst Doc-26/library/miniaeframe.rst Doc-26/library/undoc.rst Doc-26/maclib Doc-3k/contents.rst Doc-3k/howto/index.rst Doc-3k/howto/pythonmac.rst Doc-3k/library/aepack.rst Doc-3k/library/aetools.rst Doc-3k/library/aetypes.rst Doc-3k/library/autogil.rst Doc-3k/library/carbon.rst Doc-3k/library/colorpicker.rst Doc-3k/library/easydialogs.rst Doc-3k/library/filesys.rst Doc-3k/library/framework.rst Doc-3k/library/gensuitemodule.rst Doc-3k/library/ic.rst Doc-3k/library/index.rst Doc-3k/library/mac.rst Doc-3k/library/macos.rst Doc-3k/library/macosa.rst Doc-3k/library/macostools.rst Doc-3k/library/macpath.rst Doc-3k/library/miniaeframe.rst Doc-3k/library/undoc.rst Doc-3k/maclib Makefile sphinx/templates/index.html sphinx/templates/search.html sphinx/web/oldurls.py

georg.brandl python-checkins at python.org
Wed Aug 15 11:01:00 CEST 2007


Author: georg.brandl
Date: Wed Aug 15 11:00:54 2007
New Revision: 57055

Added:
   doctools/trunk/Doc-26/howto/pythonmac.rst
   doctools/trunk/Doc-26/library/aepack.rst
   doctools/trunk/Doc-26/library/aetools.rst
   doctools/trunk/Doc-26/library/aetypes.rst
   doctools/trunk/Doc-26/library/autogil.rst
   doctools/trunk/Doc-26/library/carbon.rst
   doctools/trunk/Doc-26/library/colorpicker.rst
   doctools/trunk/Doc-26/library/easydialogs.rst
   doctools/trunk/Doc-26/library/framework.rst
   doctools/trunk/Doc-26/library/gensuitemodule.rst
   doctools/trunk/Doc-26/library/ic.rst
   doctools/trunk/Doc-26/library/mac.rst
   doctools/trunk/Doc-26/library/macos.rst
   doctools/trunk/Doc-26/library/macosa.rst
   doctools/trunk/Doc-26/library/macostools.rst
   doctools/trunk/Doc-26/library/macpath.rst
   doctools/trunk/Doc-26/library/miniaeframe.rst
   doctools/trunk/Doc-3k/howto/pythonmac.rst
   doctools/trunk/Doc-3k/library/aepack.rst
   doctools/trunk/Doc-3k/library/aetools.rst
   doctools/trunk/Doc-3k/library/aetypes.rst
   doctools/trunk/Doc-3k/library/autogil.rst
   doctools/trunk/Doc-3k/library/carbon.rst
   doctools/trunk/Doc-3k/library/colorpicker.rst
   doctools/trunk/Doc-3k/library/easydialogs.rst
   doctools/trunk/Doc-3k/library/framework.rst
   doctools/trunk/Doc-3k/library/gensuitemodule.rst
   doctools/trunk/Doc-3k/library/ic.rst
   doctools/trunk/Doc-3k/library/mac.rst
   doctools/trunk/Doc-3k/library/macos.rst
   doctools/trunk/Doc-3k/library/macosa.rst
   doctools/trunk/Doc-3k/library/macostools.rst
   doctools/trunk/Doc-3k/library/macpath.rst
   doctools/trunk/Doc-3k/library/miniaeframe.rst
Removed:
   doctools/trunk/Doc-26/maclib/
   doctools/trunk/Doc-3k/maclib/
Modified:
   doctools/trunk/Doc-26/contents.rst
   doctools/trunk/Doc-26/howto/index.rst
   doctools/trunk/Doc-26/library/filesys.rst
   doctools/trunk/Doc-26/library/index.rst
   doctools/trunk/Doc-26/library/undoc.rst
   doctools/trunk/Doc-3k/contents.rst
   doctools/trunk/Doc-3k/howto/index.rst
   doctools/trunk/Doc-3k/library/filesys.rst
   doctools/trunk/Doc-3k/library/index.rst
   doctools/trunk/Doc-3k/library/undoc.rst
   doctools/trunk/Makefile
   doctools/trunk/sphinx/templates/index.html
   doctools/trunk/sphinx/templates/search.html
   doctools/trunk/sphinx/web/oldurls.py
Log:
Merge the Mac library part into the Library part.
The "Using Python on the Mac" is now a HOWTO.


Modified: doctools/trunk/Doc-26/contents.rst
==============================================================================
--- doctools/trunk/Doc-26/contents.rst	(original)
+++ doctools/trunk/Doc-26/contents.rst	Wed Aug 15 11:00:54 2007
@@ -8,7 +8,6 @@
    tutorial/index.rst
    reference/index.rst
    library/index.rst
-   maclib/index.rst
    extending/index.rst
    c-api/index.rst
    distutils/index.rst

Modified: doctools/trunk/Doc-26/howto/index.rst
==============================================================================
--- doctools/trunk/Doc-26/howto/index.rst	(original)
+++ doctools/trunk/Doc-26/howto/index.rst	Wed Aug 15 11:00:54 2007
@@ -14,6 +14,7 @@
    :maxdepth: 1
 
    advocacy.rst
+   pythonmac.rst
    curses.rst
    doanddont.rst
    functional.rst

Added: doctools/trunk/Doc-26/howto/pythonmac.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/howto/pythonmac.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,200 @@
+
+.. _using-on-mac:
+
+***************************
+Using Python on a Macintosh
+***************************
+
+:Author: Bob Savage <bobsavage at mac.com>
+
+
+Python on a Macintosh running Mac OS X is in principle very similar to Python on
+any other Unix platform, but there are a number of additional features such as
+the IDE and the Package Manager that are worth pointing out.
+
+Python on Mac OS 9 or earlier can be quite different from Python on Unix or
+Windows, but is beyond the scope of this manual, as that platform is no longer
+supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
+installers for the latest 2.3 release for Mac OS 9 and related documentation.
+
+
+.. _getting-osx:
+
+Getting and Installing MacPython
+================================
+
+Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are
+encouraged to install the most recent version of Python from the Python website
+(http://www.python.org). A "universal binary" build of Python 2.5, which runs
+natively on the Mac's new Intel and legacy PPC CPU's, is available there.
+
+What you get after installing is a number of things:
+
+* A :file:`MacPython 2.5` folder in your :file:`Applications` folder. In here
+  you find IDLE, the development environment that is a standard part of official
+  Python distributions; PythonLauncher, which handles double-clicking Python
+  scripts from the Finder; and the "Build Applet" tool, which allows you to
+  package Python scripts as standalone applications on your system.
+
+* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
+  Python executable and libraries. The installer adds this location to your shell
+  path. To uninstall MacPython, you can simply remove these three things. A
+  symlink to the Python executable is placed in /usr/local/bin/.
+
+The Apple-provided build of Python is installed in
+:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
+respectively. You should never modify or delete these, as they are
+Apple-controlled and are used by Apple- or third-party software.
+
+IDLE includes a help menu that allows you to access Python documentation. If you
+are completely new to Python you should start reading the tutorial introduction
+in that document.
+
+If you are familiar with Python on other Unix platforms you should read the
+section on running Python scripts from the Unix shell.
+
+
+How to run a Python script
+--------------------------
+
+Your best way to get started with Python on Mac OS X is through the IDLE
+integrated development environment, see section :ref:`ide` and use the Help menu
+when the IDE is running.
+
+If you want to run Python scripts from the Terminal window command line or from
+the Finder you first need an editor to create your script. Mac OS X comes with a
+number of standard Unix command line editors, :program:`vim` and
+:program:`emacs` among them. If you want a more Mac-like editor,
+:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see
+http://www.barebones.com/products/bbedit/index.shtml) are good choices, as is
+:program:`TextMate` (see http://macromates.com/). Other editors include
+:program:`Gvim` (http://macvim.org) and :program:`Aquamacs`
+(http://aquamacs.org).
+
+To run your script from the Terminal window you must make sure that
+:file:`/usr/local/bin` is in your shell search path.
+
+To run your script from the Finder you have two options:
+
+* Drag it to :program:`PythonLauncher`
+
+* Select :program:`PythonLauncher` as the default application to open your
+  script (or any .py script) through the finder Info window and double-click it.
+  :program:`PythonLauncher` has various preferences to control how your script is
+  launched. Option-dragging allows you to change these for one invocation, or use
+  its Preferences menu to change things globally.
+
+
+.. _osx-gui-scripts:
+
+Running scripts with a GUI
+--------------------------
+
+With older versions of Python, there is one Mac OS X quirk that you need to be
+aware of: programs that talk to the Aqua window manager (in other words,
+anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
+instead of :program:`python` to start such scripts.
+
+With Python 2.5, you can use either :program:`python` or :program:`pythonw`.
+
+
+Configuration
+-------------
+
+Python on OS X honors all standard Unix environment variables such as
+:envvar:`PYTHONPATH`, but setting these variables for programs started from the
+Finder is non-standard as the Finder does not read your :file:`.profile` or
+:file:`.cshrc` at startup. You need to create a file :file:`~
+/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details.
+
+For more information on installation Python packages in MacPython, see section
+:ref:`mac-package-manager`.
+
+
+.. _ide:
+
+The IDE
+=======
+
+MacPython ships with the standard IDLE development environment. A good
+introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/
+dyoo/python/idle_intro/index.html.
+
+
+.. _mac-package-manager:
+
+Installing Additional Python Packages
+=====================================
+
+There are several methods to install additional Python packages:
+
+* http://pythonmac.org/packages/ contains selected compiled packages for Python
+  2.5, 2.4, and 2.3.
+
+* Packages can be installed via the standard Python distutils mode (``python
+  setup.py install``).
+
+* Many packages can also be installed via the :program:`setuptools` extension.
+
+
+GUI Programming on the Mac
+==========================
+
+There are several options for building GUI applications on the Mac with Python.
+
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
+the foundation of most modern Mac development. Information on PyObjC is
+available from http://pyobjc.sourceforge.net.
+
+The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform
+Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS
+X by Apple, and the latest version can be downloaded and installed from
+http://www.activestate.com; it can also be built from source.
+
+*wxPython* is another popular cross-platform GUI toolkit that runs natively on
+Mac OS X. Packages and documentation are available from http://www.wxpython.org.
+
+*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac
+OS X. More information can be found at
+http://www.riverbankcomputing.co.uk/pyqt/.
+
+
+Distributing Python Applications on the Mac
+===========================================
+
+The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for
+packaging small Python scripts on your own machine to run as a standard Mac
+application. This tool, however, is not robust enough to distribute Python
+applications to other users.
+
+The standard tool for deploying standalone Python applications on the Mac is
+:program:`py2app`. More information on installing and using py2app can be found
+at http://undefined.org/python/#py2app.
+
+
+Application Scripting
+=====================
+
+Python can also be used to script other Mac applications via Apple's Open
+Scripting Architecture (OSA); see http://appscript.sourceforge.net. Appscript is
+a high-level, user-friendly Apple event bridge that allows you to control
+scriptable Mac OS X applications using ordinary Python scripts. Appscript makes
+Python a serious alternative to Apple's own *AppleScript* language for
+automating your Mac. A related package, *PyOSA*, is an OSA language component
+for the Python scripting language, allowing Python code to be executed by any
+OSA-enabled application (Script Editor, Mail, iTunes, etc.). PyOSA makes Python
+a full peer to AppleScript.
+
+
+Other Resources
+===============
+
+The MacPython mailing list is an excellent support resource for Python users and
+developers on the Mac:
+
+http://www.python.org/community/sigs/current/pythonmac-sig/
+
+Another useful resource is the MacPython wiki:
+
+http://wiki.python.org/moin/MacPython
+

Added: doctools/trunk/Doc-26/library/aepack.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/aepack.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,92 @@
+
+:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
+====================================================================================
+
+.. module:: aepack
+   :platform: Mac
+   :synopsis: Conversion between Python variables and AppleEvent data containers.
+.. sectionauthor:: Vincent Marchetti <vincem at en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aepack` module defines functions for converting (packing) Python
+variables to AppleEvent descriptors and back (unpacking). Within Python the
+AppleEvent descriptor is handled by Python objects of built-in type
+:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
+
+The :mod:`aepack` module defines the following functions:
+
+
+.. function:: pack(x[, forcetype])
+
+   Returns an :class:`AEDesc` object  containing a conversion of Python value x. If
+   *forcetype* is provided it specifies the descriptor type of the result.
+   Otherwise, a default mapping of Python types to Apple Event descriptor types is
+   used, as follows:
+
+   +-----------------+-----------------------------------+
+   | Python type     | descriptor type                   |
+   +=================+===================================+
+   | :class:`FSSpec` | typeFSS                           |
+   +-----------------+-----------------------------------+
+   | :class:`FSRef`  | typeFSRef                         |
+   +-----------------+-----------------------------------+
+   | :class:`Alias`  | typeAlias                         |
+   +-----------------+-----------------------------------+
+   | integer         | typeLong (32 bit integer)         |
+   +-----------------+-----------------------------------+
+   | float           | typeFloat (64 bit floating point) |
+   +-----------------+-----------------------------------+
+   | string          | typeText                          |
+   +-----------------+-----------------------------------+
+   | unicode         | typeUnicodeText                   |
+   +-----------------+-----------------------------------+
+   | list            | typeAEList                        |
+   +-----------------+-----------------------------------+
+   | dictionary      | typeAERecord                      |
+   +-----------------+-----------------------------------+
+   | instance        | *see below*                       |
+   +-----------------+-----------------------------------+
+
+   If *x* is a Python instance then this function attempts to call an
+   :meth:`__aepack__` method.  This method should return an :class:`AEDesc` object.
+
+   If the conversion *x* is not defined above, this function returns the Python
+   string representation of a value (the repr() function) encoded as a text
+   descriptor.
+
+
+.. function:: unpack(x[, formodulename])
+
+   *x* must be an object of type :class:`AEDesc`. This function returns a Python
+   object representation of the data in the Apple Event descriptor *x*. Simple
+   AppleEvent data types (integer, text, float) are returned as their obvious
+   Python counterparts. Apple Event lists are returned as Python lists, and the
+   list elements are recursively unpacked.  Object references (ex. ``line 3 of
+   document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
+   unless ``formodulename`` is specified.  AppleEvent descriptors with descriptor
+   type typeFSS are returned as :class:`FSSpec` objects.  AppleEvent record
+   descriptors are returned as Python dictionaries, with 4-character string keys
+   and elements recursively unpacked.
+
+   The optional ``formodulename`` argument is used by the stub packages generated
+   by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
+   are looked up in the correct module. This ensures that if, say, the Finder
+   returns an object specifier for a window you get an instance of
+   ``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
+   all the properties and elements a window has in the Finder, while the latter
+   knows no such things.
+
+
+.. seealso::
+
+   Module :mod:`Carbon.AE`
+      Built-in access to Apple Event Manager routines.
+
+   Module :mod:`aetypes`
+      Python definitions of codes for Apple Event descriptor types.
+
+   ` Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_
+      Information about inter-process communications on the Macintosh.
+

Added: doctools/trunk/Doc-26/library/aetools.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/aetools.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,86 @@
+
+:mod:`aetools` --- OSA client support
+=====================================
+
+.. module:: aetools
+   :platform: Mac
+   :synopsis: Basic support for sending Apple Events
+.. sectionauthor:: Jack Jansen <Jack.Jansen at cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetools` module contains the basic functionality on which Python
+AppleScript client support is built. It also imports and re-exports the core
+functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
+generated by :mod:`gensuitemodule` import the relevant portions of
+:mod:`aetools`, so usually you do not need to import it yourself. The exception
+to this is when you cannot use a generated suite package and need lower-level
+access to scripting.
+
+The :mod:`aetools` module itself uses the AppleEvent support provided by the
+:mod:`Carbon.AE` module. This has one drawback: you need access to the window
+manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
+lifted in future releases.
+
+The :mod:`aetools` module defines the following functions:
+
+
+.. function:: packevent(ae, parameters, attributes)
+
+   Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
+   ``parameters`` and ``attributes`` are  dictionaries mapping 4-character OSA
+   parameter keys to Python objects. The objects are packed using
+   ``aepack.pack()``.
+
+
+.. function:: unpackevent(ae[, formodulename])
+
+   Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
+   returns the parameter dictionary and the attribute dictionary. The
+   ``formodulename`` argument is used by generated stub packages to control where
+   AppleScript classes are looked up.
+
+
+.. function:: keysubst(arguments, keydict)
+
+   Converts a Python keyword argument dictionary ``arguments`` to the format
+   required by ``packevent`` by replacing the keys, which are Python identifiers,
+   by the four-character OSA keys according to the mapping specified in
+   ``keydict``. Used by the generated suite packages.
+
+
+.. function:: enumsubst(arguments, key, edict)
+
+   If the ``arguments`` dictionary contains an entry for ``key`` convert the value
+   for that entry according to dictionary ``edict``. This converts human-readable
+   Python enumeration names to the OSA 4-character codes. Used by the generated
+   suite packages.
+
+The :mod:`aetools` module defines the following class:
+
+
+.. class:: TalkTo([signature=None, start=0, timeout=0])
+
+   Base class for the proxy used to talk to an application. ``signature`` overrides
+   the class attribute ``_signature`` (which is usually set by subclasses) and is
+   the 4-char creator code defining the application to talk to. ``start`` can be
+   set to true to enable running the application on class instantiation.
+   ``timeout`` can be specified to change the default timeout used while waiting
+   for an AppleEvent reply.
+
+
+.. method:: TalkTo._start()
+
+   Test whether the application is running, and attempt to start it if not.
+
+
+.. method:: TalkTo.send(code, subcode[, parameters, attributes])
+
+   Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
+   ``code, subcode`` (which are the usual 4-character strings), pack the
+   ``parameters`` and ``attributes`` into it, send it to the target application,
+   wait for the reply, unpack the reply with ``unpackevent`` and return the reply
+   appleevent, the unpacked return values as a dictionary and the return
+   attributes.
+

Added: doctools/trunk/Doc-26/library/aetypes.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/aetypes.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,150 @@
+
+:mod:`aetypes` --- AppleEvent objects
+=====================================
+
+.. module:: aetypes
+   :platform: Mac
+   :synopsis: Python representation of the Apple Event Object Model.
+.. sectionauthor:: Vincent Marchetti <vincem at en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetypes` defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is contained in descriptors, and these descriptors are typed.
+For many descriptors the Python representation is simply the corresponding
+Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
+etc. For OSA types that have no direct Python counterpart this module declares
+classes. Packing and unpacking instances of these classes is handled
+automatically by :mod:`aepack`.
+
+An object specifier is essentially an address of an object implemented in a
+Apple Event server. An Apple Event specifier is used as the direct object for an
+Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
+module contains the base classes for OSA classes and properties, which are used
+by the packages generated by :mod:`gensuitemodule` to populate the classes and
+properties in a given suite.
+
+For reasons of backward compatibility, and for cases where you need to script an
+application for which you have not generated the stub package this module also
+contains object specifiers for a number of common OSA classes such as
+``Document``, ``Window``, ``Character``, etc.
+
+The :mod:`AEObjects` module defines the following classes to represent Apple
+Event descriptor data:
+
+
+.. class:: Unknown(type, data)
+
+   The representation of OSA descriptor data for which the :mod:`aepack` and
+   :mod:`aetypes` modules have no support, i.e. anything that is not represented by
+   the other classes here and that is not equivalent to a simple Python value.
+
+
+.. class:: Enum(enum)
+
+   An enumeration value with the given 4-character string value.
+
+
+.. class:: InsertionLoc(of, pos)
+
+   Position ``pos`` in object ``of``.
+
+
+.. class:: Boolean(bool)
+
+   A boolean.
+
+
+.. class:: StyledText(style, text)
+
+   Text with style information (font, face, etc) included.
+
+
+.. class:: AEText(script, style, text)
+
+   Text with script system and style information included.
+
+
+.. class:: IntlText(script, language, text)
+
+   Text with script system and language information included.
+
+
+.. class:: IntlWritingCode(script, language)
+
+   Script system and language information.
+
+
+.. class:: QDPoint(v, h)
+
+   A quickdraw point.
+
+
+.. class:: QDRectangle(v0, h0, v1, h1)
+
+   A quickdraw rectangle.
+
+
+.. class:: RGBColor(r, g, b)
+
+   A color.
+
+
+.. class:: Type(type)
+
+   An OSA type value with the given 4-character name.
+
+
+.. class:: Keyword(name)
+
+   An OSA keyword with the given 4-character name.
+
+
+.. class:: Range(start, stop)
+
+   A range.
+
+
+.. class:: Ordinal(abso)
+
+   Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
+   middle.
+
+
+.. class:: Logical(logc, term)
+
+   The logical expression of applying operator ``logc`` to ``term``.
+
+
+.. class:: Comparison(obj1, relo, obj2)
+
+   The comparison ``relo`` of ``obj1`` to ``obj2``.
+
+The following classes are used as base classes by the generated stub packages to
+represent AppleScript classes and properties in Python:
+
+
+.. class:: ComponentItem(which[, fr])
+
+   Abstract baseclass for an OSA class. The subclass should set the class attribute
+   ``want`` to the 4-character OSA class code. Instances of subclasses of this
+   class are equivalent to AppleScript Object Specifiers. Upon instantiation you
+   should pass a selector in ``which``, and optionally a parent object in ``fr``.
+
+
+.. class:: NProperty(fr)
+
+   Abstract baseclass for an OSA property. The subclass should set the class
+   attributes ``want`` and ``which`` to designate which property we are talking
+   about. Instances of subclasses of this class are Object Specifiers.
+
+
+.. class:: ObjectSpecifier(want, form, seld[, fr])
+
+   Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
+   Specifier. See the Apple Open Scripting Architecture documentation for the
+   parameters. Note that this class is not abstract.
+

Added: doctools/trunk/Doc-26/library/autogil.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/autogil.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,30 @@
+
+:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
+==================================================================
+
+.. module:: autoGIL
+   :platform: Mac
+   :synopsis: Global Interpreter Lock handling in event loops.
+.. moduleauthor:: Just van Rossum <just at letterror.com>
+
+
+The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
+automatically locks and unlocks Python's Global Interpreter Lock when running an
+event loop.
+
+
+.. exception:: AutoGILError
+
+   Raised if the observer callback cannot be installed, for example because the
+   current thread does not have a run loop.
+
+
+.. function:: installAutoGIL()
+
+   Install an observer callback in the event loop (CFRunLoop) for the current
+   thread, that will lock and unlock the Global Interpreter Lock (GIL) at
+   appropriate times, allowing other Python threads to run while the event loop is
+   idle.
+
+   Availability: OSX 10.1 or later.
+

Added: doctools/trunk/Doc-26/library/carbon.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/carbon.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,288 @@
+
+.. _toolbox:
+
+*********************
+MacOS Toolbox Modules
+*********************
+
+There are a set of modules that provide interfaces to various MacOS toolboxes.
+If applicable the module will define a number of Python objects for the various
+structures declared by the toolbox, and operations will be implemented as
+methods of the object.  Other operations will be implemented as functions in the
+module.  Not all operations possible in C will also be possible in Python
+(callbacks are often a problem), and parameters will occasionally be different
+in Python (input and output buffers, especially).  All methods and functions
+have a :attr:`__doc__` string describing their arguments and return values, and
+for additional description you are referred to `Inside Macintosh
+<http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.
+
+These modules all live in a package called :mod:`Carbon`. Despite that name they
+are not all part of the Carbon framework: CF is really in the CoreFoundation
+framework and Qt is in the QuickTime framework. The normal use pattern is ::
+
+   from Carbon import AE
+
+**Warning!**  These modules are not yet documented.  If you wish to contribute
+documentation of any of these modules, please get in touch with docs at python.org.
+
+
+:mod:`Carbon.AE` --- Apple Events
+=================================
+
+.. module:: Carbon.AE
+   :platform: Mac
+   :synopsis: Interface to the Apple Events toolbox.
+
+
+
+:mod:`Carbon.AH` --- Apple Help
+===============================
+
+.. module:: Carbon.AH
+   :platform: Mac
+   :synopsis: Interface to the Apple Help manager.
+
+
+
+:mod:`Carbon.App` --- Appearance Manager
+========================================
+
+.. module:: Carbon.App
+   :platform: Mac
+   :synopsis: Interface to the Appearance Manager.
+
+
+
+:mod:`Carbon.CF` --- Core Foundation
+====================================
+
+.. module:: Carbon.CF
+   :platform: Mac
+   :synopsis: Interface to the Core Foundation.
+
+
+The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
+``CFURL`` objects are supported, some only partially.
+
+
+:mod:`Carbon.CG` --- Core Graphics
+==================================
+
+.. module:: Carbon.CG
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
+================================================
+
+.. module:: Carbon.CarbonEvt
+   :platform: Mac
+   :synopsis: Interface to the Carbon Event Manager.
+
+
+
+:mod:`Carbon.Cm` --- Component Manager
+======================================
+
+.. module:: Carbon.Cm
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.Ctl` --- Control Manager
+=====================================
+
+.. module:: Carbon.Ctl
+   :platform: Mac
+   :synopsis: Interface to the Control Manager.
+
+
+
+:mod:`Carbon.Dlg` --- Dialog Manager
+====================================
+
+.. module:: Carbon.Dlg
+   :platform: Mac
+   :synopsis: Interface to the Dialog Manager.
+
+
+
+:mod:`Carbon.Evt` --- Event Manager
+===================================
+
+.. module:: Carbon.Evt
+   :platform: Mac
+   :synopsis: Interface to the classic Event Manager.
+
+
+
+:mod:`Carbon.Fm` --- Font Manager
+=================================
+
+.. module:: Carbon.Fm
+   :platform: Mac
+   :synopsis: Interface to the Font Manager.
+
+
+
+:mod:`Carbon.Folder` --- Folder Manager
+=======================================
+
+.. module:: Carbon.Folder
+   :platform: Mac
+   :synopsis: Interface to the Folder Manager.
+
+
+
+:mod:`Carbon.Help` --- Help Manager
+===================================
+
+.. module:: Carbon.Help
+   :platform: Mac
+   :synopsis: Interface to the Carbon Help Manager.
+
+
+
+:mod:`Carbon.List` --- List Manager
+===================================
+
+.. module:: Carbon.List
+   :platform: Mac
+   :synopsis: Interface to the List Manager.
+
+
+
+:mod:`Carbon.Menu` --- Menu Manager
+===================================
+
+.. module:: Carbon.Menu
+   :platform: Mac
+   :synopsis: Interface to the Menu Manager.
+
+
+
+:mod:`Carbon.Mlte` --- MultiLingual Text Editor
+===============================================
+
+.. module:: Carbon.Mlte
+   :platform: Mac
+   :synopsis: Interface to the MultiLingual Text Editor.
+
+
+
+:mod:`Carbon.Qd` --- QuickDraw
+==============================
+
+.. module:: Carbon.Qd
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw toolbox.
+
+
+
+:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
+============================================
+
+.. module:: Carbon.Qdoffs
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw Offscreen APIs.
+
+
+
+:mod:`Carbon.Qt` --- QuickTime
+==============================
+
+.. module:: Carbon.Qt
+   :platform: Mac
+   :synopsis: Interface to the QuickTime toolbox.
+
+
+
+:mod:`Carbon.Res` --- Resource Manager and Handles
+==================================================
+
+.. module:: Carbon.Res
+   :platform: Mac
+   :synopsis: Interface to the Resource Manager and Handles.
+
+
+
+:mod:`Carbon.Scrap` --- Scrap Manager
+=====================================
+
+.. module:: Carbon.Scrap
+   :platform: Mac
+   :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
+              clipboard operations.
+
+
+This module is only fully available on MacOS9 and earlier under classic PPC
+MacPython.  Very limited functionality is available under Carbon MacPython.
+
+.. index:: single: Scrap Manager
+
+The Scrap Manager supports the simplest form of cut & paste operations on the
+Macintosh.  It can be use for both inter- and intra-application clipboard
+operations.
+
+The :mod:`Scrap` module provides low-level access to the functions of the Scrap
+Manager.  It contains the following functions:
+
+
+.. function:: InfoScrap()
+
+   Return current information about the scrap.  The information is encoded as a
+   tuple containing the fields ``(size, handle, count, state, path)``.
+
+   +----------+---------------------------------------------+
+   | Field    | Meaning                                     |
+   +==========+=============================================+
+   | *size*   | Size of the scrap in bytes.                 |
+   +----------+---------------------------------------------+
+   | *handle* | Resource object representing the scrap.     |
+   +----------+---------------------------------------------+
+   | *count*  | Serial number of the scrap contents.        |
+   +----------+---------------------------------------------+
+   | *state*  | Integer; positive if in memory, ``0`` if on |
+   |          | disk, negative if uninitialized.            |
+   +----------+---------------------------------------------+
+   | *path*   | Filename of the scrap when stored on disk.  |
+   +----------+---------------------------------------------+
+
+
+.. seealso::
+
+   `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
+      Apple's documentation for the Scrap Manager gives a lot of useful information
+      about using the Scrap Manager in applications.
+
+
+
+:mod:`Carbon.Snd` --- Sound Manager
+===================================
+
+.. module:: Carbon.Snd
+   :platform: Mac
+   :synopsis: Interface to the Sound Manager.
+
+
+
+:mod:`Carbon.TE` --- TextEdit
+=============================
+
+.. module:: Carbon.TE
+   :platform: Mac
+   :synopsis: Interface to TextEdit.
+
+
+
+:mod:`Carbon.Win` --- Window Manager
+====================================
+
+.. module:: Carbon.Win
+   :platform: Mac
+   :synopsis: Interface to the Window Manager.
+
+

Added: doctools/trunk/Doc-26/library/colorpicker.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/colorpicker.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,23 @@
+
+:mod:`ColorPicker` --- Color selection dialog
+=============================================
+
+.. module:: ColorPicker
+   :platform: Mac
+   :synopsis: Interface to the standard color selection dialog.
+.. moduleauthor:: Just van Rossum <just at letterror.com>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
+
+
+The :mod:`ColorPicker` module provides access to the standard color picker
+dialog.
+
+
+.. function:: GetColor(prompt, rgb)
+
+   Show a standard color selection dialog and allow the user to select a color.
+   The user is given instruction by the *prompt* string, and the default color is
+   set to *rgb*.  *rgb* must be a tuple giving the red, green, and blue components
+   of the color. :func:`GetColor` returns a tuple giving the user's selected color
+   and a flag indicating whether they accepted the selection of cancelled.
+

Added: doctools/trunk/Doc-26/library/easydialogs.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/easydialogs.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,207 @@
+
+:mod:`EasyDialogs` --- Basic Macintosh dialogs
+==============================================
+
+.. module:: EasyDialogs
+   :platform: Mac
+   :synopsis: Basic Macintosh dialogs.
+
+
+The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
+All routines take an optional resource ID parameter *id* with which one can
+override the :const:`DLOG` resource used for the dialog, provided that the
+dialog items correspond (both type and item number) to those in the default
+:const:`DLOG` resource. See source code for details.
+
+The :mod:`EasyDialogs` module defines the following functions:
+
+
+.. function:: Message(str[, id[, ok]])
+
+   Displays a modal dialog with the message text *str*, which should be at most 255
+   characters long. The button text defaults to "OK", but is set to the string
+   argument *ok* if the latter is supplied. Control is returned when the user
+   clicks the "OK" button.
+
+
+.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. *prompt* is the prompt
+   message, and the optional *default* supplies the initial value for the string
+   (otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
+   changed with the *ok* and *cancel* arguments. All strings can be at most 255
+   bytes long. :func:`AskString` returns the string entered or :const:`None` in
+   case the user cancelled.
+
+
+.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. Like
+   :func:`AskString`, but with the text shown as bullets. The arguments have the
+   same meaning as for :func:`AskString`.
+
+
+.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
+
+   Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
+   and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
+   The value of *default* (or ``0`` if *default* is not supplied) is returned when
+   the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
+   the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
+   supply ``""`` for the corresponding argument.
+
+
+.. function:: ProgressBar([title[, maxval[, label[, id]]]])
+
+   Displays a modeless progress-bar dialog. This is the constructor for the
+   :class:`ProgressBar` class described below. *title* is the text string displayed
+   (default "Working..."), *maxval* is the value at which progress is complete
+   (default ``0``, indicating that an indeterminate amount of work remains to be
+   done), and *label* is the text that is displayed above the progress bar itself.
+
+
+.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
+
+   Displays a dialog which aids the user in constructing a command-line argument
+   list.  Returns the list in ``sys.argv`` format, suitable for passing as an
+   argument to :func:`getopt.getopt`.  *addoldfile*, *addnewfile*, and *addfolder*
+   are boolean arguments.  When nonzero, they enable the user to insert into the
+   command line paths to an existing file, a (possibly) not-yet-existent file, and
+   a folder, respectively.  (Note: Option arguments must appear in the command line
+   before file and folder arguments in order to be recognized by
+   :func:`getopt.getopt`.)  Arguments containing spaces can be specified by
+   enclosing them within single or double quotes.  A :exc:`SystemExit` exception is
+   raised if the user presses the "Cancel" button.
+
+   *optionlist* is a list that determines a popup menu from which the allowed
+   options are selected.  Its items can take one of two forms: *optstr* or
+   ``(optstr, descr)``.  When present, *descr* is a short descriptive string that
+   is displayed in the dialog while this option is selected in the popup menu.  The
+   correspondence between *optstr*\s and command-line arguments is:
+
+   +----------------------+------------------------------------------+
+   | *optstr* format      | Command-line format                      |
+   +======================+==========================================+
+   | ``x``                | :option:`-x` (short option)              |
+   +----------------------+------------------------------------------+
+   | ``x:`` or ``x=``     | :option:`-x` (short option with value)   |
+   +----------------------+------------------------------------------+
+   | ``xyz``              | :option:`--xyz` (long option)            |
+   +----------------------+------------------------------------------+
+   | ``xyz:`` or ``xyz=`` | :option:`--xyz` (long option with value) |
+   +----------------------+------------------------------------------+
+
+   *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
+   where *descr* is as above.  The *cmdstr*s will appear in a popup menu.  When
+   chosen, the text of *cmdstr* will be appended to the command line as is, except
+   that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
+
+   .. versionadded:: 2.0
+
+
+.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user for a file to open, and return the file selected
+   or :const:`None` if the user cancelled. *message* is a text message to display,
+   *typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
+   pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
+   *location* is the ``(x, y)`` position on the screen where the dialog is shown,
+   *actionButtonLabel* is a string to show instead of "Open" in the OK button,
+   *cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
+   button, *wanted* is the type of value wanted as a return: :class:`str`,
+   :class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
+   acceptable.
+
+   .. index:: single: Navigation Services
+
+   For a description of the other arguments please see the Apple Navigation
+   Services documentation and the :mod:`EasyDialogs` source code.
+
+
+.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
+
+   Post a dialog asking the user for a file to save to, and return the file
+   selected or :const:`None` if the user cancelled. *savedFileName* is the default
+   for the file name to save to (the return value). See :func:`AskFileForOpen` for
+   a description of the other arguments.
+
+
+.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user to select a folder, and return the folder selected
+   or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
+   description of the arguments.
+
+
+.. seealso::
+
+   `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_
+      Programmer's reference documentation for the Navigation Services, a part of the
+      Carbon framework.
+
+
+.. _progressbar-objects:
+
+ProgressBar Objects
+-------------------
+
+:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
+Both determinate (thermometer style) and indeterminate (barber-pole style)
+progress bars are supported.  The bar will be determinate if its maximum value
+is greater than zero; otherwise it will be indeterminate.
+
+.. versionchanged:: 2.2
+   Support for indeterminate-style progress bars was added.
+
+The dialog is displayed immediately after creation. If the dialog's "Cancel"
+button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
+is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
+does not occur until the progress bar is next updated, typically via a call to
+:meth:`inc` or :meth:`set`).  Otherwise, the bar remains visible until the
+:class:`ProgressBar` object is discarded.
+
+:class:`ProgressBar` objects possess the following attributes and methods:
+
+
+.. attribute:: ProgressBar.curval
+
+   The current value (of type integer or long integer) of the progress bar.  The
+   normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
+   This attribute should not be altered directly.
+
+
+.. attribute:: ProgressBar.maxval
+
+   The maximum value (of type integer or long integer) of the progress bar; the
+   progress bar (thermometer style) is full when :attr:`curval` equals
+   :attr:`maxval`.  If :attr:`maxval` is ``0``, the bar will be indeterminate
+   (barber-pole).  This attribute should not be altered directly.
+
+
+.. method:: ProgressBar.title([newstr])
+
+   Sets the text in the title bar of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.label([newstr])
+
+   Sets the text in the progress box of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.set(value[, max])
+
+   Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
+   *max* if the latter is provided.  *value* is first coerced between 0 and
+   :attr:`maxval`.  The thermometer bar is updated to reflect the changes,
+   including a change from indeterminate to determinate or vice versa.
+
+
+.. method:: ProgressBar.inc([n])
+
+   Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
+   provided.  (Note that *n* may be negative, in which case the effect is a
+   decrement.)  The progress bar is updated to reflect the change.  If the bar is
+   indeterminate, this causes one "spin" of the barber pole.  The resulting
+   :attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
+   to fall outside this range.
+

Modified: doctools/trunk/Doc-26/library/filesys.rst
==============================================================================
--- doctools/trunk/Doc-26/library/filesys.rst	(original)
+++ doctools/trunk/Doc-26/library/filesys.rst	Wed Aug 15 11:00:54 2007
@@ -24,6 +24,7 @@
    linecache.rst
    shutil.rst
    dircache.rst
+   macpath.rst
 
 
 .. seealso::

Added: doctools/trunk/Doc-26/library/framework.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/framework.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,335 @@
+
+:mod:`FrameWork` --- Interactive application framework
+======================================================
+
+.. module:: FrameWork
+   :platform: Mac
+   :synopsis: Interactive application framework.
+
+
+The :mod:`FrameWork` module contains classes that together provide a framework
+for an interactive Macintosh application. The programmer builds an application
+by creating subclasses that override various methods of the bases classes,
+thereby implementing the functionality wanted. Overriding functionality can
+often be done on various different levels, i.e. to handle clicks in a single
+dialog window in a non-standard way it is not necessary to override the complete
+event handling.
+
+Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
+available for full Cocoa access from Python, and the documentation describes
+only the most important functionality, and not in the most logical manner at
+that. Examine the source or the examples for more details.  The following are
+some comments posted on the MacPython newsgroup about the strengths and
+limitations of :mod:`FrameWork`:
+
+
+.. epigraph::
+
+   The strong point of :mod:`FrameWork` is that it allows you to break into the
+   control-flow at many different places. :mod:`W`, for instance, uses a different
+   way to enable/disable menus and that plugs right in leaving the rest intact.
+   The weak points of :mod:`FrameWork` are that it has no abstract command
+   interface (but that shouldn't be difficult), that its dialog support is minimal
+   and that its control/toolbar support is non-existent.
+
+The :mod:`FrameWork` module defines the following functions:
+
+
+.. function:: Application()
+
+   An object representing the complete application. See below for a description of
+   the methods. The default :meth:`__init__` routine creates an empty window
+   dictionary and a menu bar with an apple menu.
+
+
+.. function:: MenuBar()
+
+   An object representing the menubar. This object is usually not created by the
+   user.
+
+
+.. function:: Menu(bar, title[, after])
+
+   An object representing a menu. Upon creation you pass the ``MenuBar`` the menu
+   appears in, the *title* string and a position (1-based) *after* where the menu
+   should appear (default: at the end).
+
+
+.. function:: MenuItem(menu, title[, shortcut, callback])
+
+   Create a menu item object. The arguments are the menu to create, the item title
+   string and optionally the keyboard shortcut and a callback routine. The callback
+   is called with the arguments menu-id, item number within menu (1-based), current
+   front window and the event record.
+
+   Instead of a callable object the callback can also be a string. In this case
+   menu selection causes the lookup of a method in the topmost window and the
+   application. The method name is the callback string with ``'domenu_'``
+   prepended.
+
+   Calling the ``MenuBar`` :meth:`fixmenudimstate` method sets the correct dimming
+   for all menu items based on the current front window.
+
+
+.. function:: Separator(menu)
+
+   Add a separator to the end of a menu.
+
+
+.. function:: SubMenu(menu, label)
+
+   Create a submenu named *label* under menu *menu*. The menu object is returned.
+
+
+.. function:: Window(parent)
+
+   Creates a (modeless) window. *Parent* is the application object to which the
+   window belongs. The window is not displayed until later.
+
+
+.. function:: DialogWindow(parent)
+
+   Creates a modeless dialog window.
+
+
+.. function:: windowbounds(width, height)
+
+   Return a ``(left, top, right, bottom)`` tuple suitable for creation of a window
+   of given width and height. The window will be staggered with respect to previous
+   windows, and an attempt is made to keep the whole window on-screen. However, the
+   window will however always be the exact size given, so parts may be offscreen.
+
+
+.. function:: setwatchcursor()
+
+   Set the mouse cursor to a watch.
+
+
+.. function:: setarrowcursor()
+
+   Set the mouse cursor to an arrow.
+
+
+.. _application-objects:
+
+Application Objects
+-------------------
+
+Application objects have the following methods, among others:
+
+
+.. method:: Application.makeusermenus()
+
+   Override this method if you need menus in your application. Append the menus to
+   the attribute :attr:`menubar`.
+
+
+.. method:: Application.getabouttext()
+
+   Override this method to return a text string describing your application.
+   Alternatively, override the :meth:`do_about` method for more elaborate "about"
+   messages.
+
+
+.. method:: Application.mainloop([mask[, wait]])
+
+   This routine is the main event loop, call it to set your application rolling.
+   *Mask* is the mask of events you want to handle, *wait* is the number of ticks
+   you want to leave to other concurrent application (default 0, which is probably
+   not a good idea). While raising *self* to exit the mainloop is still supported
+   it is not recommended: call ``self._quit()`` instead.
+
+   The event loop is split into many small parts, each of which can be overridden.
+   The default methods take care of dispatching events to windows and dialogs,
+   handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.
+
+   In general, all event handlers should return ``1`` if the event is fully handled
+   and ``0`` otherwise (because the front window was not a FrameWork window, for
+   instance). This is needed so that update events and such can be passed on to
+   other windows like the Sioux console window. Calling :func:`MacOS.HandleEvent`
+   is not allowed within *our_dispatch* or its callees, since this may result in an
+   infinite loop if the code is called through the Python inner-loop event handler.
+
+
+.. method:: Application.asyncevents(onoff)
+
+   Call this method with a nonzero parameter to enable asynchronous event handling.
+   This will tell the inner interpreter loop to call the application event handler
+   *async_dispatch* whenever events are available. This will cause FrameWork window
+   updates and the user interface to remain working during long computations, but
+   will slow the interpreter down and may cause surprising results in non-reentrant
+   code (such as FrameWork itself). By default *async_dispatch* will immediately
+   call *our_dispatch* but you may override this to handle only certain events
+   asynchronously. Events you do not handle will be passed to Sioux and such.
+
+   The old on/off value is returned.
+
+
+.. method:: Application._quit()
+
+   Terminate the running :meth:`mainloop` call at the next convenient moment.
+
+
+.. method:: Application.do_char(c, event)
+
+   The user typed character *c*. The complete details of the event can be found in
+   the *event* structure. This method can also be provided in a ``Window`` object,
+   which overrides the application-wide handler if the window is frontmost.
+
+
+.. method:: Application.do_dialogevent(event)
+
+   Called early in the event loop to handle modeless dialog events. The default
+   method simply dispatches the event to the relevant dialog (not through the
+   ``DialogWindow`` object involved). Override if you need special handling of
+   dialog events (keyboard shortcuts, etc).
+
+
+.. method:: Application.idle(event)
+
+   Called by the main event loop when no events are available. The null-event is
+   passed (so you can look at mouse position, etc).
+
+
+.. _window-objects:
+
+Window Objects
+--------------
+
+Window objects have the following methods, among others:
+
+
+.. method:: Window.open()
+
+   Override this method to open a window. Store the MacOS window-id in
+   :attr:`self.wid` and call the :meth:`do_postopen` method to register the window
+   with the parent application.
+
+
+.. method:: Window.close()
+
+   Override this method to do any special processing on window close. Call the
+   :meth:`do_postclose` method to cleanup the parent state.
+
+
+.. method:: Window.do_postresize(width, height, macoswindowid)
+
+   Called after the window is resized. Override if more needs to be done than
+   calling ``InvalRect``.
+
+
+.. method:: Window.do_contentclick(local, modifiers, event)
+
+   The user clicked in the content part of a window. The arguments are the
+   coordinates (window-relative), the key modifiers and the raw event.
+
+
+.. method:: Window.do_update(macoswindowid, event)
+
+   An update event for the window was received. Redraw the window.
+
+
+.. method:: Window.do_activate(activate, event)
+
+   The window was activated (``activate == 1``) or deactivated (``activate == 0``).
+   Handle things like focus highlighting, etc.
+
+
+.. _controlswindow-object:
+
+ControlsWindow Object
+---------------------
+
+ControlsWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: ControlsWindow.do_controlhit(window, control, pcode, event)
+
+   Part *pcode* of control *control* was hit by the user. Tracking and such has
+   already been taken care of.
+
+
+.. _scrolledwindow-object:
+
+ScrolledWindow Object
+---------------------
+
+ScrolledWindow objects are ControlsWindow objects with the following extra
+methods:
+
+
+.. method:: ScrolledWindow.scrollbars([wantx[, wanty]])
+
+   Create (or destroy) horizontal and vertical scrollbars. The arguments specify
+   which you want (default: both). The scrollbars always have minimum ``0`` and
+   maximum ``32767``.
+
+
+.. method:: ScrolledWindow.getscrollbarvalues()
+
+   You must supply this method. It should return a tuple ``(x, y)`` giving the
+   current position of the scrollbars (between ``0`` and ``32767``). You can return
+   ``None`` for either to indicate the whole document is visible in that direction.
+
+
+.. method:: ScrolledWindow.updatescrollbars()
+
+   Call this method when the document has changed. It will call
+   :meth:`getscrollbarvalues` and update the scrollbars.
+
+
+.. method:: ScrolledWindow.scrollbar_callback(which, what, value)
+
+   Supplied by you and called after user interaction. *which* will be ``'x'`` or
+   ``'y'``, *what* will be ``'-'``, ``'--'``, ``'set'``, ``'++'`` or ``'+'``. For
+   ``'set'``, *value* will contain the new scrollbar position.
+
+
+.. method:: ScrolledWindow.scalebarvalues(absmin, absmax, curmin, curmax)
+
+   Auxiliary method to help you calculate values to return from
+   :meth:`getscrollbarvalues`. You pass document minimum and maximum value and
+   topmost (leftmost) and bottommost (rightmost) visible values and it returns the
+   correct number or ``None``.
+
+
+.. method:: ScrolledWindow.do_activate(onoff, event)
+
+   Takes care of dimming/highlighting scrollbars when a window becomes frontmost.
+   If you override this method, call this one at the end of your method.
+
+
+.. method:: ScrolledWindow.do_postresize(width, height, window)
+
+   Moves scrollbars to the correct position. Call this method initially if you
+   override it.
+
+
+.. method:: ScrolledWindow.do_controlhit(window, control, pcode, event)
+
+   Handles scrollbar interaction. If you override it call this method first, a
+   nonzero return value indicates the hit was in the scrollbars and has been
+   handled.
+
+
+.. _dialogwindow-objects:
+
+DialogWindow Objects
+--------------------
+
+DialogWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: DialogWindow.open(resid)
+
+   Create the dialog window, from the DLOG resource with id *resid*. The dialog
+   object is stored in :attr:`self.wid`.
+
+
+.. method:: DialogWindow.do_itemhit(item, event)
+
+   Item number *item* was hit. You are responsible for redrawing toggle buttons,
+   etc.
+

Added: doctools/trunk/Doc-26/library/gensuitemodule.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/gensuitemodule.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,63 @@
+
+:mod:`gensuitemodule` --- Generate OSA stub packages
+====================================================
+
+.. module:: gensuitemodule
+   :platform: Mac
+   :synopsis: Create a stub package from an OSA dictionary
+.. sectionauthor:: Jack Jansen <Jack.Jansen at cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`gensuitemodule` module creates a Python package implementing stub code
+for the AppleScript suites that are implemented by a specific application,
+according to its AppleScript dictionary.
+
+It is usually invoked by the user through the :program:`PythonIDE`, but it can
+also be run as a script from the command line (pass :option:`--help` for help on
+the options) or imported from Python code. For an example of its use see
+:file:`Mac/scripts/genallsuites.py` in a source distribution, which generates
+the stub packages that are included in the standard library.
+
+It defines the following public functions:
+
+
+.. function:: is_scriptable(application)
+
+   Returns true if ``application``, which should be passed as a pathname, appears
+   to be scriptable. Take the return value with a grain of salt: :program:`Internet
+   Explorer` appears not to be scriptable but definitely is.
+
+
+.. function:: processfile(application[, output, basepkgname,  edit_modnames, creatorsignature, dump, verbose])
+
+   Create a stub package for ``application``, which should be passed as a full
+   pathname. For a :file:`.app` bundle this is the pathname to the bundle, not to
+   the executable inside the bundle; for an unbundled CFM application you pass the
+   filename of the application binary.
+
+   This function asks the application for its OSA terminology resources, decodes
+   these resources and uses the resultant data to create the Python code for the
+   package implementing the client stubs.
+
+   ``output`` is the pathname where the resulting package is stored, if not
+   specified a standard "save file as" dialog is presented to the user.
+   ``basepkgname`` is the base package on which this package will build, and
+   defaults to :mod:`StdSuites`. Only when generating :mod:`StdSuites` itself do
+   you need to specify this. ``edit_modnames`` is a dictionary that can be used to
+   change modulenames that are too ugly after name mangling. ``creator_signature``
+   can be used to override the 4-char creator code, which is normally obtained from
+   the :file:`PkgInfo` file in the package or from the CFM file creator signature.
+   When ``dump`` is given it should refer to a file object, and ``processfile``
+   will stop after decoding the resources and dump the Python representation of the
+   terminology resources to this file. ``verbose`` should also be a file object,
+   and specifying it will cause ``processfile`` to tell you what it is doing.
+
+
+.. function:: processfile_fromresource(application[, output,  basepkgname, edit_modnames, creatorsignature, dump, verbose])
+
+   This function does the same as ``processfile``, except that it uses a different
+   method to get the terminology resources. It opens ``application`` as a resource
+   file and reads all ``"aete"`` and ``"aeut"`` resources from this file.
+

Added: doctools/trunk/Doc-26/library/ic.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/ic.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,119 @@
+
+:mod:`ic` --- Access to the Mac OS X Internet Config
+====================================================
+
+.. module:: ic
+   :platform: Mac
+   :synopsis: Access to the Mac OS X Internet Config.
+
+
+This module provides access to various internet-related preferences set through
+:program:`System Preferences` or the :program:`Finder`.
+
+.. index:: module: icglue
+
+There is a low-level companion module :mod:`icglue` which provides the basic
+Internet Config access functionality.  This low-level module is not documented,
+but the docstrings of the routines document the parameters and the routine names
+are the same as for the Pascal or C API to Internet Config, so the standard IC
+programmers' documentation can be used if this module is needed.
+
+The :mod:`ic` module defines the :exc:`error` exception and symbolic names for
+all error codes Internet Config can produce; see the source for details.
+
+
+.. exception:: error
+
+   Exception raised on errors in the :mod:`ic` module.
+
+The :mod:`ic` module defines the following class and function:
+
+
+.. class:: IC([signature[, ic]])
+
+   Create an Internet Config object. The signature is a 4-character creator code of
+   the current application (default ``'Pyth'``) which may influence some of ICs
+   settings. The optional *ic* argument is a low-level ``icglue.icinstance``
+   created beforehand, this may be useful if you want to get preferences from a
+   different config file, etc.
+
+
+.. function:: launchurl(url[, hint])
+              parseurl(data[, start[, end[, hint]]])
+              mapfile(file)
+              maptypecreator(type, creator[, filename])
+              settypecreator(file)
+
+   These functions are "shortcuts" to the methods of the same name, described
+   below.
+
+
+IC Objects
+----------
+
+:class:`IC` objects have a mapping interface, hence to obtain the mail address
+you simply get ``ic['MailAddress']``. Assignment also works, and changes the
+option in the configuration file.
+
+The module knows about various datatypes, and converts the internal IC
+representation to a "logical" Python data structure. Running the :mod:`ic`
+module standalone will run a test program that lists all keys and values in your
+IC database, this will have to serve as documentation.
+
+If the module does not know how to represent the data it returns an instance of
+the ``ICOpaqueData`` type, with the raw data in its :attr:`data` attribute.
+Objects of this type are also acceptable values for assignment.
+
+Besides the dictionary interface, :class:`IC` objects have the following
+methods:
+
+
+.. method:: IC.launchurl(url[, hint])
+
+   Parse the given URL, launch the correct application and pass it the URL. The
+   optional *hint* can be a scheme name such as ``'mailto:'``, in which case
+   incomplete URLs are completed with this scheme.  If *hint* is not provided,
+   incomplete URLs are invalid.
+
+
+.. method:: IC.parseurl(data[, start[, end[, hint]]])
+
+   Find an URL somewhere in *data* and return start position, end position and the
+   URL. The optional *start* and *end* can be used to limit the search, so for
+   instance if a user clicks in a long text field you can pass the whole text field
+   and the click-position in *start* and this routine will return the whole URL in
+   which the user clicked.  As above, *hint* is an optional scheme used to complete
+   incomplete URLs.
+
+
+.. method:: IC.mapfile(file)
+
+   Return the mapping entry for the given *file*, which can be passed as either a
+   filename or an :func:`FSSpec` result, and which need not exist.
+
+   The mapping entry is returned as a tuple ``(version, type, creator, postcreator,
+   flags, extension, appname, postappname, mimetype, entryname)``, where *version*
+   is the entry version number, *type* is the 4-character filetype, *creator* is
+   the 4-character creator type, *postcreator* is the 4-character creator code of
+   an optional application to post-process the file after downloading, *flags* are
+   various bits specifying whether to transfer in binary or ascii and such,
+   *extension* is the filename extension for this file type, *appname* is the
+   printable name of the application to which this file belongs, *postappname* is
+   the name of the postprocessing application, *mimetype* is the MIME type of this
+   file and *entryname* is the name of this entry.
+
+
+.. method:: IC.maptypecreator(type, creator[, filename])
+
+   Return the mapping entry for files with given 4-character *type* and *creator*
+   codes. The optional *filename* may be specified to further help finding the
+   correct entry (if the creator code is ``'????'``, for instance).
+
+   The mapping entry is returned in the same format as for *mapfile*.
+
+
+.. method:: IC.settypecreator(file)
+
+   Given an existing *file*, specified either as a filename or as an :func:`FSSpec`
+   result, set its creator and type correctly based on its extension.  The finder
+   is told about the change, so the finder icon will be updated quickly.

Modified: doctools/trunk/Doc-26/library/index.rst
==============================================================================
--- doctools/trunk/Doc-26/library/index.rst	(original)
+++ doctools/trunk/Doc-26/library/index.rst	Wed Aug 15 11:00:54 2007
@@ -78,6 +78,8 @@
    misc.rst
    windows.rst
    unix.rst
+   mac.rst
+   macosa.rst
    sgi.rst
    sun.rst
    undoc.rst

Added: doctools/trunk/Doc-26/library/mac.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/mac.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,19 @@
+
+*************************
+MacOS X specific services
+*************************
+
+This chapter describes modules that are only available on the Mac OS X platform.
+
+See also the chapters :ref:`mac-scripting` and :ref:`undoc-mac-modules`.
+
+.. toctree::
+
+   ic.rst
+   macos.rst
+   macostools.rst
+   easydialogs.rst
+   framework.rst
+   autogil.rst
+   carbon.rst
+   colorpicker.rst
\ No newline at end of file

Added: doctools/trunk/Doc-26/library/macos.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/macos.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,95 @@
+
+:mod:`MacOS` --- Access to Mac OS interpreter features
+======================================================
+
+.. module:: MacOS
+   :platform: Mac
+   :synopsis: Access to Mac OS-specific interpreter features.
+
+
+This module provides access to MacOS specific functionality in the Python
+interpreter, such as how the interpreter eventloop functions and the like. Use
+with care.
+
+Note the capitalization of the module name; this is a historical artifact.
+
+
+.. data:: runtimemodel
+
+   Always ``'macho'``, from Python 2.4 on. In earlier versions of Python the value
+   could also be ``'ppc'`` for the classic Mac OS 8 runtime model or ``'carbon'``
+   for the Mac OS 9 runtime model.
+
+
+.. data:: linkmodel
+
+   The way the interpreter has been linked. As extension modules may be
+   incompatible between linking models, packages could use this information to give
+   more decent error messages. The value is one of ``'static'`` for a statically
+   linked Python, ``'framework'`` for Python in a Mac OS X framework, ``'shared'``
+   for Python in a standard Unix shared library. Older Pythons could also have the
+   value ``'cfm'`` for Mac OS 9-compatible Python.
+
+
+.. exception:: Error
+
+   .. index:: module: macerrors
+
+   This exception is raised on MacOS generated errors, either from functions in
+   this module or from other mac-specific modules like the toolbox interfaces. The
+   arguments are the integer error code (the :cdata:`OSErr` value) and a textual
+   description of the error code. Symbolic names for all known error codes are
+   defined in the standard module :mod:`macerrors`.
+
+
+.. function:: GetErrorString(errno)
+
+   Return the textual description of MacOS error code *errno*.
+
+
+.. function:: DebugStr(message [, object])
+
+   On Mac OS X the string is simply printed to stderr (on older Mac OS systems more
+   elaborate functionality was available), but it provides a convenient location to
+   attach a breakpoint in a low-level debugger like :program:`gdb`.
+
+
+.. function:: SysBeep()
+
+   Ring the bell.
+
+
+.. function:: GetTicks()
+
+   Get the number of clock ticks (1/60th of a second) since system boot.
+
+
+.. function:: GetCreatorAndType(file)
+
+   Return the file creator and file type as two four-character strings. The *file*
+   parameter can be a pathname or an ``FSSpec`` or  ``FSRef`` object.
+
+
+.. function:: SetCreatorAndType(file, creator, type)
+
+   Set the file creator and file type. The *file* parameter can be a pathname or an
+   ``FSSpec`` or  ``FSRef`` object. *creator* and *type* must be four character
+   strings.
+
+
+.. function:: openrf(name [, mode])
+
+   Open the resource fork of a file. Arguments are the same as for the built-in
+   function :func:`open`. The object returned has file-like semantics, but it is
+   not a Python file object, so there may be subtle differences.
+
+
+.. function:: WMAvailable()
+
+   Checks whether the current process has access to the window manager. The method
+   will return ``False`` if the window manager is not available, for instance when
+   running on Mac OS X Server or when logged in via ssh, or when the current
+   interpreter is not running from a fullblown application bundle. A script runs
+   from an application bundle either when it has been started with
+   :program:`pythonw` instead of :program:`python` or when running  as an applet.
+

Added: doctools/trunk/Doc-26/library/macosa.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/macosa.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,92 @@
+
+.. _mac-scripting:
+
+*********************
+MacPython OSA Modules
+*********************
+
+This chapter describes the current implementation of the Open Scripting
+Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
+you to control scriptable applications from your Python program, and with a
+fairly pythonic interface. Development on this set of modules has stopped, and a
+replacement is expected for Python 2.5.
+
+For a description of the various components of AppleScript and OSA, and to get
+an understanding of the architecture and terminology, you should read Apple's
+documentation. The "Applescript Language Guide" explains the conceptual model
+and the terminology, and documents the standard suite. The "Open Scripting
+Architecture" document explains how to use OSA from an application programmers
+point of view. In the Apple Help Viewer these books are located in the Developer
+Documentation, Core Technologies section.
+
+As an example of scripting an application, the following piece of AppleScript
+will get the name of the frontmost :program:`Finder` window and print it::
+
+   tell application "Finder"
+       get name of window 1
+   end tell
+
+In Python, the following code fragment will do the same::
+
+   import Finder
+
+   f = Finder.Finder()
+   print f.get(f.window(1).name)
+
+As distributed the Python library includes packages that implement the standard
+suites, plus packages that interface to a small number of common applications.
+
+To send AppleEvents to an application you must first create the Python package
+interfacing to the terminology of the application (what :program:`Script Editor`
+calls the "Dictionary"). This can be done from within the :program:`PythonIDE`
+or by running the :file:`gensuitemodule.py` module as a standalone program from
+the command line.
+
+The generated output is a package with a number of modules, one for every suite
+used in the program plus an :mod:`__init__` module to glue it all together. The
+Python inheritance graph follows the AppleScript inheritance graph, so if a
+program's dictionary specifies that it includes support for the Standard Suite,
+but extends one or two verbs with extra arguments then the output suite will
+contain a module :mod:`Standard_Suite` that imports and re-exports everything
+from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra
+functionality. The output of :mod:`gensuitemodule` is pretty readable, and
+contains the documentation that was in the original AppleScript dictionary in
+Python docstrings, so reading it is a good source of documentation.
+
+The output package implements a main class with the same name as the package
+which contains all the AppleScript verbs as methods, with the direct object as
+the first argument and all optional parameters as keyword arguments. AppleScript
+classes are also implemented as Python classes, as are comparisons and all the
+other thingies.
+
+The main Python class implementing the verbs also allows access to the
+properties and elements declared in the AppleScript class "application". In the
+current release that is as far as the object orientation goes, so in the example
+above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic
+``f.window(1).name.get()``.
+
+If an AppleScript identifier is not a Python identifier the name is mangled
+according to a small number of rules:
+
+* spaces are replaced with underscores
+
+* other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is
+  the hexadecimal character value
+
+* any Python reserved word gets an underscore appended
+
+Python also has support for creating scriptable applications in Python, but The
+following modules are relevant to MacPython AppleScript support:
+
+.. toctree::
+
+   gensuitemodule.rst
+   aetools.rst
+   aepack.rst
+   aetypes.rst
+   miniaeframe.rst
+
+
+In addition, support modules have been pre-generated for :mod:`Finder`,
+:mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,
+:mod:`SystemEvents` and :mod:`StdSuites`.

Added: doctools/trunk/Doc-26/library/macostools.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/macostools.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,115 @@
+
+:mod:`macostools` --- Convenience routines for file manipulation
+================================================================
+
+.. module:: macostools
+   :platform: Mac
+   :synopsis: Convenience routines for file manipulation.
+
+
+This module contains some convenience routines for file-manipulation on the
+Macintosh. All file parameters can be specified as pathnames, :class:`FSRef` or
+:class:`FSSpec` objects.  This module expects a filesystem which supports forked
+files, so it should not be used on UFS partitions.
+
+The :mod:`macostools` module defines the following functions:
+
+
+.. function:: copy(src, dst[, createpath[, copytimes]])
+
+   Copy file *src* to *dst*.  If *createpath* is non-zero the folders leading to
+   *dst* are created if necessary. The method copies data and resource fork and
+   some finder information (creator, type, flags) and optionally the creation,
+   modification and backup times (default is to copy them). Custom icons, comments
+   and icon position are not copied.
+
+
+.. function:: copytree(src, dst)
+
+   Recursively copy a file tree from *src* to *dst*, creating folders as needed.
+   *src* and *dst* should be specified as pathnames.
+
+
+.. function:: mkalias(src, dst)
+
+   Create a finder alias *dst* pointing to *src*.
+
+
+.. function:: touched(dst)
+
+   Tell the finder that some bits of finder-information such as creator or type for
+   file *dst* has changed. The file can be specified by pathname or fsspec. This
+   call should tell the finder to redraw the files icon.
+
+   .. deprecated:: 2.6
+      The function is a no-op on OS X.
+
+
+.. data:: BUFSIZ
+
+   The buffer size for ``copy``, default 1 megabyte.
+
+Note that the process of creating finder aliases is not specified in the Apple
+documentation. Hence, aliases created with :func:`mkalias` could conceivably
+have incompatible behaviour in some cases.
+
+
+:mod:`findertools` --- The :program:`finder`'s Apple Events interface
+=====================================================================
+
+.. module:: findertools
+   :platform: Mac
+   :synopsis: Wrappers around the finder's Apple Events interface.
+
+
+.. index:: single: AppleEvents
+
+This module contains routines that give Python programs access to some
+functionality provided by the finder. They are implemented as wrappers around
+the AppleEvent interface to the finder.
+
+All file and folder parameters can be specified either as full pathnames, or as
+:class:`FSRef` or :class:`FSSpec` objects.
+
+The :mod:`findertools` module defines the following functions:
+
+
+.. function:: launch(file)
+
+   Tell the finder to launch *file*. What launching means depends on the file:
+   applications are started, folders are opened and documents are opened in the
+   correct application.
+
+
+.. function:: Print(file)
+
+   Tell the finder to print a file. The behaviour is identical to selecting the
+   file and using the print command in the finder's file menu.
+
+
+.. function:: copy(file, destdir)
+
+   Tell the finder to copy a file or folder *file* to folder *destdir*. The
+   function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: move(file, destdir)
+
+   Tell the finder to move a file or folder *file* to folder *destdir*. The
+   function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: sleep()
+
+   Tell the finder to put the Macintosh to sleep, if your machine supports it.
+
+
+.. function:: restart()
+
+   Tell the finder to perform an orderly restart of the machine.
+
+
+.. function:: shutdown()
+
+   Tell the finder to perform an orderly shutdown of the machine.
+

Added: doctools/trunk/Doc-26/library/macpath.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/macpath.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,17 @@
+
+:mod:`macpath` --- MacOS 9 path manipulation functions
+======================================================
+
+.. module:: macpath
+   :synopsis: MacOS 9 path manipulation functions.
+
+
+This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path`
+module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X
+(or any other platform).
+
+The following functions are available in this module: :func:`normcase`,
+:func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`,
+:func:`isfile`, :func:`walk`, :func:`exists`. For other functions available in
+:mod:`os.path` dummy counterparts are available.
+

Added: doctools/trunk/Doc-26/library/miniaeframe.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-26/library/miniaeframe.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,68 @@
+
+:mod:`MiniAEFrame` --- Open Scripting Architecture server support
+=================================================================
+
+.. module:: MiniAEFrame
+   :platform: Mac
+   :synopsis: Support to act as an Open Scripting Architecture (OSA) server ("Apple Events").
+
+
+.. index::
+   single: Open Scripting Architecture
+   single: AppleEvents
+   module: FrameWork
+
+The module :mod:`MiniAEFrame` provides a framework for an application that can
+function as an Open Scripting Architecture  (OSA) server, i.e. receive and
+process AppleEvents. It can be used in conjunction with :mod:`FrameWork` or
+standalone. As an example, it is used in :program:`PythonCGISlave`.
+
+The :mod:`MiniAEFrame` module defines the following classes:
+
+
+.. class:: AEServer()
+
+   A class that handles AppleEvent dispatch. Your application should subclass this
+   class together with either :class:`MiniApplication` or
+   :class:`FrameWork.Application`. Your :meth:`__init__` method should call the
+   :meth:`__init__` method for both classes.
+
+
+.. class:: MiniApplication()
+
+   A class that is more or less compatible with :class:`FrameWork.Application` but
+   with less functionality. Its event loop supports the apple menu, command-dot and
+   AppleEvents; other events are passed on to the Python interpreter and/or Sioux.
+   Useful if your application wants to use :class:`AEServer` but does not provide
+   its own windows, etc.
+
+
+.. _aeserver-objects:
+
+AEServer Objects
+----------------
+
+
+.. method:: AEServer.installaehandler(classe, type, callback)
+
+   Installs an AppleEvent handler. *classe* and *type* are the four-character OSA
+   Class and Type designators, ``'****'`` wildcards are allowed. When a matching
+   AppleEvent is received the parameters are decoded and your callback is invoked.
+
+
+.. method:: AEServer.callback(_object, **kwargs)
+
+   Your callback is called with the OSA Direct Object as first positional
+   parameter. The other parameters are passed as keyword arguments, with the
+   4-character designator as name. Three extra keyword parameters are passed:
+   ``_class`` and ``_type`` are the Class and Type designators and ``_attributes``
+   is a dictionary with the AppleEvent attributes.
+
+   The return value of your method is packed with :func:`aetools.packevent` and
+   sent as reply.
+
+Note that there are some serious problems with the current design. AppleEvents
+which have non-identifier 4-character designators for arguments are not
+implementable, and it is not possible to return an error to the originator. This
+will be addressed in a future release.
+

Modified: doctools/trunk/Doc-26/library/undoc.rst
==============================================================================
--- doctools/trunk/Doc-26/library/undoc.rst	(original)
+++ doctools/trunk/Doc-26/library/undoc.rst	Wed Aug 15 11:00:54 2007
@@ -14,15 +14,6 @@
 revised.
 
 
-Frameworks
-==========
-
-Frameworks tend to be harder to document, but are well worth the effort spent.
-
-
-   None at this time.
-
-
 Miscellaneous useful utilities
 ==============================
 
@@ -71,6 +62,128 @@
    or demo.  Requires the external program :program:`sox`.
 
 
+.. _undoc-mac-modules:
+
+Undocumented Mac OS modules
+===========================
+
+
+:mod:`applesingle` --- AppleSingle decoder
+------------------------------------------
+
+.. module:: applesingle
+   :platform: Mac
+   :synopsis: Rudimentary decoder for AppleSingle format files.
+
+
+
+:mod:`buildtools` --- Helper module for BuildApplet and Friends
+---------------------------------------------------------------
+
+.. module:: buildtools
+   :platform: Mac
+   :synopsis: Helper module for BuildApplet, BuildApplication and macfreeze.
+
+
+.. deprecated:: 2.4
+
+:mod:`cfmfile` --- Code Fragment Resource module
+------------------------------------------------
+
+.. module:: cfmfile
+   :platform: Mac
+   :synopsis: Code Fragment Resource module.
+
+
+:mod:`cfmfile` is a module that understands Code Fragments and the accompanying
+"cfrg" resources. It can parse them and merge them, and is used by
+BuildApplication to combine all plugin modules to a single executable.
+
+.. deprecated:: 2.4
+
+:mod:`icopen` --- Internet Config replacement for :meth:`open`
+--------------------------------------------------------------
+
+.. module:: icopen
+   :platform: Mac
+   :synopsis: Internet Config replacement for open().
+
+
+Importing :mod:`icopen` will replace the builtin :meth:`open` with a version
+that uses Internet Config to set file type and creator for new files.
+
+
+:mod:`macerrors` --- Mac OS Errors
+----------------------------------
+
+.. module:: macerrors
+   :platform: Mac
+   :synopsis: Constant definitions for many Mac OS error codes.
+
+
+:mod:`macerrors` contains constant definitions for many Mac OS error codes.
+
+
+:mod:`macresource` --- Locate script resources
+----------------------------------------------
+
+.. module:: macresource
+   :platform: Mac
+   :synopsis: Locate script resources.
+
+
+:mod:`macresource` helps scripts finding their resources, such as dialogs and
+menus, without requiring special case code for when the script is run under
+MacPython, as a MacPython applet or under OSX Python.
+
+
+:mod:`Nav` --- NavServices calls
+--------------------------------
+
+.. module:: Nav
+   :platform: Mac
+   :synopsis: Interface to Navigation Services.
+
+
+A low-level interface to Navigation Services.
+
+
+:mod:`PixMapWrapper` --- Wrapper for PixMap objects
+---------------------------------------------------
+
+.. module:: PixMapWrapper
+   :platform: Mac
+   :synopsis: Wrapper for PixMap objects.
+
+
+:mod:`PixMapWrapper` wraps a PixMap object with a Python object that allows
+access to the fields by name. It also has methods to convert to and from
+:mod:`PIL` images.
+
+
+:mod:`videoreader` --- Read QuickTime movies
+--------------------------------------------
+
+.. module:: videoreader
+   :platform: Mac
+   :synopsis: Read QuickTime movies frame by frame for further processing.
+
+
+:mod:`videoreader` reads and decodes QuickTime movies and passes a stream of
+images to your program. It also provides some support for audio tracks.
+
+
+:mod:`W` --- Widgets built on :mod:`FrameWork`
+----------------------------------------------
+
+.. module:: W
+   :platform: Mac
+   :synopsis: Widgets for the Mac, built on top of FrameWork.
+
+
+The :mod:`W` widgets are used extensively in the :program:`IDE`.
+
+
 .. _obsolete-modules:
 
 Obsolete

Modified: doctools/trunk/Doc-3k/contents.rst
==============================================================================
--- doctools/trunk/Doc-3k/contents.rst	(original)
+++ doctools/trunk/Doc-3k/contents.rst	Wed Aug 15 11:00:54 2007
@@ -8,7 +8,6 @@
    tutorial/index.rst
    reference/index.rst
    library/index.rst
-   maclib/index.rst
    extending/index.rst
    c-api/index.rst
    distutils/index.rst

Modified: doctools/trunk/Doc-3k/howto/index.rst
==============================================================================
--- doctools/trunk/Doc-3k/howto/index.rst	(original)
+++ doctools/trunk/Doc-3k/howto/index.rst	Wed Aug 15 11:00:54 2007
@@ -14,6 +14,7 @@
    :maxdepth: 1
 
    advocacy.rst
+   pythonmac.rst
    curses.rst
    doanddont.rst
    functional.rst

Added: doctools/trunk/Doc-3k/howto/pythonmac.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/howto/pythonmac.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,200 @@
+
+.. _using-on-mac:
+
+***************************
+Using Python on a Macintosh
+***************************
+
+:Author: Bob Savage <bobsavage at mac.com>
+
+
+Python on a Macintosh running Mac OS X is in principle very similar to Python on
+any other Unix platform, but there are a number of additional features such as
+the IDE and the Package Manager that are worth pointing out.
+
+Python on Mac OS 9 or earlier can be quite different from Python on Unix or
+Windows, but is beyond the scope of this manual, as that platform is no longer
+supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
+installers for the latest 2.3 release for Mac OS 9 and related documentation.
+
+
+.. _getting-osx:
+
+Getting and Installing MacPython
+================================
+
+Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are
+encouraged to install the most recent version of Python from the Python website
+(http://www.python.org). A "universal binary" build of Python 2.5, which runs
+natively on the Mac's new Intel and legacy PPC CPU's, is available there.
+
+What you get after installing is a number of things:
+
+* A :file:`MacPython 2.5` folder in your :file:`Applications` folder. In here
+  you find IDLE, the development environment that is a standard part of official
+  Python distributions; PythonLauncher, which handles double-clicking Python
+  scripts from the Finder; and the "Build Applet" tool, which allows you to
+  package Python scripts as standalone applications on your system.
+
+* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
+  Python executable and libraries. The installer adds this location to your shell
+  path. To uninstall MacPython, you can simply remove these three things. A
+  symlink to the Python executable is placed in /usr/local/bin/.
+
+The Apple-provided build of Python is installed in
+:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
+respectively. You should never modify or delete these, as they are
+Apple-controlled and are used by Apple- or third-party software.
+
+IDLE includes a help menu that allows you to access Python documentation. If you
+are completely new to Python you should start reading the tutorial introduction
+in that document.
+
+If you are familiar with Python on other Unix platforms you should read the
+section on running Python scripts from the Unix shell.
+
+
+How to run a Python script
+--------------------------
+
+Your best way to get started with Python on Mac OS X is through the IDLE
+integrated development environment, see section :ref:`ide` and use the Help menu
+when the IDE is running.
+
+If you want to run Python scripts from the Terminal window command line or from
+the Finder you first need an editor to create your script. Mac OS X comes with a
+number of standard Unix command line editors, :program:`vim` and
+:program:`emacs` among them. If you want a more Mac-like editor,
+:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see
+http://www.barebones.com/products/bbedit/index.shtml) are good choices, as is
+:program:`TextMate` (see http://macromates.com/). Other editors include
+:program:`Gvim` (http://macvim.org) and :program:`Aquamacs`
+(http://aquamacs.org).
+
+To run your script from the Terminal window you must make sure that
+:file:`/usr/local/bin` is in your shell search path.
+
+To run your script from the Finder you have two options:
+
+* Drag it to :program:`PythonLauncher`
+
+* Select :program:`PythonLauncher` as the default application to open your
+  script (or any .py script) through the finder Info window and double-click it.
+  :program:`PythonLauncher` has various preferences to control how your script is
+  launched. Option-dragging allows you to change these for one invocation, or use
+  its Preferences menu to change things globally.
+
+
+.. _osx-gui-scripts:
+
+Running scripts with a GUI
+--------------------------
+
+With older versions of Python, there is one Mac OS X quirk that you need to be
+aware of: programs that talk to the Aqua window manager (in other words,
+anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
+instead of :program:`python` to start such scripts.
+
+With Python 2.5, you can use either :program:`python` or :program:`pythonw`.
+
+
+Configuration
+-------------
+
+Python on OS X honors all standard Unix environment variables such as
+:envvar:`PYTHONPATH`, but setting these variables for programs started from the
+Finder is non-standard as the Finder does not read your :file:`.profile` or
+:file:`.cshrc` at startup. You need to create a file :file:`~
+/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details.
+
+For more information on installation Python packages in MacPython, see section
+:ref:`mac-package-manager`.
+
+
+.. _ide:
+
+The IDE
+=======
+
+MacPython ships with the standard IDLE development environment. A good
+introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/
+dyoo/python/idle_intro/index.html.
+
+
+.. _mac-package-manager:
+
+Installing Additional Python Packages
+=====================================
+
+There are several methods to install additional Python packages:
+
+* http://pythonmac.org/packages/ contains selected compiled packages for Python
+  2.5, 2.4, and 2.3.
+
+* Packages can be installed via the standard Python distutils mode (``python
+  setup.py install``).
+
+* Many packages can also be installed via the :program:`setuptools` extension.
+
+
+GUI Programming on the Mac
+==========================
+
+There are several options for building GUI applications on the Mac with Python.
+
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
+the foundation of most modern Mac development. Information on PyObjC is
+available from http://pyobjc.sourceforge.net.
+
+The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform
+Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS
+X by Apple, and the latest version can be downloaded and installed from
+http://www.activestate.com; it can also be built from source.
+
+*wxPython* is another popular cross-platform GUI toolkit that runs natively on
+Mac OS X. Packages and documentation are available from http://www.wxpython.org.
+
+*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac
+OS X. More information can be found at
+http://www.riverbankcomputing.co.uk/pyqt/.
+
+
+Distributing Python Applications on the Mac
+===========================================
+
+The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for
+packaging small Python scripts on your own machine to run as a standard Mac
+application. This tool, however, is not robust enough to distribute Python
+applications to other users.
+
+The standard tool for deploying standalone Python applications on the Mac is
+:program:`py2app`. More information on installing and using py2app can be found
+at http://undefined.org/python/#py2app.
+
+
+Application Scripting
+=====================
+
+Python can also be used to script other Mac applications via Apple's Open
+Scripting Architecture (OSA); see http://appscript.sourceforge.net. Appscript is
+a high-level, user-friendly Apple event bridge that allows you to control
+scriptable Mac OS X applications using ordinary Python scripts. Appscript makes
+Python a serious alternative to Apple's own *AppleScript* language for
+automating your Mac. A related package, *PyOSA*, is an OSA language component
+for the Python scripting language, allowing Python code to be executed by any
+OSA-enabled application (Script Editor, Mail, iTunes, etc.). PyOSA makes Python
+a full peer to AppleScript.
+
+
+Other Resources
+===============
+
+The MacPython mailing list is an excellent support resource for Python users and
+developers on the Mac:
+
+http://www.python.org/community/sigs/current/pythonmac-sig/
+
+Another useful resource is the MacPython wiki:
+
+http://wiki.python.org/moin/MacPython
+

Added: doctools/trunk/Doc-3k/library/aepack.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/aepack.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,92 @@
+
+:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
+====================================================================================
+
+.. module:: aepack
+   :platform: Mac
+   :synopsis: Conversion between Python variables and AppleEvent data containers.
+.. sectionauthor:: Vincent Marchetti <vincem at en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aepack` module defines functions for converting (packing) Python
+variables to AppleEvent descriptors and back (unpacking). Within Python the
+AppleEvent descriptor is handled by Python objects of built-in type
+:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
+
+The :mod:`aepack` module defines the following functions:
+
+
+.. function:: pack(x[, forcetype])
+
+   Returns an :class:`AEDesc` object  containing a conversion of Python value x. If
+   *forcetype* is provided it specifies the descriptor type of the result.
+   Otherwise, a default mapping of Python types to Apple Event descriptor types is
+   used, as follows:
+
+   +-----------------+-----------------------------------+
+   | Python type     | descriptor type                   |
+   +=================+===================================+
+   | :class:`FSSpec` | typeFSS                           |
+   +-----------------+-----------------------------------+
+   | :class:`FSRef`  | typeFSRef                         |
+   +-----------------+-----------------------------------+
+   | :class:`Alias`  | typeAlias                         |
+   +-----------------+-----------------------------------+
+   | integer         | typeLong (32 bit integer)         |
+   +-----------------+-----------------------------------+
+   | float           | typeFloat (64 bit floating point) |
+   +-----------------+-----------------------------------+
+   | string          | typeText                          |
+   +-----------------+-----------------------------------+
+   | unicode         | typeUnicodeText                   |
+   +-----------------+-----------------------------------+
+   | list            | typeAEList                        |
+   +-----------------+-----------------------------------+
+   | dictionary      | typeAERecord                      |
+   +-----------------+-----------------------------------+
+   | instance        | *see below*                       |
+   +-----------------+-----------------------------------+
+
+   If *x* is a Python instance then this function attempts to call an
+   :meth:`__aepack__` method.  This method should return an :class:`AEDesc` object.
+
+   If the conversion *x* is not defined above, this function returns the Python
+   string representation of a value (the repr() function) encoded as a text
+   descriptor.
+
+
+.. function:: unpack(x[, formodulename])
+
+   *x* must be an object of type :class:`AEDesc`. This function returns a Python
+   object representation of the data in the Apple Event descriptor *x*. Simple
+   AppleEvent data types (integer, text, float) are returned as their obvious
+   Python counterparts. Apple Event lists are returned as Python lists, and the
+   list elements are recursively unpacked.  Object references (ex. ``line 3 of
+   document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
+   unless ``formodulename`` is specified.  AppleEvent descriptors with descriptor
+   type typeFSS are returned as :class:`FSSpec` objects.  AppleEvent record
+   descriptors are returned as Python dictionaries, with 4-character string keys
+   and elements recursively unpacked.
+
+   The optional ``formodulename`` argument is used by the stub packages generated
+   by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
+   are looked up in the correct module. This ensures that if, say, the Finder
+   returns an object specifier for a window you get an instance of
+   ``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
+   all the properties and elements a window has in the Finder, while the latter
+   knows no such things.
+
+
+.. seealso::
+
+   Module :mod:`Carbon.AE`
+      Built-in access to Apple Event Manager routines.
+
+   Module :mod:`aetypes`
+      Python definitions of codes for Apple Event descriptor types.
+
+   ` Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_
+      Information about inter-process communications on the Macintosh.
+

Added: doctools/trunk/Doc-3k/library/aetools.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/aetools.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,86 @@
+
+:mod:`aetools` --- OSA client support
+=====================================
+
+.. module:: aetools
+   :platform: Mac
+   :synopsis: Basic support for sending Apple Events
+.. sectionauthor:: Jack Jansen <Jack.Jansen at cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetools` module contains the basic functionality on which Python
+AppleScript client support is built. It also imports and re-exports the core
+functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
+generated by :mod:`gensuitemodule` import the relevant portions of
+:mod:`aetools`, so usually you do not need to import it yourself. The exception
+to this is when you cannot use a generated suite package and need lower-level
+access to scripting.
+
+The :mod:`aetools` module itself uses the AppleEvent support provided by the
+:mod:`Carbon.AE` module. This has one drawback: you need access to the window
+manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
+lifted in future releases.
+
+The :mod:`aetools` module defines the following functions:
+
+
+.. function:: packevent(ae, parameters, attributes)
+
+   Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
+   ``parameters`` and ``attributes`` are  dictionaries mapping 4-character OSA
+   parameter keys to Python objects. The objects are packed using
+   ``aepack.pack()``.
+
+
+.. function:: unpackevent(ae[, formodulename])
+
+   Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
+   returns the parameter dictionary and the attribute dictionary. The
+   ``formodulename`` argument is used by generated stub packages to control where
+   AppleScript classes are looked up.
+
+
+.. function:: keysubst(arguments, keydict)
+
+   Converts a Python keyword argument dictionary ``arguments`` to the format
+   required by ``packevent`` by replacing the keys, which are Python identifiers,
+   by the four-character OSA keys according to the mapping specified in
+   ``keydict``. Used by the generated suite packages.
+
+
+.. function:: enumsubst(arguments, key, edict)
+
+   If the ``arguments`` dictionary contains an entry for ``key`` convert the value
+   for that entry according to dictionary ``edict``. This converts human-readable
+   Python enumeration names to the OSA 4-character codes. Used by the generated
+   suite packages.
+
+The :mod:`aetools` module defines the following class:
+
+
+.. class:: TalkTo([signature=None, start=0, timeout=0])
+
+   Base class for the proxy used to talk to an application. ``signature`` overrides
+   the class attribute ``_signature`` (which is usually set by subclasses) and is
+   the 4-char creator code defining the application to talk to. ``start`` can be
+   set to true to enable running the application on class instantiation.
+   ``timeout`` can be specified to change the default timeout used while waiting
+   for an AppleEvent reply.
+
+
+.. method:: TalkTo._start()
+
+   Test whether the application is running, and attempt to start it if not.
+
+
+.. method:: TalkTo.send(code, subcode[, parameters, attributes])
+
+   Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
+   ``code, subcode`` (which are the usual 4-character strings), pack the
+   ``parameters`` and ``attributes`` into it, send it to the target application,
+   wait for the reply, unpack the reply with ``unpackevent`` and return the reply
+   appleevent, the unpacked return values as a dictionary and the return
+   attributes.
+

Added: doctools/trunk/Doc-3k/library/aetypes.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/aetypes.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,150 @@
+
+:mod:`aetypes` --- AppleEvent objects
+=====================================
+
+.. module:: aetypes
+   :platform: Mac
+   :synopsis: Python representation of the Apple Event Object Model.
+.. sectionauthor:: Vincent Marchetti <vincem at en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetypes` defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is contained in descriptors, and these descriptors are typed.
+For many descriptors the Python representation is simply the corresponding
+Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
+etc. For OSA types that have no direct Python counterpart this module declares
+classes. Packing and unpacking instances of these classes is handled
+automatically by :mod:`aepack`.
+
+An object specifier is essentially an address of an object implemented in a
+Apple Event server. An Apple Event specifier is used as the direct object for an
+Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
+module contains the base classes for OSA classes and properties, which are used
+by the packages generated by :mod:`gensuitemodule` to populate the classes and
+properties in a given suite.
+
+For reasons of backward compatibility, and for cases where you need to script an
+application for which you have not generated the stub package this module also
+contains object specifiers for a number of common OSA classes such as
+``Document``, ``Window``, ``Character``, etc.
+
+The :mod:`AEObjects` module defines the following classes to represent Apple
+Event descriptor data:
+
+
+.. class:: Unknown(type, data)
+
+   The representation of OSA descriptor data for which the :mod:`aepack` and
+   :mod:`aetypes` modules have no support, i.e. anything that is not represented by
+   the other classes here and that is not equivalent to a simple Python value.
+
+
+.. class:: Enum(enum)
+
+   An enumeration value with the given 4-character string value.
+
+
+.. class:: InsertionLoc(of, pos)
+
+   Position ``pos`` in object ``of``.
+
+
+.. class:: Boolean(bool)
+
+   A boolean.
+
+
+.. class:: StyledText(style, text)
+
+   Text with style information (font, face, etc) included.
+
+
+.. class:: AEText(script, style, text)
+
+   Text with script system and style information included.
+
+
+.. class:: IntlText(script, language, text)
+
+   Text with script system and language information included.
+
+
+.. class:: IntlWritingCode(script, language)
+
+   Script system and language information.
+
+
+.. class:: QDPoint(v, h)
+
+   A quickdraw point.
+
+
+.. class:: QDRectangle(v0, h0, v1, h1)
+
+   A quickdraw rectangle.
+
+
+.. class:: RGBColor(r, g, b)
+
+   A color.
+
+
+.. class:: Type(type)
+
+   An OSA type value with the given 4-character name.
+
+
+.. class:: Keyword(name)
+
+   An OSA keyword with the given 4-character name.
+
+
+.. class:: Range(start, stop)
+
+   A range.
+
+
+.. class:: Ordinal(abso)
+
+   Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
+   middle.
+
+
+.. class:: Logical(logc, term)
+
+   The logical expression of applying operator ``logc`` to ``term``.
+
+
+.. class:: Comparison(obj1, relo, obj2)
+
+   The comparison ``relo`` of ``obj1`` to ``obj2``.
+
+The following classes are used as base classes by the generated stub packages to
+represent AppleScript classes and properties in Python:
+
+
+.. class:: ComponentItem(which[, fr])
+
+   Abstract baseclass for an OSA class. The subclass should set the class attribute
+   ``want`` to the 4-character OSA class code. Instances of subclasses of this
+   class are equivalent to AppleScript Object Specifiers. Upon instantiation you
+   should pass a selector in ``which``, and optionally a parent object in ``fr``.
+
+
+.. class:: NProperty(fr)
+
+   Abstract baseclass for an OSA property. The subclass should set the class
+   attributes ``want`` and ``which`` to designate which property we are talking
+   about. Instances of subclasses of this class are Object Specifiers.
+
+
+.. class:: ObjectSpecifier(want, form, seld[, fr])
+
+   Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
+   Specifier. See the Apple Open Scripting Architecture documentation for the
+   parameters. Note that this class is not abstract.
+

Added: doctools/trunk/Doc-3k/library/autogil.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/autogil.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,30 @@
+
+:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
+==================================================================
+
+.. module:: autoGIL
+   :platform: Mac
+   :synopsis: Global Interpreter Lock handling in event loops.
+.. moduleauthor:: Just van Rossum <just at letterror.com>
+
+
+The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
+automatically locks and unlocks Python's Global Interpreter Lock when running an
+event loop.
+
+
+.. exception:: AutoGILError
+
+   Raised if the observer callback cannot be installed, for example because the
+   current thread does not have a run loop.
+
+
+.. function:: installAutoGIL()
+
+   Install an observer callback in the event loop (CFRunLoop) for the current
+   thread, that will lock and unlock the Global Interpreter Lock (GIL) at
+   appropriate times, allowing other Python threads to run while the event loop is
+   idle.
+
+   Availability: OSX 10.1 or later.
+

Added: doctools/trunk/Doc-3k/library/carbon.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/carbon.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,288 @@
+
+.. _toolbox:
+
+*********************
+MacOS Toolbox Modules
+*********************
+
+There are a set of modules that provide interfaces to various MacOS toolboxes.
+If applicable the module will define a number of Python objects for the various
+structures declared by the toolbox, and operations will be implemented as
+methods of the object.  Other operations will be implemented as functions in the
+module.  Not all operations possible in C will also be possible in Python
+(callbacks are often a problem), and parameters will occasionally be different
+in Python (input and output buffers, especially).  All methods and functions
+have a :attr:`__doc__` string describing their arguments and return values, and
+for additional description you are referred to `Inside Macintosh
+<http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.
+
+These modules all live in a package called :mod:`Carbon`. Despite that name they
+are not all part of the Carbon framework: CF is really in the CoreFoundation
+framework and Qt is in the QuickTime framework. The normal use pattern is ::
+
+   from Carbon import AE
+
+**Warning!**  These modules are not yet documented.  If you wish to contribute
+documentation of any of these modules, please get in touch with docs at python.org.
+
+
+:mod:`Carbon.AE` --- Apple Events
+=================================
+
+.. module:: Carbon.AE
+   :platform: Mac
+   :synopsis: Interface to the Apple Events toolbox.
+
+
+
+:mod:`Carbon.AH` --- Apple Help
+===============================
+
+.. module:: Carbon.AH
+   :platform: Mac
+   :synopsis: Interface to the Apple Help manager.
+
+
+
+:mod:`Carbon.App` --- Appearance Manager
+========================================
+
+.. module:: Carbon.App
+   :platform: Mac
+   :synopsis: Interface to the Appearance Manager.
+
+
+
+:mod:`Carbon.CF` --- Core Foundation
+====================================
+
+.. module:: Carbon.CF
+   :platform: Mac
+   :synopsis: Interface to the Core Foundation.
+
+
+The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
+``CFURL`` objects are supported, some only partially.
+
+
+:mod:`Carbon.CG` --- Core Graphics
+==================================
+
+.. module:: Carbon.CG
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
+================================================
+
+.. module:: Carbon.CarbonEvt
+   :platform: Mac
+   :synopsis: Interface to the Carbon Event Manager.
+
+
+
+:mod:`Carbon.Cm` --- Component Manager
+======================================
+
+.. module:: Carbon.Cm
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.Ctl` --- Control Manager
+=====================================
+
+.. module:: Carbon.Ctl
+   :platform: Mac
+   :synopsis: Interface to the Control Manager.
+
+
+
+:mod:`Carbon.Dlg` --- Dialog Manager
+====================================
+
+.. module:: Carbon.Dlg
+   :platform: Mac
+   :synopsis: Interface to the Dialog Manager.
+
+
+
+:mod:`Carbon.Evt` --- Event Manager
+===================================
+
+.. module:: Carbon.Evt
+   :platform: Mac
+   :synopsis: Interface to the classic Event Manager.
+
+
+
+:mod:`Carbon.Fm` --- Font Manager
+=================================
+
+.. module:: Carbon.Fm
+   :platform: Mac
+   :synopsis: Interface to the Font Manager.
+
+
+
+:mod:`Carbon.Folder` --- Folder Manager
+=======================================
+
+.. module:: Carbon.Folder
+   :platform: Mac
+   :synopsis: Interface to the Folder Manager.
+
+
+
+:mod:`Carbon.Help` --- Help Manager
+===================================
+
+.. module:: Carbon.Help
+   :platform: Mac
+   :synopsis: Interface to the Carbon Help Manager.
+
+
+
+:mod:`Carbon.List` --- List Manager
+===================================
+
+.. module:: Carbon.List
+   :platform: Mac
+   :synopsis: Interface to the List Manager.
+
+
+
+:mod:`Carbon.Menu` --- Menu Manager
+===================================
+
+.. module:: Carbon.Menu
+   :platform: Mac
+   :synopsis: Interface to the Menu Manager.
+
+
+
+:mod:`Carbon.Mlte` --- MultiLingual Text Editor
+===============================================
+
+.. module:: Carbon.Mlte
+   :platform: Mac
+   :synopsis: Interface to the MultiLingual Text Editor.
+
+
+
+:mod:`Carbon.Qd` --- QuickDraw
+==============================
+
+.. module:: Carbon.Qd
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw toolbox.
+
+
+
+:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
+============================================
+
+.. module:: Carbon.Qdoffs
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw Offscreen APIs.
+
+
+
+:mod:`Carbon.Qt` --- QuickTime
+==============================
+
+.. module:: Carbon.Qt
+   :platform: Mac
+   :synopsis: Interface to the QuickTime toolbox.
+
+
+
+:mod:`Carbon.Res` --- Resource Manager and Handles
+==================================================
+
+.. module:: Carbon.Res
+   :platform: Mac
+   :synopsis: Interface to the Resource Manager and Handles.
+
+
+
+:mod:`Carbon.Scrap` --- Scrap Manager
+=====================================
+
+.. module:: Carbon.Scrap
+   :platform: Mac
+   :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
+              clipboard operations.
+
+
+This module is only fully available on MacOS9 and earlier under classic PPC
+MacPython.  Very limited functionality is available under Carbon MacPython.
+
+.. index:: single: Scrap Manager
+
+The Scrap Manager supports the simplest form of cut & paste operations on the
+Macintosh.  It can be use for both inter- and intra-application clipboard
+operations.
+
+The :mod:`Scrap` module provides low-level access to the functions of the Scrap
+Manager.  It contains the following functions:
+
+
+.. function:: InfoScrap()
+
+   Return current information about the scrap.  The information is encoded as a
+   tuple containing the fields ``(size, handle, count, state, path)``.
+
+   +----------+---------------------------------------------+
+   | Field    | Meaning                                     |
+   +==========+=============================================+
+   | *size*   | Size of the scrap in bytes.                 |
+   +----------+---------------------------------------------+
+   | *handle* | Resource object representing the scrap.     |
+   +----------+---------------------------------------------+
+   | *count*  | Serial number of the scrap contents.        |
+   +----------+---------------------------------------------+
+   | *state*  | Integer; positive if in memory, ``0`` if on |
+   |          | disk, negative if uninitialized.            |
+   +----------+---------------------------------------------+
+   | *path*   | Filename of the scrap when stored on disk.  |
+   +----------+---------------------------------------------+
+
+
+.. seealso::
+
+   `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
+      Apple's documentation for the Scrap Manager gives a lot of useful information
+      about using the Scrap Manager in applications.
+
+
+
+:mod:`Carbon.Snd` --- Sound Manager
+===================================
+
+.. module:: Carbon.Snd
+   :platform: Mac
+   :synopsis: Interface to the Sound Manager.
+
+
+
+:mod:`Carbon.TE` --- TextEdit
+=============================
+
+.. module:: Carbon.TE
+   :platform: Mac
+   :synopsis: Interface to TextEdit.
+
+
+
+:mod:`Carbon.Win` --- Window Manager
+====================================
+
+.. module:: Carbon.Win
+   :platform: Mac
+   :synopsis: Interface to the Window Manager.
+
+

Added: doctools/trunk/Doc-3k/library/colorpicker.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/colorpicker.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,23 @@
+
+:mod:`ColorPicker` --- Color selection dialog
+=============================================
+
+.. module:: ColorPicker
+   :platform: Mac
+   :synopsis: Interface to the standard color selection dialog.
+.. moduleauthor:: Just van Rossum <just at letterror.com>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
+
+
+The :mod:`ColorPicker` module provides access to the standard color picker
+dialog.
+
+
+.. function:: GetColor(prompt, rgb)
+
+   Show a standard color selection dialog and allow the user to select a color.
+   The user is given instruction by the *prompt* string, and the default color is
+   set to *rgb*.  *rgb* must be a tuple giving the red, green, and blue components
+   of the color. :func:`GetColor` returns a tuple giving the user's selected color
+   and a flag indicating whether they accepted the selection of cancelled.
+

Added: doctools/trunk/Doc-3k/library/easydialogs.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/easydialogs.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,207 @@
+
+:mod:`EasyDialogs` --- Basic Macintosh dialogs
+==============================================
+
+.. module:: EasyDialogs
+   :platform: Mac
+   :synopsis: Basic Macintosh dialogs.
+
+
+The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
+All routines take an optional resource ID parameter *id* with which one can
+override the :const:`DLOG` resource used for the dialog, provided that the
+dialog items correspond (both type and item number) to those in the default
+:const:`DLOG` resource. See source code for details.
+
+The :mod:`EasyDialogs` module defines the following functions:
+
+
+.. function:: Message(str[, id[, ok]])
+
+   Displays a modal dialog with the message text *str*, which should be at most 255
+   characters long. The button text defaults to "OK", but is set to the string
+   argument *ok* if the latter is supplied. Control is returned when the user
+   clicks the "OK" button.
+
+
+.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. *prompt* is the prompt
+   message, and the optional *default* supplies the initial value for the string
+   (otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
+   changed with the *ok* and *cancel* arguments. All strings can be at most 255
+   bytes long. :func:`AskString` returns the string entered or :const:`None` in
+   case the user cancelled.
+
+
+.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. Like
+   :func:`AskString`, but with the text shown as bullets. The arguments have the
+   same meaning as for :func:`AskString`.
+
+
+.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
+
+   Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
+   and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
+   The value of *default* (or ``0`` if *default* is not supplied) is returned when
+   the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
+   the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
+   supply ``""`` for the corresponding argument.
+
+
+.. function:: ProgressBar([title[, maxval[, label[, id]]]])
+
+   Displays a modeless progress-bar dialog. This is the constructor for the
+   :class:`ProgressBar` class described below. *title* is the text string displayed
+   (default "Working..."), *maxval* is the value at which progress is complete
+   (default ``0``, indicating that an indeterminate amount of work remains to be
+   done), and *label* is the text that is displayed above the progress bar itself.
+
+
+.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
+
+   Displays a dialog which aids the user in constructing a command-line argument
+   list.  Returns the list in ``sys.argv`` format, suitable for passing as an
+   argument to :func:`getopt.getopt`.  *addoldfile*, *addnewfile*, and *addfolder*
+   are boolean arguments.  When nonzero, they enable the user to insert into the
+   command line paths to an existing file, a (possibly) not-yet-existent file, and
+   a folder, respectively.  (Note: Option arguments must appear in the command line
+   before file and folder arguments in order to be recognized by
+   :func:`getopt.getopt`.)  Arguments containing spaces can be specified by
+   enclosing them within single or double quotes.  A :exc:`SystemExit` exception is
+   raised if the user presses the "Cancel" button.
+
+   *optionlist* is a list that determines a popup menu from which the allowed
+   options are selected.  Its items can take one of two forms: *optstr* or
+   ``(optstr, descr)``.  When present, *descr* is a short descriptive string that
+   is displayed in the dialog while this option is selected in the popup menu.  The
+   correspondence between *optstr*\s and command-line arguments is:
+
+   +----------------------+------------------------------------------+
+   | *optstr* format      | Command-line format                      |
+   +======================+==========================================+
+   | ``x``                | :option:`-x` (short option)              |
+   +----------------------+------------------------------------------+
+   | ``x:`` or ``x=``     | :option:`-x` (short option with value)   |
+   +----------------------+------------------------------------------+
+   | ``xyz``              | :option:`--xyz` (long option)            |
+   +----------------------+------------------------------------------+
+   | ``xyz:`` or ``xyz=`` | :option:`--xyz` (long option with value) |
+   +----------------------+------------------------------------------+
+
+   *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
+   where *descr* is as above.  The *cmdstr*s will appear in a popup menu.  When
+   chosen, the text of *cmdstr* will be appended to the command line as is, except
+   that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
+
+   .. versionadded:: 2.0
+
+
+.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user for a file to open, and return the file selected
+   or :const:`None` if the user cancelled. *message* is a text message to display,
+   *typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
+   pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
+   *location* is the ``(x, y)`` position on the screen where the dialog is shown,
+   *actionButtonLabel* is a string to show instead of "Open" in the OK button,
+   *cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
+   button, *wanted* is the type of value wanted as a return: :class:`str`,
+   :class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
+   acceptable.
+
+   .. index:: single: Navigation Services
+
+   For a description of the other arguments please see the Apple Navigation
+   Services documentation and the :mod:`EasyDialogs` source code.
+
+
+.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
+
+   Post a dialog asking the user for a file to save to, and return the file
+   selected or :const:`None` if the user cancelled. *savedFileName* is the default
+   for the file name to save to (the return value). See :func:`AskFileForOpen` for
+   a description of the other arguments.
+
+
+.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user to select a folder, and return the folder selected
+   or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
+   description of the arguments.
+
+
+.. seealso::
+
+   `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_
+      Programmer's reference documentation for the Navigation Services, a part of the
+      Carbon framework.
+
+
+.. _progressbar-objects:
+
+ProgressBar Objects
+-------------------
+
+:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
+Both determinate (thermometer style) and indeterminate (barber-pole style)
+progress bars are supported.  The bar will be determinate if its maximum value
+is greater than zero; otherwise it will be indeterminate.
+
+.. versionchanged:: 2.2
+   Support for indeterminate-style progress bars was added.
+
+The dialog is displayed immediately after creation. If the dialog's "Cancel"
+button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
+is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
+does not occur until the progress bar is next updated, typically via a call to
+:meth:`inc` or :meth:`set`).  Otherwise, the bar remains visible until the
+:class:`ProgressBar` object is discarded.
+
+:class:`ProgressBar` objects possess the following attributes and methods:
+
+
+.. attribute:: ProgressBar.curval
+
+   The current value (of type integer or long integer) of the progress bar.  The
+   normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
+   This attribute should not be altered directly.
+
+
+.. attribute:: ProgressBar.maxval
+
+   The maximum value (of type integer or long integer) of the progress bar; the
+   progress bar (thermometer style) is full when :attr:`curval` equals
+   :attr:`maxval`.  If :attr:`maxval` is ``0``, the bar will be indeterminate
+   (barber-pole).  This attribute should not be altered directly.
+
+
+.. method:: ProgressBar.title([newstr])
+
+   Sets the text in the title bar of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.label([newstr])
+
+   Sets the text in the progress box of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.set(value[, max])
+
+   Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
+   *max* if the latter is provided.  *value* is first coerced between 0 and
+   :attr:`maxval`.  The thermometer bar is updated to reflect the changes,
+   including a change from indeterminate to determinate or vice versa.
+
+
+.. method:: ProgressBar.inc([n])
+
+   Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
+   provided.  (Note that *n* may be negative, in which case the effect is a
+   decrement.)  The progress bar is updated to reflect the change.  If the bar is
+   indeterminate, this causes one "spin" of the barber pole.  The resulting
+   :attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
+   to fall outside this range.
+

Modified: doctools/trunk/Doc-3k/library/filesys.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/filesys.rst	(original)
+++ doctools/trunk/Doc-3k/library/filesys.rst	Wed Aug 15 11:00:54 2007
@@ -24,6 +24,7 @@
    linecache.rst
    shutil.rst
    dircache.rst
+   macpath.rst
 
 
 .. seealso::

Added: doctools/trunk/Doc-3k/library/framework.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/framework.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,335 @@
+
+:mod:`FrameWork` --- Interactive application framework
+======================================================
+
+.. module:: FrameWork
+   :platform: Mac
+   :synopsis: Interactive application framework.
+
+
+The :mod:`FrameWork` module contains classes that together provide a framework
+for an interactive Macintosh application. The programmer builds an application
+by creating subclasses that override various methods of the bases classes,
+thereby implementing the functionality wanted. Overriding functionality can
+often be done on various different levels, i.e. to handle clicks in a single
+dialog window in a non-standard way it is not necessary to override the complete
+event handling.
+
+Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
+available for full Cocoa access from Python, and the documentation describes
+only the most important functionality, and not in the most logical manner at
+that. Examine the source or the examples for more details.  The following are
+some comments posted on the MacPython newsgroup about the strengths and
+limitations of :mod:`FrameWork`:
+
+
+.. epigraph::
+
+   The strong point of :mod:`FrameWork` is that it allows you to break into the
+   control-flow at many different places. :mod:`W`, for instance, uses a different
+   way to enable/disable menus and that plugs right in leaving the rest intact.
+   The weak points of :mod:`FrameWork` are that it has no abstract command
+   interface (but that shouldn't be difficult), that its dialog support is minimal
+   and that its control/toolbar support is non-existent.
+
+The :mod:`FrameWork` module defines the following functions:
+
+
+.. function:: Application()
+
+   An object representing the complete application. See below for a description of
+   the methods. The default :meth:`__init__` routine creates an empty window
+   dictionary and a menu bar with an apple menu.
+
+
+.. function:: MenuBar()
+
+   An object representing the menubar. This object is usually not created by the
+   user.
+
+
+.. function:: Menu(bar, title[, after])
+
+   An object representing a menu. Upon creation you pass the ``MenuBar`` the menu
+   appears in, the *title* string and a position (1-based) *after* where the menu
+   should appear (default: at the end).
+
+
+.. function:: MenuItem(menu, title[, shortcut, callback])
+
+   Create a menu item object. The arguments are the menu to create, the item title
+   string and optionally the keyboard shortcut and a callback routine. The callback
+   is called with the arguments menu-id, item number within menu (1-based), current
+   front window and the event record.
+
+   Instead of a callable object the callback can also be a string. In this case
+   menu selection causes the lookup of a method in the topmost window and the
+   application. The method name is the callback string with ``'domenu_'``
+   prepended.
+
+   Calling the ``MenuBar`` :meth:`fixmenudimstate` method sets the correct dimming
+   for all menu items based on the current front window.
+
+
+.. function:: Separator(menu)
+
+   Add a separator to the end of a menu.
+
+
+.. function:: SubMenu(menu, label)
+
+   Create a submenu named *label* under menu *menu*. The menu object is returned.
+
+
+.. function:: Window(parent)
+
+   Creates a (modeless) window. *Parent* is the application object to which the
+   window belongs. The window is not displayed until later.
+
+
+.. function:: DialogWindow(parent)
+
+   Creates a modeless dialog window.
+
+
+.. function:: windowbounds(width, height)
+
+   Return a ``(left, top, right, bottom)`` tuple suitable for creation of a window
+   of given width and height. The window will be staggered with respect to previous
+   windows, and an attempt is made to keep the whole window on-screen. However, the
+   window will however always be the exact size given, so parts may be offscreen.
+
+
+.. function:: setwatchcursor()
+
+   Set the mouse cursor to a watch.
+
+
+.. function:: setarrowcursor()
+
+   Set the mouse cursor to an arrow.
+
+
+.. _application-objects:
+
+Application Objects
+-------------------
+
+Application objects have the following methods, among others:
+
+
+.. method:: Application.makeusermenus()
+
+   Override this method if you need menus in your application. Append the menus to
+   the attribute :attr:`menubar`.
+
+
+.. method:: Application.getabouttext()
+
+   Override this method to return a text string describing your application.
+   Alternatively, override the :meth:`do_about` method for more elaborate "about"
+   messages.
+
+
+.. method:: Application.mainloop([mask[, wait]])
+
+   This routine is the main event loop, call it to set your application rolling.
+   *Mask* is the mask of events you want to handle, *wait* is the number of ticks
+   you want to leave to other concurrent application (default 0, which is probably
+   not a good idea). While raising *self* to exit the mainloop is still supported
+   it is not recommended: call ``self._quit()`` instead.
+
+   The event loop is split into many small parts, each of which can be overridden.
+   The default methods take care of dispatching events to windows and dialogs,
+   handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.
+
+   In general, all event handlers should return ``1`` if the event is fully handled
+   and ``0`` otherwise (because the front window was not a FrameWork window, for
+   instance). This is needed so that update events and such can be passed on to
+   other windows like the Sioux console window. Calling :func:`MacOS.HandleEvent`
+   is not allowed within *our_dispatch* or its callees, since this may result in an
+   infinite loop if the code is called through the Python inner-loop event handler.
+
+
+.. method:: Application.asyncevents(onoff)
+
+   Call this method with a nonzero parameter to enable asynchronous event handling.
+   This will tell the inner interpreter loop to call the application event handler
+   *async_dispatch* whenever events are available. This will cause FrameWork window
+   updates and the user interface to remain working during long computations, but
+   will slow the interpreter down and may cause surprising results in non-reentrant
+   code (such as FrameWork itself). By default *async_dispatch* will immediately
+   call *our_dispatch* but you may override this to handle only certain events
+   asynchronously. Events you do not handle will be passed to Sioux and such.
+
+   The old on/off value is returned.
+
+
+.. method:: Application._quit()
+
+   Terminate the running :meth:`mainloop` call at the next convenient moment.
+
+
+.. method:: Application.do_char(c, event)
+
+   The user typed character *c*. The complete details of the event can be found in
+   the *event* structure. This method can also be provided in a ``Window`` object,
+   which overrides the application-wide handler if the window is frontmost.
+
+
+.. method:: Application.do_dialogevent(event)
+
+   Called early in the event loop to handle modeless dialog events. The default
+   method simply dispatches the event to the relevant dialog (not through the
+   ``DialogWindow`` object involved). Override if you need special handling of
+   dialog events (keyboard shortcuts, etc).
+
+
+.. method:: Application.idle(event)
+
+   Called by the main event loop when no events are available. The null-event is
+   passed (so you can look at mouse position, etc).
+
+
+.. _window-objects:
+
+Window Objects
+--------------
+
+Window objects have the following methods, among others:
+
+
+.. method:: Window.open()
+
+   Override this method to open a window. Store the MacOS window-id in
+   :attr:`self.wid` and call the :meth:`do_postopen` method to register the window
+   with the parent application.
+
+
+.. method:: Window.close()
+
+   Override this method to do any special processing on window close. Call the
+   :meth:`do_postclose` method to cleanup the parent state.
+
+
+.. method:: Window.do_postresize(width, height, macoswindowid)
+
+   Called after the window is resized. Override if more needs to be done than
+   calling ``InvalRect``.
+
+
+.. method:: Window.do_contentclick(local, modifiers, event)
+
+   The user clicked in the content part of a window. The arguments are the
+   coordinates (window-relative), the key modifiers and the raw event.
+
+
+.. method:: Window.do_update(macoswindowid, event)
+
+   An update event for the window was received. Redraw the window.
+
+
+.. method:: Window.do_activate(activate, event)
+
+   The window was activated (``activate == 1``) or deactivated (``activate == 0``).
+   Handle things like focus highlighting, etc.
+
+
+.. _controlswindow-object:
+
+ControlsWindow Object
+---------------------
+
+ControlsWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: ControlsWindow.do_controlhit(window, control, pcode, event)
+
+   Part *pcode* of control *control* was hit by the user. Tracking and such has
+   already been taken care of.
+
+
+.. _scrolledwindow-object:
+
+ScrolledWindow Object
+---------------------
+
+ScrolledWindow objects are ControlsWindow objects with the following extra
+methods:
+
+
+.. method:: ScrolledWindow.scrollbars([wantx[, wanty]])
+
+   Create (or destroy) horizontal and vertical scrollbars. The arguments specify
+   which you want (default: both). The scrollbars always have minimum ``0`` and
+   maximum ``32767``.
+
+
+.. method:: ScrolledWindow.getscrollbarvalues()
+
+   You must supply this method. It should return a tuple ``(x, y)`` giving the
+   current position of the scrollbars (between ``0`` and ``32767``). You can return
+   ``None`` for either to indicate the whole document is visible in that direction.
+
+
+.. method:: ScrolledWindow.updatescrollbars()
+
+   Call this method when the document has changed. It will call
+   :meth:`getscrollbarvalues` and update the scrollbars.
+
+
+.. method:: ScrolledWindow.scrollbar_callback(which, what, value)
+
+   Supplied by you and called after user interaction. *which* will be ``'x'`` or
+   ``'y'``, *what* will be ``'-'``, ``'--'``, ``'set'``, ``'++'`` or ``'+'``. For
+   ``'set'``, *value* will contain the new scrollbar position.
+
+
+.. method:: ScrolledWindow.scalebarvalues(absmin, absmax, curmin, curmax)
+
+   Auxiliary method to help you calculate values to return from
+   :meth:`getscrollbarvalues`. You pass document minimum and maximum value and
+   topmost (leftmost) and bottommost (rightmost) visible values and it returns the
+   correct number or ``None``.
+
+
+.. method:: ScrolledWindow.do_activate(onoff, event)
+
+   Takes care of dimming/highlighting scrollbars when a window becomes frontmost.
+   If you override this method, call this one at the end of your method.
+
+
+.. method:: ScrolledWindow.do_postresize(width, height, window)
+
+   Moves scrollbars to the correct position. Call this method initially if you
+   override it.
+
+
+.. method:: ScrolledWindow.do_controlhit(window, control, pcode, event)
+
+   Handles scrollbar interaction. If you override it call this method first, a
+   nonzero return value indicates the hit was in the scrollbars and has been
+   handled.
+
+
+.. _dialogwindow-objects:
+
+DialogWindow Objects
+--------------------
+
+DialogWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: DialogWindow.open(resid)
+
+   Create the dialog window, from the DLOG resource with id *resid*. The dialog
+   object is stored in :attr:`self.wid`.
+
+
+.. method:: DialogWindow.do_itemhit(item, event)
+
+   Item number *item* was hit. You are responsible for redrawing toggle buttons,
+   etc.
+

Added: doctools/trunk/Doc-3k/library/gensuitemodule.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/gensuitemodule.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,63 @@
+
+:mod:`gensuitemodule` --- Generate OSA stub packages
+====================================================
+
+.. module:: gensuitemodule
+   :platform: Mac
+   :synopsis: Create a stub package from an OSA dictionary
+.. sectionauthor:: Jack Jansen <Jack.Jansen at cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`gensuitemodule` module creates a Python package implementing stub code
+for the AppleScript suites that are implemented by a specific application,
+according to its AppleScript dictionary.
+
+It is usually invoked by the user through the :program:`PythonIDE`, but it can
+also be run as a script from the command line (pass :option:`--help` for help on
+the options) or imported from Python code. For an example of its use see
+:file:`Mac/scripts/genallsuites.py` in a source distribution, which generates
+the stub packages that are included in the standard library.
+
+It defines the following public functions:
+
+
+.. function:: is_scriptable(application)
+
+   Returns true if ``application``, which should be passed as a pathname, appears
+   to be scriptable. Take the return value with a grain of salt: :program:`Internet
+   Explorer` appears not to be scriptable but definitely is.
+
+
+.. function:: processfile(application[, output, basepkgname,  edit_modnames, creatorsignature, dump, verbose])
+
+   Create a stub package for ``application``, which should be passed as a full
+   pathname. For a :file:`.app` bundle this is the pathname to the bundle, not to
+   the executable inside the bundle; for an unbundled CFM application you pass the
+   filename of the application binary.
+
+   This function asks the application for its OSA terminology resources, decodes
+   these resources and uses the resultant data to create the Python code for the
+   package implementing the client stubs.
+
+   ``output`` is the pathname where the resulting package is stored, if not
+   specified a standard "save file as" dialog is presented to the user.
+   ``basepkgname`` is the base package on which this package will build, and
+   defaults to :mod:`StdSuites`. Only when generating :mod:`StdSuites` itself do
+   you need to specify this. ``edit_modnames`` is a dictionary that can be used to
+   change modulenames that are too ugly after name mangling. ``creator_signature``
+   can be used to override the 4-char creator code, which is normally obtained from
+   the :file:`PkgInfo` file in the package or from the CFM file creator signature.
+   When ``dump`` is given it should refer to a file object, and ``processfile``
+   will stop after decoding the resources and dump the Python representation of the
+   terminology resources to this file. ``verbose`` should also be a file object,
+   and specifying it will cause ``processfile`` to tell you what it is doing.
+
+
+.. function:: processfile_fromresource(application[, output,  basepkgname, edit_modnames, creatorsignature, dump, verbose])
+
+   This function does the same as ``processfile``, except that it uses a different
+   method to get the terminology resources. It opens ``application`` as a resource
+   file and reads all ``"aete"`` and ``"aeut"`` resources from this file.
+

Added: doctools/trunk/Doc-3k/library/ic.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/ic.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,119 @@
+
+:mod:`ic` --- Access to the Mac OS X Internet Config
+====================================================
+
+.. module:: ic
+   :platform: Mac
+   :synopsis: Access to the Mac OS X Internet Config.
+
+
+This module provides access to various internet-related preferences set through
+:program:`System Preferences` or the :program:`Finder`.
+
+.. index:: module: icglue
+
+There is a low-level companion module :mod:`icglue` which provides the basic
+Internet Config access functionality.  This low-level module is not documented,
+but the docstrings of the routines document the parameters and the routine names
+are the same as for the Pascal or C API to Internet Config, so the standard IC
+programmers' documentation can be used if this module is needed.
+
+The :mod:`ic` module defines the :exc:`error` exception and symbolic names for
+all error codes Internet Config can produce; see the source for details.
+
+
+.. exception:: error
+
+   Exception raised on errors in the :mod:`ic` module.
+
+The :mod:`ic` module defines the following class and function:
+
+
+.. class:: IC([signature[, ic]])
+
+   Create an Internet Config object. The signature is a 4-character creator code of
+   the current application (default ``'Pyth'``) which may influence some of ICs
+   settings. The optional *ic* argument is a low-level ``icglue.icinstance``
+   created beforehand, this may be useful if you want to get preferences from a
+   different config file, etc.
+
+
+.. function:: launchurl(url[, hint])
+              parseurl(data[, start[, end[, hint]]])
+              mapfile(file)
+              maptypecreator(type, creator[, filename])
+              settypecreator(file)
+
+   These functions are "shortcuts" to the methods of the same name, described
+   below.
+
+
+IC Objects
+----------
+
+:class:`IC` objects have a mapping interface, hence to obtain the mail address
+you simply get ``ic['MailAddress']``. Assignment also works, and changes the
+option in the configuration file.
+
+The module knows about various datatypes, and converts the internal IC
+representation to a "logical" Python data structure. Running the :mod:`ic`
+module standalone will run a test program that lists all keys and values in your
+IC database, this will have to serve as documentation.
+
+If the module does not know how to represent the data it returns an instance of
+the ``ICOpaqueData`` type, with the raw data in its :attr:`data` attribute.
+Objects of this type are also acceptable values for assignment.
+
+Besides the dictionary interface, :class:`IC` objects have the following
+methods:
+
+
+.. method:: IC.launchurl(url[, hint])
+
+   Parse the given URL, launch the correct application and pass it the URL. The
+   optional *hint* can be a scheme name such as ``'mailto:'``, in which case
+   incomplete URLs are completed with this scheme.  If *hint* is not provided,
+   incomplete URLs are invalid.
+
+
+.. method:: IC.parseurl(data[, start[, end[, hint]]])
+
+   Find an URL somewhere in *data* and return start position, end position and the
+   URL. The optional *start* and *end* can be used to limit the search, so for
+   instance if a user clicks in a long text field you can pass the whole text field
+   and the click-position in *start* and this routine will return the whole URL in
+   which the user clicked.  As above, *hint* is an optional scheme used to complete
+   incomplete URLs.
+
+
+.. method:: IC.mapfile(file)
+
+   Return the mapping entry for the given *file*, which can be passed as either a
+   filename or an :func:`FSSpec` result, and which need not exist.
+
+   The mapping entry is returned as a tuple ``(version, type, creator, postcreator,
+   flags, extension, appname, postappname, mimetype, entryname)``, where *version*
+   is the entry version number, *type* is the 4-character filetype, *creator* is
+   the 4-character creator type, *postcreator* is the 4-character creator code of
+   an optional application to post-process the file after downloading, *flags* are
+   various bits specifying whether to transfer in binary or ascii and such,
+   *extension* is the filename extension for this file type, *appname* is the
+   printable name of the application to which this file belongs, *postappname* is
+   the name of the postprocessing application, *mimetype* is the MIME type of this
+   file and *entryname* is the name of this entry.
+
+
+.. method:: IC.maptypecreator(type, creator[, filename])
+
+   Return the mapping entry for files with given 4-character *type* and *creator*
+   codes. The optional *filename* may be specified to further help finding the
+   correct entry (if the creator code is ``'????'``, for instance).
+
+   The mapping entry is returned in the same format as for *mapfile*.
+
+
+.. method:: IC.settypecreator(file)
+
+   Given an existing *file*, specified either as a filename or as an :func:`FSSpec`
+   result, set its creator and type correctly based on its extension.  The finder
+   is told about the change, so the finder icon will be updated quickly.

Modified: doctools/trunk/Doc-3k/library/index.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/index.rst	(original)
+++ doctools/trunk/Doc-3k/library/index.rst	Wed Aug 15 11:00:54 2007
@@ -76,4 +76,6 @@
    misc.rst
    windows.rst
    unix.rst
+   mac.rst
+   macosa.rst
    undoc.rst

Added: doctools/trunk/Doc-3k/library/mac.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/mac.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,19 @@
+
+*************************
+MacOS X specific services
+*************************
+
+This chapter describes modules that are only available on the Mac OS X platform.
+
+See also the chapters :ref:`mac-scripting` and :ref:`undoc-mac-modules`.
+
+.. toctree::
+
+   ic.rst
+   macos.rst
+   macostools.rst
+   easydialogs.rst
+   framework.rst
+   autogil.rst
+   carbon.rst
+   colorpicker.rst
\ No newline at end of file

Added: doctools/trunk/Doc-3k/library/macos.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/macos.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,95 @@
+
+:mod:`MacOS` --- Access to Mac OS interpreter features
+======================================================
+
+.. module:: MacOS
+   :platform: Mac
+   :synopsis: Access to Mac OS-specific interpreter features.
+
+
+This module provides access to MacOS specific functionality in the Python
+interpreter, such as how the interpreter eventloop functions and the like. Use
+with care.
+
+Note the capitalization of the module name; this is a historical artifact.
+
+
+.. data:: runtimemodel
+
+   Always ``'macho'``, from Python 2.4 on. In earlier versions of Python the value
+   could also be ``'ppc'`` for the classic Mac OS 8 runtime model or ``'carbon'``
+   for the Mac OS 9 runtime model.
+
+
+.. data:: linkmodel
+
+   The way the interpreter has been linked. As extension modules may be
+   incompatible between linking models, packages could use this information to give
+   more decent error messages. The value is one of ``'static'`` for a statically
+   linked Python, ``'framework'`` for Python in a Mac OS X framework, ``'shared'``
+   for Python in a standard Unix shared library. Older Pythons could also have the
+   value ``'cfm'`` for Mac OS 9-compatible Python.
+
+
+.. exception:: Error
+
+   .. index:: module: macerrors
+
+   This exception is raised on MacOS generated errors, either from functions in
+   this module or from other mac-specific modules like the toolbox interfaces. The
+   arguments are the integer error code (the :cdata:`OSErr` value) and a textual
+   description of the error code. Symbolic names for all known error codes are
+   defined in the standard module :mod:`macerrors`.
+
+
+.. function:: GetErrorString(errno)
+
+   Return the textual description of MacOS error code *errno*.
+
+
+.. function:: DebugStr(message [, object])
+
+   On Mac OS X the string is simply printed to stderr (on older Mac OS systems more
+   elaborate functionality was available), but it provides a convenient location to
+   attach a breakpoint in a low-level debugger like :program:`gdb`.
+
+
+.. function:: SysBeep()
+
+   Ring the bell.
+
+
+.. function:: GetTicks()
+
+   Get the number of clock ticks (1/60th of a second) since system boot.
+
+
+.. function:: GetCreatorAndType(file)
+
+   Return the file creator and file type as two four-character strings. The *file*
+   parameter can be a pathname or an ``FSSpec`` or  ``FSRef`` object.
+
+
+.. function:: SetCreatorAndType(file, creator, type)
+
+   Set the file creator and file type. The *file* parameter can be a pathname or an
+   ``FSSpec`` or  ``FSRef`` object. *creator* and *type* must be four character
+   strings.
+
+
+.. function:: openrf(name [, mode])
+
+   Open the resource fork of a file. Arguments are the same as for the built-in
+   function :func:`open`. The object returned has file-like semantics, but it is
+   not a Python file object, so there may be subtle differences.
+
+
+.. function:: WMAvailable()
+
+   Checks whether the current process has access to the window manager. The method
+   will return ``False`` if the window manager is not available, for instance when
+   running on Mac OS X Server or when logged in via ssh, or when the current
+   interpreter is not running from a fullblown application bundle. A script runs
+   from an application bundle either when it has been started with
+   :program:`pythonw` instead of :program:`python` or when running  as an applet.
+

Added: doctools/trunk/Doc-3k/library/macosa.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/macosa.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,92 @@
+
+.. _mac-scripting:
+
+*********************
+MacPython OSA Modules
+*********************
+
+This chapter describes the current implementation of the Open Scripting
+Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
+you to control scriptable applications from your Python program, and with a
+fairly pythonic interface. Development on this set of modules has stopped, and a
+replacement is expected for Python 2.5.
+
+For a description of the various components of AppleScript and OSA, and to get
+an understanding of the architecture and terminology, you should read Apple's
+documentation. The "Applescript Language Guide" explains the conceptual model
+and the terminology, and documents the standard suite. The "Open Scripting
+Architecture" document explains how to use OSA from an application programmers
+point of view. In the Apple Help Viewer these books are located in the Developer
+Documentation, Core Technologies section.
+
+As an example of scripting an application, the following piece of AppleScript
+will get the name of the frontmost :program:`Finder` window and print it::
+
+   tell application "Finder"
+       get name of window 1
+   end tell
+
+In Python, the following code fragment will do the same::
+
+   import Finder
+
+   f = Finder.Finder()
+   print f.get(f.window(1).name)
+
+As distributed the Python library includes packages that implement the standard
+suites, plus packages that interface to a small number of common applications.
+
+To send AppleEvents to an application you must first create the Python package
+interfacing to the terminology of the application (what :program:`Script Editor`
+calls the "Dictionary"). This can be done from within the :program:`PythonIDE`
+or by running the :file:`gensuitemodule.py` module as a standalone program from
+the command line.
+
+The generated output is a package with a number of modules, one for every suite
+used in the program plus an :mod:`__init__` module to glue it all together. The
+Python inheritance graph follows the AppleScript inheritance graph, so if a
+program's dictionary specifies that it includes support for the Standard Suite,
+but extends one or two verbs with extra arguments then the output suite will
+contain a module :mod:`Standard_Suite` that imports and re-exports everything
+from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra
+functionality. The output of :mod:`gensuitemodule` is pretty readable, and
+contains the documentation that was in the original AppleScript dictionary in
+Python docstrings, so reading it is a good source of documentation.
+
+The output package implements a main class with the same name as the package
+which contains all the AppleScript verbs as methods, with the direct object as
+the first argument and all optional parameters as keyword arguments. AppleScript
+classes are also implemented as Python classes, as are comparisons and all the
+other thingies.
+
+The main Python class implementing the verbs also allows access to the
+properties and elements declared in the AppleScript class "application". In the
+current release that is as far as the object orientation goes, so in the example
+above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic
+``f.window(1).name.get()``.
+
+If an AppleScript identifier is not a Python identifier the name is mangled
+according to a small number of rules:
+
+* spaces are replaced with underscores
+
+* other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is
+  the hexadecimal character value
+
+* any Python reserved word gets an underscore appended
+
+Python also has support for creating scriptable applications in Python, but The
+following modules are relevant to MacPython AppleScript support:
+
+.. toctree::
+
+   gensuitemodule.rst
+   aetools.rst
+   aepack.rst
+   aetypes.rst
+   miniaeframe.rst
+
+
+In addition, support modules have been pre-generated for :mod:`Finder`,
+:mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,
+:mod:`SystemEvents` and :mod:`StdSuites`.

Added: doctools/trunk/Doc-3k/library/macostools.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/macostools.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,115 @@
+
+:mod:`macostools` --- Convenience routines for file manipulation
+================================================================
+
+.. module:: macostools
+   :platform: Mac
+   :synopsis: Convenience routines for file manipulation.
+
+
+This module contains some convenience routines for file-manipulation on the
+Macintosh. All file parameters can be specified as pathnames, :class:`FSRef` or
+:class:`FSSpec` objects.  This module expects a filesystem which supports forked
+files, so it should not be used on UFS partitions.
+
+The :mod:`macostools` module defines the following functions:
+
+
+.. function:: copy(src, dst[, createpath[, copytimes]])
+
+   Copy file *src* to *dst*.  If *createpath* is non-zero the folders leading to
+   *dst* are created if necessary. The method copies data and resource fork and
+   some finder information (creator, type, flags) and optionally the creation,
+   modification and backup times (default is to copy them). Custom icons, comments
+   and icon position are not copied.
+
+
+.. function:: copytree(src, dst)
+
+   Recursively copy a file tree from *src* to *dst*, creating folders as needed.
+   *src* and *dst* should be specified as pathnames.
+
+
+.. function:: mkalias(src, dst)
+
+   Create a finder alias *dst* pointing to *src*.
+
+
+.. function:: touched(dst)
+
+   Tell the finder that some bits of finder-information such as creator or type for
+   file *dst* has changed. The file can be specified by pathname or fsspec. This
+   call should tell the finder to redraw the files icon.
+
+   .. deprecated:: 2.6
+      The function is a no-op on OS X.
+
+
+.. data:: BUFSIZ
+
+   The buffer size for ``copy``, default 1 megabyte.
+
+Note that the process of creating finder aliases is not specified in the Apple
+documentation. Hence, aliases created with :func:`mkalias` could conceivably
+have incompatible behaviour in some cases.
+
+
+:mod:`findertools` --- The :program:`finder`'s Apple Events interface
+=====================================================================
+
+.. module:: findertools
+   :platform: Mac
+   :synopsis: Wrappers around the finder's Apple Events interface.
+
+
+.. index:: single: AppleEvents
+
+This module contains routines that give Python programs access to some
+functionality provided by the finder. They are implemented as wrappers around
+the AppleEvent interface to the finder.
+
+All file and folder parameters can be specified either as full pathnames, or as
+:class:`FSRef` or :class:`FSSpec` objects.
+
+The :mod:`findertools` module defines the following functions:
+
+
+.. function:: launch(file)
+
+   Tell the finder to launch *file*. What launching means depends on the file:
+   applications are started, folders are opened and documents are opened in the
+   correct application.
+
+
+.. function:: Print(file)
+
+   Tell the finder to print a file. The behaviour is identical to selecting the
+   file and using the print command in the finder's file menu.
+
+
+.. function:: copy(file, destdir)
+
+   Tell the finder to copy a file or folder *file* to folder *destdir*. The
+   function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: move(file, destdir)
+
+   Tell the finder to move a file or folder *file* to folder *destdir*. The
+   function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: sleep()
+
+   Tell the finder to put the Macintosh to sleep, if your machine supports it.
+
+
+.. function:: restart()
+
+   Tell the finder to perform an orderly restart of the machine.
+
+
+.. function:: shutdown()
+
+   Tell the finder to perform an orderly shutdown of the machine.
+

Added: doctools/trunk/Doc-3k/library/macpath.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/macpath.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,17 @@
+
+:mod:`macpath` --- MacOS 9 path manipulation functions
+======================================================
+
+.. module:: macpath
+   :synopsis: MacOS 9 path manipulation functions.
+
+
+This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path`
+module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X
+(or any other platform).
+
+The following functions are available in this module: :func:`normcase`,
+:func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`,
+:func:`isfile`, :func:`walk`, :func:`exists`. For other functions available in
+:mod:`os.path` dummy counterparts are available.
+

Added: doctools/trunk/Doc-3k/library/miniaeframe.rst
==============================================================================
--- (empty file)
+++ doctools/trunk/Doc-3k/library/miniaeframe.rst	Wed Aug 15 11:00:54 2007
@@ -0,0 +1,68 @@
+
+:mod:`MiniAEFrame` --- Open Scripting Architecture server support
+=================================================================
+
+.. module:: MiniAEFrame
+   :platform: Mac
+   :synopsis: Support to act as an Open Scripting Architecture (OSA) server ("Apple Events").
+
+
+.. index::
+   single: Open Scripting Architecture
+   single: AppleEvents
+   module: FrameWork
+
+The module :mod:`MiniAEFrame` provides a framework for an application that can
+function as an Open Scripting Architecture  (OSA) server, i.e. receive and
+process AppleEvents. It can be used in conjunction with :mod:`FrameWork` or
+standalone. As an example, it is used in :program:`PythonCGISlave`.
+
+The :mod:`MiniAEFrame` module defines the following classes:
+
+
+.. class:: AEServer()
+
+   A class that handles AppleEvent dispatch. Your application should subclass this
+   class together with either :class:`MiniApplication` or
+   :class:`FrameWork.Application`. Your :meth:`__init__` method should call the
+   :meth:`__init__` method for both classes.
+
+
+.. class:: MiniApplication()
+
+   A class that is more or less compatible with :class:`FrameWork.Application` but
+   with less functionality. Its event loop supports the apple menu, command-dot and
+   AppleEvents; other events are passed on to the Python interpreter and/or Sioux.
+   Useful if your application wants to use :class:`AEServer` but does not provide
+   its own windows, etc.
+
+
+.. _aeserver-objects:
+
+AEServer Objects
+----------------
+
+
+.. method:: AEServer.installaehandler(classe, type, callback)
+
+   Installs an AppleEvent handler. *classe* and *type* are the four-character OSA
+   Class and Type designators, ``'****'`` wildcards are allowed. When a matching
+   AppleEvent is received the parameters are decoded and your callback is invoked.
+
+
+.. method:: AEServer.callback(_object, **kwargs)
+
+   Your callback is called with the OSA Direct Object as first positional
+   parameter. The other parameters are passed as keyword arguments, with the
+   4-character designator as name. Three extra keyword parameters are passed:
+   ``_class`` and ``_type`` are the Class and Type designators and ``_attributes``
+   is a dictionary with the AppleEvent attributes.
+
+   The return value of your method is packed with :func:`aetools.packevent` and
+   sent as reply.
+
+Note that there are some serious problems with the current design. AppleEvents
+which have non-identifier 4-character designators for arguments are not
+implementable, and it is not possible to return an error to the originator. This
+will be addressed in a future release.
+

Modified: doctools/trunk/Doc-3k/library/undoc.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/undoc.rst	(original)
+++ doctools/trunk/Doc-3k/library/undoc.rst	Wed Aug 15 11:00:54 2007
@@ -14,15 +14,6 @@
 revised.
 
 
-Frameworks
-==========
-
-Frameworks tend to be harder to document, but are well worth the effort spent.
-
-
-   None at this time.
-
-
 Miscellaneous useful utilities
 ==============================
 
@@ -59,6 +50,115 @@
    --- Interpret Sun audio headers (may become obsolete or a tool/demo).
 
 
+.. _undoc-mac-modules:
+
+Undocumented Mac OS modules
+===========================
+
+
+:mod:`applesingle` --- AppleSingle decoder
+------------------------------------------
+
+.. module:: applesingle
+   :platform: Mac
+   :synopsis: Rudimentary decoder for AppleSingle format files.
+
+
+
+:mod:`buildtools` --- Helper module for BuildApplet and Friends
+---------------------------------------------------------------
+
+.. module:: buildtools
+   :platform: Mac
+   :synopsis: Helper module for BuildApplet, BuildApplication and macfreeze.
+
+
+.. deprecated:: 2.4
+
+
+:mod:`icopen` --- Internet Config replacement for :meth:`open`
+--------------------------------------------------------------
+
+.. module:: icopen
+   :platform: Mac
+   :synopsis: Internet Config replacement for open().
+
+
+Importing :mod:`icopen` will replace the builtin :meth:`open` with a version
+that uses Internet Config to set file type and creator for new files.
+
+
+:mod:`macerrors` --- Mac OS Errors
+----------------------------------
+
+.. module:: macerrors
+   :platform: Mac
+   :synopsis: Constant definitions for many Mac OS error codes.
+
+
+:mod:`macerrors` contains constant definitions for many Mac OS error codes.
+
+
+:mod:`macresource` --- Locate script resources
+----------------------------------------------
+
+.. module:: macresource
+   :platform: Mac
+   :synopsis: Locate script resources.
+
+
+:mod:`macresource` helps scripts finding their resources, such as dialogs and
+menus, without requiring special case code for when the script is run under
+MacPython, as a MacPython applet or under OSX Python.
+
+
+:mod:`Nav` --- NavServices calls
+--------------------------------
+
+.. module:: Nav
+   :platform: Mac
+   :synopsis: Interface to Navigation Services.
+
+
+A low-level interface to Navigation Services.
+
+
+:mod:`PixMapWrapper` --- Wrapper for PixMap objects
+---------------------------------------------------
+
+.. module:: PixMapWrapper
+   :platform: Mac
+   :synopsis: Wrapper for PixMap objects.
+
+
+:mod:`PixMapWrapper` wraps a PixMap object with a Python object that allows
+access to the fields by name. It also has methods to convert to and from
+:mod:`PIL` images.
+
+
+:mod:`videoreader` --- Read QuickTime movies
+--------------------------------------------
+
+.. module:: videoreader
+   :platform: Mac
+   :synopsis: Read QuickTime movies frame by frame for further processing.
+
+
+:mod:`videoreader` reads and decodes QuickTime movies and passes a stream of
+images to your program. It also provides some support for audio tracks.
+
+
+:mod:`W` --- Widgets built on :mod:`FrameWork`
+----------------------------------------------
+
+.. module:: W
+   :platform: Mac
+   :synopsis: Widgets for the Mac, built on top of FrameWork.
+
+
+The :mod:`W` widgets are used extensively in the :program:`IDE`.
+
+
 .. _obsolete-modules:
 
 Obsolete

Modified: doctools/trunk/Makefile
==============================================================================
--- doctools/trunk/Makefile	(original)
+++ doctools/trunk/Makefile	Wed Aug 15 11:00:54 2007
@@ -10,13 +10,17 @@
 	@$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js sphinx
 	@$(PYTHON) utils/check_sources.py converter
 
-clean: clean-pyc
+clean: clean-pyc clean-patchfiles
 
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '*~' -exec rm -f {} +
 
+clean-patchfiles:
+	find . -name '*.orig' -exec rm -f {} +
+	find . -name '*.rej' -exec rm -f {} +
+
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx converter
 

Modified: doctools/trunk/sphinx/templates/index.html
==============================================================================
--- doctools/trunk/sphinx/templates/index.html	(original)
+++ doctools/trunk/sphinx/templates/index.html	Wed Aug 15 11:00:54 2007
@@ -21,8 +21,6 @@
          <span class="linkdescr">describes syntax and language elements</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("library/index.rst") }}">Library Reference</a><br>
          <span class="linkdescr">keep this under your pillow</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("maclib/index.rst") }}">Macintosh Library Modules</a><br>
-         <span class="linkdescr">this too, if you use a Macintosh</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("howto/index.rst") }}">Python HOWTOs</a><br>
          <span class="linkdescr">in-depth documents on specific topics</span></p>
     </td><td width="50%">

Modified: doctools/trunk/sphinx/templates/search.html
==============================================================================
--- doctools/trunk/sphinx/templates/search.html	(original)
+++ doctools/trunk/sphinx/templates/search.html	Wed Aug 15 11:00:54 2007
@@ -25,7 +25,6 @@
     {% for id, name, checked in [
       ('tutorial', 'Python Tutorial', true),
       ('library', 'Library Reference', true),
-      ('maclib', 'Macintosh Library Modules', false),
       ('reference', 'Language Reference', false),
       ('extending', 'Extending and Embedding', false),
       ('c-api', 'Python/C API', false),

Modified: doctools/trunk/sphinx/web/oldurls.py
==============================================================================
--- doctools/trunk/sphinx/web/oldurls.py	(original)
+++ doctools/trunk/sphinx/web/oldurls.py	Wed Aug 15 11:00:54 2007
@@ -60,9 +60,11 @@
             return 'bugs/'
         if url == 'modindex.html' or url.endswith('/modindex.html'):
             return 'modindex/'
-        # library, maclib
+        if url == 'mac/using.html':
+            return 'howto/pythonmac/'
+        # library
         if url[:4] in ('lib/', 'mac/'):
-            p = 'library/' if url[0] == 'l' else 'maclib/'
+            p = 'library/'
             m = _module_re.match(url[4:])
             if m:
                 mn = m.group(1)


More information about the Python-checkins mailing list