diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/aepack.rst | 86 | ||||
| -rw-r--r-- | Doc/library/aetools.rst | 84 | ||||
| -rw-r--r-- | Doc/library/aetypes.rst | 148 | ||||
| -rw-r--r-- | Doc/library/autogil.rst | 30 | ||||
| -rw-r--r-- | Doc/library/binhex.rst | 4 | ||||
| -rw-r--r-- | Doc/library/carbon.rst | 288 | ||||
| -rw-r--r-- | Doc/library/colorpicker.rst | 23 | ||||
| -rw-r--r-- | Doc/library/easydialogs.rst | 202 | ||||
| -rw-r--r-- | Doc/library/framework.rst | 335 | ||||
| -rw-r--r-- | Doc/library/ic.rst | 119 | ||||
| -rw-r--r-- | Doc/library/index.rst | 2 | ||||
| -rw-r--r-- | Doc/library/mac.rst | 23 | ||||
| -rw-r--r-- | Doc/library/macos.rst | 93 | ||||
| -rw-r--r-- | Doc/library/macosa.rst | 92 | ||||
| -rw-r--r-- | Doc/library/macostools.rst | 115 | ||||
| -rw-r--r-- | Doc/library/plistlib.rst | 13 | ||||
| -rw-r--r-- | Doc/library/undoc.rst | 98 |
17 files changed, 1 insertions, 1754 deletions
diff --git a/Doc/library/aepack.rst b/Doc/library/aepack.rst deleted file mode 100644 index d8aef6b..0000000 --- a/Doc/library/aepack.rst +++ /dev/null @@ -1,86 +0,0 @@ - -: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@en.com> -.. moduleauthor:: Jack Jansen - -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. diff --git a/Doc/library/aetools.rst b/Doc/library/aetools.rst deleted file mode 100644 index da427eb..0000000 --- a/Doc/library/aetools.rst +++ /dev/null @@ -1,84 +0,0 @@ - -:mod:`aetools` --- OSA client support -===================================== - -.. module:: aetools - :platform: Mac - :synopsis: Basic support for sending Apple Events -.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl> -.. moduleauthor:: Jack Jansen - -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. - diff --git a/Doc/library/aetypes.rst b/Doc/library/aetypes.rst deleted file mode 100644 index c8c5d80..0000000 --- a/Doc/library/aetypes.rst +++ /dev/null @@ -1,148 +0,0 @@ - -:mod:`aetypes` --- AppleEvent objects -===================================== - -.. module:: aetypes - :platform: Mac - :synopsis: Python representation of the Apple Event Object Model. -.. sectionauthor:: Vincent Marchetti <vincem@en.com> -.. moduleauthor:: Jack Jansen - -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. - diff --git a/Doc/library/autogil.rst b/Doc/library/autogil.rst deleted file mode 100644 index 7625be6..0000000 --- a/Doc/library/autogil.rst +++ /dev/null @@ -1,30 +0,0 @@ - -: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@letterror.com> - - -The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that -automatically locks and unlocks Python's :term:`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. - diff --git a/Doc/library/binhex.rst b/Doc/library/binhex.rst index 3b0485c..9e5a8f3 100644 --- a/Doc/library/binhex.rst +++ b/Doc/library/binhex.rst @@ -7,9 +7,7 @@ This module encodes and decodes files in binhex4 format, a format allowing -representation of Macintosh files in ASCII. On the Macintosh, both forks of a -file and the finder information are encoded (or decoded), on other platforms -only the data fork is handled. +representation of Macintosh files in ASCII. Only the data fork is handled. The :mod:`binhex` module defines the following functions: diff --git a/Doc/library/carbon.rst b/Doc/library/carbon.rst deleted file mode 100644 index 886fa82..0000000 --- a/Doc/library/carbon.rst +++ /dev/null @@ -1,288 +0,0 @@ - -.. _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@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 Core Graphics. - - - -: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. - - diff --git a/Doc/library/colorpicker.rst b/Doc/library/colorpicker.rst deleted file mode 100644 index 4244104..0000000 --- a/Doc/library/colorpicker.rst +++ /dev/null @@ -1,23 +0,0 @@ - -:mod:`ColorPicker` --- Color selection dialog -============================================= - -.. module:: ColorPicker - :platform: Mac - :synopsis: Interface to the standard color selection dialog. -.. moduleauthor:: Just van Rossum <just@letterror.com> -.. sectionauthor:: Fred L. Drake, Jr. <fdrake@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. - diff --git a/Doc/library/easydialogs.rst b/Doc/library/easydialogs.rst deleted file mode 100644 index 5aa5e5b..0000000 --- a/Doc/library/easydialogs.rst +++ /dev/null @@ -1,202 +0,0 @@ - -: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. - - -.. 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:`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. - -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) 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) 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. - diff --git a/Doc/library/framework.rst b/Doc/library/framework.rst deleted file mode 100644 index c665fb7..0000000 --- a/Doc/library/framework.rst +++ /dev/null @@ -1,335 +0,0 @@ - -: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. - diff --git a/Doc/library/ic.rst b/Doc/library/ic.rst deleted file mode 100644 index d5e03bd..0000000 --- a/Doc/library/ic.rst +++ /dev/null @@ -1,119 +0,0 @@ - -: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. diff --git a/Doc/library/index.rst b/Doc/library/index.rst index a433214..3a1d14d 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -73,6 +73,4 @@ the `Python Package Index <http://pypi.python.org/pypi>`_. misc.rst windows.rst unix.rst - mac.rst - macosa.rst undoc.rst diff --git a/Doc/library/mac.rst b/Doc/library/mac.rst deleted file mode 100644 index 791eb81..0000000 --- a/Doc/library/mac.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _mac-specific-services: - -************************* -MacOS X specific services -************************* - -This chapter describes modules that are only available on the Mac OS X platform. - -See the chapters :ref:`mac-scripting` and :ref:`undoc-mac-modules` for more -modules, and the HOWTO :ref:`using-on-mac` for a general introduction to -Mac-specific Python programming. - - -.. toctree:: - - ic.rst - macos.rst - macostools.rst - easydialogs.rst - framework.rst - autogil.rst - carbon.rst - colorpicker.rst diff --git a/Doc/library/macos.rst b/Doc/library/macos.rst deleted file mode 100644 index 0eb7225..0000000 --- a/Doc/library/macos.rst +++ /dev/null @@ -1,93 +0,0 @@ - -: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'``. - - -.. 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. - diff --git a/Doc/library/macosa.rst b/Doc/library/macosa.rst deleted file mode 100644 index 4e0b3aa..0000000 --- a/Doc/library/macosa.rst +++ /dev/null @@ -1,92 +0,0 @@ - -.. _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`. diff --git a/Doc/library/macostools.rst b/Doc/library/macostools.rst deleted file mode 100644 index 275100e..0000000 --- a/Doc/library/macostools.rst +++ /dev/null @@ -1,115 +0,0 @@ - -: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. - diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst index f449d7f..81b10bc 100644 --- a/Doc/library/plistlib.rst +++ b/Doc/library/plistlib.rst @@ -65,19 +65,6 @@ This module defines the following functions: Return *rootObject* as a plist-formatted string. - -.. function:: readPlistFromResource(path[, restype='plst'[, resid=0]]) - - Read a plist from the resource with type *restype* from the resource fork of - *path*. Availability: MacOS X. - - -.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]]) - - Write *rootObject* as a resource with type *restype* to the resource fork of - *path*. Availability: MacOS X. - - The following class is available: .. class:: Data(data) diff --git a/Doc/library/undoc.rst b/Doc/library/undoc.rst index b314530..8cdf442 100644 --- a/Doc/library/undoc.rst +++ b/Doc/library/undoc.rst @@ -37,104 +37,6 @@ Multimedia :mod:`sunaudio` --- 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:`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 |