[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