diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/mac | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.zip cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.bz2 |
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/mac')
-rw-r--r-- | Doc/mac/libaepack.tex | 82 | ||||
-rw-r--r-- | Doc/mac/libaetools.tex | 83 | ||||
-rw-r--r-- | Doc/mac/libaetypes.tex | 135 | ||||
-rw-r--r-- | Doc/mac/libautogil.tex | 26 | ||||
-rw-r--r-- | Doc/mac/libcolorpicker.tex | 23 | ||||
-rw-r--r-- | Doc/mac/libframework.tex | 312 | ||||
-rw-r--r-- | Doc/mac/libgensuitemodule.tex | 64 | ||||
-rw-r--r-- | Doc/mac/libmac.tex | 29 | ||||
-rw-r--r-- | Doc/mac/libmacic.tex | 123 | ||||
-rw-r--r-- | Doc/mac/libmacos.tex | 90 | ||||
-rw-r--r-- | Doc/mac/libmacostools.tex | 106 | ||||
-rw-r--r-- | Doc/mac/libmacui.tex | 266 | ||||
-rw-r--r-- | Doc/mac/libminiae.tex | 65 | ||||
-rw-r--r-- | Doc/mac/libscrap.tex | 42 | ||||
-rw-r--r-- | Doc/mac/mac.tex | 88 | ||||
-rw-r--r-- | Doc/mac/scripting.tex | 101 | ||||
-rw-r--r-- | Doc/mac/toolbox.tex | 173 | ||||
-rw-r--r-- | Doc/mac/undoc.tex | 85 | ||||
-rw-r--r-- | Doc/mac/using.tex | 178 |
19 files changed, 0 insertions, 2071 deletions
diff --git a/Doc/mac/libaepack.tex b/Doc/mac/libaepack.tex deleted file mode 100644 index 26a672e..0000000 --- a/Doc/mac/libaepack.tex +++ /dev/null @@ -1,82 +0,0 @@ -\section{\module{aepack} --- - Conversion between Python variables and AppleEvent data containers} - -\declaremodule{standard}{aepack} - \platform{Mac} -%\moduleauthor{Jack Jansen?}{email} -\modulesynopsis{Conversion between Python variables and AppleEvent - data containers.} -\sectionauthor{Vincent Marchetti}{vincem@en.com} - - -The \module{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 \refmodule{Carbon.AE}. - -The \module{aepack} module defines the following functions: - - -\begin{funcdesc}{pack}{x\optional{, forcetype}} -Returns an \class{AEDesc} object containing a conversion of Python -value x. If \var{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: - -\begin{tableii}{l|l}{textrm}{Python type}{descriptor type} - \lineii{\class{FSSpec}}{typeFSS} - \lineii{\class{FSRef}}{typeFSRef} - \lineii{\class{Alias}}{typeAlias} - \lineii{integer}{typeLong (32 bit integer)} - \lineii{float}{typeFloat (64 bit floating point)} - \lineii{string}{typeText} - \lineii{unicode}{typeUnicodeText} - \lineii{list}{typeAEList} - \lineii{dictionary}{typeAERecord} - \lineii{instance}{\emph{see below}} -\end{tableii} - -If \var{x} is a Python instance then this function attempts to call an -\method{__aepack__()} method. This method should return an -\class{AEDesc} object. - -If the conversion \var{x} is not defined above, this function returns -the Python string representation of a value (the repr() function) -encoded as a text descriptor. -\end{funcdesc} - -\begin{funcdesc}{unpack}{x\optional{, formodulename}} - \var{x} must be an object of type \class{AEDesc}. This function - returns a Python object representation of the data in the Apple - Event descriptor \var{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. \code{line 3 of document 1}) are returned as instances of - \class{aetypes.ObjectSpecifier}, unless \code{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 \code{formodulename} argument is used by the stub packages - generated by \module{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 \code{Finder.Window} and not a generic - \code{aetypes.Window}. The former knows about all the properties - and elements a window has in the Finder, while the latter knows - no such things. -\end{funcdesc} - - -\begin{seealso} - \seemodule{Carbon.AE}{Built-in access to Apple Event Manager routines.} - \seemodule{aetypes}{Python definitions of codes for Apple Event - descriptor types.} - \seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{ - Inside Macintosh: Interapplication - Communication}{Information about inter-process - communications on the Macintosh.} -\end{seealso} diff --git a/Doc/mac/libaetools.tex b/Doc/mac/libaetools.tex deleted file mode 100644 index 463755b..0000000 --- a/Doc/mac/libaetools.tex +++ /dev/null @@ -1,83 +0,0 @@ -\section{\module{aetools} --- - OSA client support} - -\declaremodule{standard}{aetools} - \platform{Mac} -%\moduleauthor{Jack Jansen?}{email} -\modulesynopsis{Basic support for sending Apple Events} -\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl} - - -The \module{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 -\module{aetypes} and \module{aepack} modules. The stub packages -generated by \module{gensuitemodule} import the relevant -portions of \module{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 \module{aetools} module itself uses the AppleEvent support -provided by the \module{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 \module{aetools} module defines the following functions: - -\begin{funcdesc}{packevent}{ae, parameters, attributes} -Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc} -object. \code{parameters} and \code{attributes} are -dictionaries mapping 4-character OSA parameter keys to Python objects. The -objects are packed using \code{aepack.pack()}. -\end{funcdesc} - -\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}} -Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects. -The function returns the parameter dictionary and the attribute dictionary. -The \code{formodulename} argument is used by generated stub packages to -control where AppleScript classes are looked up. -\end{funcdesc} - -\begin{funcdesc}{keysubst}{arguments, keydict} -Converts a Python keyword argument dictionary \code{arguments} to -the format required by \code{packevent} by replacing the keys, -which are Python identifiers, by the four-character OSA keys according -to the mapping specified in \code{keydict}. Used by the generated suite -packages. -\end{funcdesc} - -\begin{funcdesc}{enumsubst}{arguments, key, edict} -If the \code{arguments} dictionary contains an entry for \code{key} -convert the value for that entry according to dictionary \code{edict}. -This converts human-readable Python enumeration names to the OSA 4-character -codes. -Used by the generated suite -packages. -\end{funcdesc} - -The \module{aetools} module defines the following class: - -\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}} - -Base class for the proxy used to talk to an application. \code{signature} -overrides the class attribute \code{_signature} (which is usually set by subclasses) -and is the 4-char creator code defining the application to talk to. -\code{start} can be set to true to enable running the application on -class instantiation. \code{timeout} can be specified to change the -default timeout used while waiting for an AppleEvent reply. -\end{classdesc} - -\begin{methoddesc}{_start}{} -Test whether the application is running, and attempt to start it if not. -\end{methoddesc} - -\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}} -Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with -the OSA designation \code{code, subcode} (which are the usual 4-character -strings), pack the \code{parameters} and \code{attributes} into it, send it -to the target application, wait for the reply, unpack the reply with -\code{unpackevent} and return the reply appleevent, the unpacked return values -as a dictionary and the return attributes. -\end{methoddesc} diff --git a/Doc/mac/libaetypes.tex b/Doc/mac/libaetypes.tex deleted file mode 100644 index f7d8f8b..0000000 --- a/Doc/mac/libaetypes.tex +++ /dev/null @@ -1,135 +0,0 @@ -\section{\module{aetypes} --- - AppleEvent objects} - -\declaremodule{standard}{aetypes} - \platform{Mac} -%\moduleauthor{Jack Jansen?}{email} -\modulesynopsis{Python representation of the Apple Event Object Model.} -\sectionauthor{Vincent Marchetti}{vincem@en.com} - - -The \module{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: \code{typeText} in OSA is a Python string, -\code{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 \module{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 \module{aetypes} module contains the base classes for OSA classes -and properties, which are used by the packages generated by -\module{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 \code{Document}, \code{Window}, \code{Character}, etc. - - - -The \module{AEObjects} module defines the following classes to represent -Apple Event descriptor data: - -\begin{classdesc}{Unknown}{type, data} -The representation of OSA descriptor data for which the \module{aepack} -and \module{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. -\end{classdesc} - -\begin{classdesc}{Enum}{enum} -An enumeration value with the given 4-character string value. -\end{classdesc} - -\begin{classdesc}{InsertionLoc}{of, pos} -Position \code{pos} in object \code{of}. -\end{classdesc} - -\begin{classdesc}{Boolean}{bool} -A boolean. -\end{classdesc} - -\begin{classdesc}{StyledText}{style, text} -Text with style information (font, face, etc) included. -\end{classdesc} - -\begin{classdesc}{AEText}{script, style, text} -Text with script system and style information included. -\end{classdesc} - -\begin{classdesc}{IntlText}{script, language, text} -Text with script system and language information included. -\end{classdesc} - -\begin{classdesc}{IntlWritingCode}{script, language} -Script system and language information. -\end{classdesc} - -\begin{classdesc}{QDPoint}{v, h} -A quickdraw point. -\end{classdesc} - -\begin{classdesc}{QDRectangle}{v0, h0, v1, h1} -A quickdraw rectangle. -\end{classdesc} - -\begin{classdesc}{RGBColor}{r, g, b} -A color. -\end{classdesc} - -\begin{classdesc}{Type}{type} -An OSA type value with the given 4-character name. -\end{classdesc} - -\begin{classdesc}{Keyword}{name} -An OSA keyword with the given 4-character name. -\end{classdesc} - -\begin{classdesc}{Range}{start, stop} -A range. -\end{classdesc} - -\begin{classdesc}{Ordinal}{abso} -Non-numeric absolute positions, such as \code{"firs"}, first, or \code{"midd"}, -middle. -\end{classdesc} - -\begin{classdesc}{Logical}{logc, term} -The logical expression of applying operator \code{logc} to -\code{term}. -\end{classdesc} - -\begin{classdesc}{Comparison}{obj1, relo, obj2} -The comparison \code{relo} of \code{obj1} to \code{obj2}. -\end{classdesc} - -The following classes are used as base classes by the generated stub -packages to represent AppleScript classes and properties in Python: - -\begin{classdesc}{ComponentItem}{which\optional{, fr}} -Abstract baseclass for an OSA class. The subclass should set the class -attribute \code{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 -\code{which}, and optionally a parent object in \code{fr}. -\end{classdesc} - -\begin{classdesc}{NProperty}{fr} -Abstract baseclass for an OSA property. The subclass should set the class -attributes \code{want} and \code{which} to designate which property we -are talking about. Instances of subclasses of this class are Object -Specifiers. -\end{classdesc} - -\begin{classdesc}{ObjectSpecifier}{want, form, seld\optional{, fr}} -Base class of \code{ComponentItem} and \code{NProperty}, a general -OSA Object Specifier. See the Apple Open Scripting Architecture -documentation for the parameters. Note that this class is not abstract. -\end{classdesc} - diff --git a/Doc/mac/libautogil.tex b/Doc/mac/libautogil.tex deleted file mode 100644 index 002e872..0000000 --- a/Doc/mac/libautogil.tex +++ /dev/null @@ -1,26 +0,0 @@ -\section{\module{autoGIL} --- - Global Interpreter Lock handling in event loops} - -\declaremodule{extension}{autoGIL} - \platform{Mac} -\modulesynopsis{Global Interpreter Lock handling in event loops.} -\moduleauthor{Just van Rossum}{just@letterror.com} - - -The \module{autoGIL} module provides a function \function{installAutoGIL} that -automatically locks and unlocks Python's Global Interpreter Lock -when running an event loop. - -\begin{excdesc}{AutoGILError} -Raised if the observer callback cannot be installed, for example because -the current thread does not have a run loop. -\end{excdesc} - -\begin{funcdesc}{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. -\end{funcdesc} diff --git a/Doc/mac/libcolorpicker.tex b/Doc/mac/libcolorpicker.tex deleted file mode 100644 index 596e9c2..0000000 --- a/Doc/mac/libcolorpicker.tex +++ /dev/null @@ -1,23 +0,0 @@ -\section{\module{ColorPicker} --- - Color selection dialog} - -\declaremodule{extension}{ColorPicker} - \platform{Mac} -\modulesynopsis{Interface to the standard color selection dialog.} -\moduleauthor{Just van Rossum}{just@letterror.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{ColorPicker} module provides access to the standard color -picker dialog. - - -\begin{funcdesc}{GetColor}{prompt, rgb} - Show a standard color selection dialog and allow the user to select - a color. The user is given instruction by the \var{prompt} string, - and the default color is set to \var{rgb}. \var{rgb} must be a - tuple giving the red, green, and blue components of the color. - \function{GetColor()} returns a tuple giving the user's selected - color and a flag indicating whether they accepted the selection of - cancelled. -\end{funcdesc} diff --git a/Doc/mac/libframework.tex b/Doc/mac/libframework.tex deleted file mode 100644 index edc76c1..0000000 --- a/Doc/mac/libframework.tex +++ /dev/null @@ -1,312 +0,0 @@ -\section{\module{FrameWork} --- - Interactive application framework} - -\declaremodule{standard}{FrameWork} - \platform{Mac} -\modulesynopsis{Interactive application framework.} - - -The \module{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 \module{FrameWork} has pretty much stopped, now that -\module{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 -\module{FrameWork}: - -\begin{quotation} -The strong point of \module{FrameWork} is that it allows you to break -into the control-flow at many different places. \refmodule{W}, for -instance, uses a different way to enable/disable menus and that plugs -right in leaving the rest intact. The weak points of -\module{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. -\end{quotation} - - -The \module{FrameWork} module defines the following functions: - - -\begin{funcdesc}{Application}{} -An object representing the complete application. See below for a -description of the methods. The default \method{__init__()} routine -creates an empty window dictionary and a menu bar with an apple menu. -\end{funcdesc} - -\begin{funcdesc}{MenuBar}{} -An object representing the menubar. This object is usually not created -by the user. -\end{funcdesc} - -\begin{funcdesc}{Menu}{bar, title\optional{, after}} -An object representing a menu. Upon creation you pass the -\code{MenuBar} the menu appears in, the \var{title} string and a -position (1-based) \var{after} where the menu should appear (default: -at the end). -\end{funcdesc} - -\begin{funcdesc}{MenuItem}{menu, title\optional{, 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 \code{'domenu_'} prepended. - -Calling the \code{MenuBar} \method{fixmenudimstate()} method sets the -correct dimming for all menu items based on the current front window. -\end{funcdesc} - -\begin{funcdesc}{Separator}{menu} -Add a separator to the end of a menu. -\end{funcdesc} - -\begin{funcdesc}{SubMenu}{menu, label} -Create a submenu named \var{label} under menu \var{menu}. The menu -object is returned. -\end{funcdesc} - -\begin{funcdesc}{Window}{parent} -Creates a (modeless) window. \var{Parent} is the application object to -which the window belongs. The window is not displayed until later. -\end{funcdesc} - -\begin{funcdesc}{DialogWindow}{parent} -Creates a modeless dialog window. -\end{funcdesc} - -\begin{funcdesc}{windowbounds}{width, height} -Return a \code{(\var{left}, \var{top}, \var{right}, \var{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. -\end{funcdesc} - -\begin{funcdesc}{setwatchcursor}{} -Set the mouse cursor to a watch. -\end{funcdesc} - -\begin{funcdesc}{setarrowcursor}{} -Set the mouse cursor to an arrow. -\end{funcdesc} - - -\subsection{Application Objects \label{application-objects}} - -Application objects have the following methods, among others: - - -\begin{methoddesc}[Application]{makeusermenus}{} -Override this method if you need menus in your application. Append the -menus to the attribute \member{menubar}. -\end{methoddesc} - -\begin{methoddesc}[Application]{getabouttext}{} -Override this method to return a text string describing your -application. Alternatively, override the \method{do_about()} method -for more elaborate ``about'' messages. -\end{methoddesc} - -\begin{methoddesc}[Application]{mainloop}{\optional{mask\optional{, wait}}} -This routine is the main event loop, call it to set your application -rolling. \var{Mask} is the mask of events you want to handle, -\var{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 \var{self} to exit the mainloop is still -supported it is not recommended: call \code{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 \code{1} if the event is fully -handled and \code{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 \function{MacOS.HandleEvent()} is not allowed within -\var{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. -\end{methoddesc} - -\begin{methoddesc}[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 \var{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 \var{async_dispatch} will immediately -call \var{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. -\end{methoddesc} - -\begin{methoddesc}[Application]{_quit}{} -Terminate the running \method{mainloop()} call at the next convenient -moment. -\end{methoddesc} - -\begin{methoddesc}[Application]{do_char}{c, event} -The user typed character \var{c}. The complete details of the event -can be found in the \var{event} structure. This method can also be -provided in a \code{Window} object, which overrides the -application-wide handler if the window is frontmost. -\end{methoddesc} - -\begin{methoddesc}[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 \code{DialogWindow} object involved). Override if you -need special handling of dialog events (keyboard shortcuts, etc). -\end{methoddesc} - -\begin{methoddesc}[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). -\end{methoddesc} - - -\subsection{Window Objects \label{window-objects}} - -Window objects have the following methods, among others: - -\begin{methoddesc}[Window]{open}{} -Override this method to open a window. Store the MacOS window-id in -\member{self.wid} and call the \method{do_postopen()} method to -register the window with the parent application. -\end{methoddesc} - -\begin{methoddesc}[Window]{close}{} -Override this method to do any special processing on window -close. Call the \method{do_postclose()} method to cleanup the parent -state. -\end{methoddesc} - -\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid} -Called after the window is resized. Override if more needs to be done -than calling \code{InvalRect}. -\end{methoddesc} - -\begin{methoddesc}[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. -\end{methoddesc} - -\begin{methoddesc}[Window]{do_update}{macoswindowid, event} -An update event for the window was received. Redraw the window. -\end{methoddesc} - -\begin{methoddesc}[Window]{do_activate}{activate, event} -The window was activated (\code{\var{activate} == 1}) or deactivated -(\code{\var{activate} == 0}). Handle things like focus highlighting, -etc. -\end{methoddesc} - - -\subsection{ControlsWindow Object \label{controlswindow-object}} - -ControlsWindow objects have the following methods besides those of -\code{Window} objects: - - -\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control, - pcode, event} -Part \var{pcode} of control \var{control} was hit by the -user. Tracking and such has already been taken care of. -\end{methoddesc} - - -\subsection{ScrolledWindow Object \label{scrolledwindow-object}} - -ScrolledWindow objects are ControlsWindow objects with the following -extra methods: - - -\begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{, - wanty}}} -Create (or destroy) horizontal and vertical scrollbars. The arguments -specify which you want (default: both). The scrollbars always have -minimum \code{0} and maximum \code{32767}. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{} -You must supply this method. It should return a tuple \code{(\var{x}, -\var{y})} giving the current position of the scrollbars (between -\code{0} and \code{32767}). You can return \code{None} for either to -indicate the whole document is visible in that direction. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{} -Call this method when the document has changed. It will call -\method{getscrollbarvalues()} and update the scrollbars. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value} -Supplied by you and called after user interaction. \var{which} will -be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'}, -\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For -\code{'set'}, \var{value} will contain the new scrollbar position. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax, - curmin, curmax} -Auxiliary method to help you calculate values to return from -\method{getscrollbarvalues()}. You pass document minimum and maximum value -and topmost (leftmost) and bottommost (rightmost) visible values and -it returns the correct number or \code{None}. -\end{methoddesc} - -\begin{methoddesc}[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. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window} -Moves scrollbars to the correct position. Call this method initially -if you override it. -\end{methoddesc} - -\begin{methoddesc}[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. -\end{methoddesc} - - -\subsection{DialogWindow Objects \label{dialogwindow-objects}} - -DialogWindow objects have the following methods besides those of -\code{Window} objects: - - -\begin{methoddesc}[DialogWindow]{open}{resid} -Create the dialog window, from the DLOG resource with id -\var{resid}. The dialog object is stored in \member{self.wid}. -\end{methoddesc} - -\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event} -Item number \var{item} was hit. You are responsible for redrawing -toggle buttons, etc. -\end{methoddesc} diff --git a/Doc/mac/libgensuitemodule.tex b/Doc/mac/libgensuitemodule.tex deleted file mode 100644 index 57ab587..0000000 --- a/Doc/mac/libgensuitemodule.tex +++ /dev/null @@ -1,64 +0,0 @@ -\section{\module{gensuitemodule} --- - Generate OSA stub packages} - -\declaremodule{standard}{gensuitemodule} - \platform{Mac} -%\moduleauthor{Jack Jansen?}{email} -\modulesynopsis{Create a stub package from an OSA dictionary} -\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl} - -The \module{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 -\longprogramopt{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: - -\begin{funcdesc}{is_scriptable}{application} -Returns true if \code{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. -\end{funcdesc} - -\begin{funcdesc}{processfile}{application\optional{, output, basepkgname, - edit_modnames, creatorsignature, dump, verbose}} -Create a stub package for \code{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. - -\code{output} is the pathname where the resulting package is stored, if -not specified a standard "save file as" dialog is presented to -the user. \code{basepkgname} is the base package on which this package -will build, and defaults to \module{StdSuites}. Only when generating -\module{StdSuites} itself do you need to specify this. -\code{edit_modnames} is a dictionary that can be used to change -modulenames that are too ugly after name mangling. -\code{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 \code{dump} is -given it should refer to a file object, and \code{processfile} will stop -after decoding the resources and dump the Python representation of the -terminology resources to this file. \code{verbose} should also be a file -object, and specifying it will cause \code{processfile} to tell you what -it is doing. -\end{funcdesc} - -\begin{funcdesc}{processfile_fromresource}{application\optional{, output, - basepkgname, edit_modnames, creatorsignature, dump, verbose}} -This function does the same as \code{processfile}, except that it uses a -different method to get the terminology resources. It opens \code{application} -as a resource file and reads all \code{"aete"} and \code{"aeut"} resources -from this file. -\end{funcdesc} - diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex deleted file mode 100644 index 9dece8d..0000000 --- a/Doc/mac/libmac.tex +++ /dev/null @@ -1,29 +0,0 @@ - -\section{\module{macpath} --- - MacOS path manipulation functions} - -\declaremodule{standard}{macpath} -% Could be labeled \platform{Mac}, but the module should work anywhere and -% is distributed with the standard library. -\modulesynopsis{MacOS path manipulation functions.} - - -This module is the Mac OS 9 (and earlier) implementation of the \module{os.path} -module. It can be used to manipulate old-style Macintosh pathnames on Mac OS -X (or any other platform). -Refer to the -\citetitle[../lib/lib.html]{Python Library Reference} for -documentation of \module{os.path}. - -The following functions are available in this module: -\function{normcase()}, -\function{normpath()}, -\function{isabs()}, -\function{join()}, -\function{split()}, -\function{isdir()}, -\function{isfile()}, -\function{walk()}, -\function{exists()}. -For other functions available in \module{os.path} dummy counterparts -are available. diff --git a/Doc/mac/libmacic.tex b/Doc/mac/libmacic.tex deleted file mode 100644 index f8006f3..0000000 --- a/Doc/mac/libmacic.tex +++ /dev/null @@ -1,123 +0,0 @@ -\section{\module{ic} --- - Access to Internet Config} - -\declaremodule{builtin}{ic} - \platform{Mac} -\modulesynopsis{Access to Internet Config.} - - -This module provides access to various internet-related preferences -set through \program{System Preferences} or the \program{Finder}. - -There is a low-level companion module -\module{icglue}\refbimodindex{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 \module{ic} module defines the \exception{error} exception and -symbolic names for all error codes Internet Config can produce; see -the source for details. - -\begin{excdesc}{error} -Exception raised on errors in the \module{ic} module. -\end{excdesc} - - -The \module{ic} module defines the following class and function: - -\begin{classdesc}{IC}{\optional{signature\optional{, ic}}} -Create an Internet Config object. The signature is a 4-character creator -code of the current application (default \code{'Pyth'}) which may -influence some of ICs settings. The optional \var{ic} argument is a -low-level \code{icglue.icinstance} created beforehand, this may be -useful if you want to get preferences from a different config file, -etc. -\end{classdesc} - -\begin{funcdesc}{launchurl}{url\optional{, hint}} -\funcline{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}} -\funcline{mapfile}{file} -\funcline{maptypecreator}{type, creator\optional{, filename}} -\funcline{settypecreator}{file} -These functions are ``shortcuts'' to the methods of the same name, -described below. -\end{funcdesc} - - -\subsection{IC Objects} - -\class{IC} objects have a mapping interface, hence to obtain the mail -address you simply get \code{\var{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 -\module{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 \code{ICOpaqueData} type, with the raw data in its -\member{data} attribute. Objects of this type are also acceptable values -for assignment. - -Besides the dictionary interface, \class{IC} objects have the -following methods: - - -\begin{methoddesc}[IC]{launchurl}{url\optional{, hint}} -Parse the given URL, launch the correct application and pass it the -URL. The optional \var{hint} can be a scheme name such as -\code{'mailto:'}, in which case incomplete URLs are completed with this -scheme. If \var{hint} is not provided, incomplete URLs are invalid. -\end{methoddesc} - -\begin{methoddesc}[IC]{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}} -Find an URL somewhere in \var{data} and return start position, end -position and the URL. The optional \var{start} and \var{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 -\var{start} and this routine will return the whole URL in which the -user clicked. As above, \var{hint} is an optional scheme used to -complete incomplete URLs. -\end{methoddesc} - -\begin{methoddesc}[IC]{mapfile}{file} -Return the mapping entry for the given \var{file}, which can be passed -as either a filename or an \function{FSSpec()} result, and which -need not exist. - -The mapping entry is returned as a tuple \code{(\var{version}, -\var{type}, \var{creator}, \var{postcreator}, \var{flags}, -\var{extension}, \var{appname}, \var{postappname}, \var{mimetype}, -\var{entryname})}, where \var{version} is the entry version -number, \var{type} is the 4-character filetype, \var{creator} is the -4-character creator type, \var{postcreator} is the 4-character creator -code of an -optional application to post-process the file after downloading, -\var{flags} are various bits specifying whether to transfer in binary -or ascii and such, \var{extension} is the filename extension for this -file type, \var{appname} is the printable name of the application to -which this file belongs, \var{postappname} is the name of the -postprocessing application, \var{mimetype} is the MIME type of this -file and \var{entryname} is the name of this entry. -\end{methoddesc} - -\begin{methoddesc}[IC]{maptypecreator}{type, creator\optional{, filename}} -Return the mapping entry for files with given 4-character \var{type} and -\var{creator} codes. The optional \var{filename} may be specified to -further help finding the correct entry (if the creator code is -\code{'????'}, for instance). - -The mapping entry is returned in the same format as for \var{mapfile}. -\end{methoddesc} - -\begin{methoddesc}[IC]{settypecreator}{file} -Given an existing \var{file}, specified either as a filename or as an -\function{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. -\end{methoddesc} diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex deleted file mode 100644 index e50b99b..0000000 --- a/Doc/mac/libmacos.tex +++ /dev/null @@ -1,90 +0,0 @@ -\section{\module{MacOS} --- - Access to Mac OS interpreter features} - -\declaremodule{builtin}{MacOS} - \platform{Mac} -\modulesynopsis{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. - -\begin{datadesc}{runtimemodel} -Always \code{'macho'}, from Python 2.4 on. -In earlier versions of Python the value could -also be \code{'ppc'} for the classic Mac OS 8 runtime model or -\code{'carbon'} for the Mac OS 9 runtime model. -\end{datadesc} - -\begin{datadesc}{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 \code{'static'} for a -statically linked Python, \code{'framework'} for Python in a Mac OS X framework, -\code{'shared'} for Python in a standard \UNIX{} shared library. -Older Pythons could also have the value -\code{'cfm'} for Mac OS 9-compatible Python. -\end{datadesc} - -\begin{excdesc}{Error} -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 \refmodule{macerrors}.\refstmodindex{macerrors} -\end{excdesc} - - -\begin{funcdesc}{GetErrorString}{errno} -Return the textual description of MacOS error code \var{errno}. -\end{funcdesc} - -\begin{funcdesc}{DebugStr}{message \optional{, 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}. -\end{funcdesc} - -\begin{funcdesc}{SysBeep}{} -Ring the bell. -\end{funcdesc} - -\begin{funcdesc}{GetTicks}{} -Get the number of clock ticks (1/60th of a second) since system boot. -\end{funcdesc} - -\begin{funcdesc}{GetCreatorAndType}{file} -Return the file creator and file type as two four-character strings. -The \var{file} parameter can be a pathname or an \code{FSSpec} or -\code{FSRef} object. -\end{funcdesc} - -\begin{funcdesc}{SetCreatorAndType}{file, creator, type} -Set the file creator and file type. -The \var{file} parameter can be a pathname or an \code{FSSpec} or -\code{FSRef} object. \var{creator} and \var{type} must be four character -strings. -\end{funcdesc} - -\begin{funcdesc}{openrf}{name \optional{, mode}} -Open the resource fork of a file. Arguments are the same as for the -built-in function \function{open()}. The object returned has file-like -semantics, but it is not a Python file object, so there may be subtle -differences. -\end{funcdesc} - -\begin{funcdesc}{WMAvailable}{} -Checks whether the current process has access to the window manager. -The method will return \code{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. -\end{funcdesc} diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex deleted file mode 100644 index 2754811..0000000 --- a/Doc/mac/libmacostools.tex +++ /dev/null @@ -1,106 +0,0 @@ -\section{\module{macostools} --- - Convenience routines for file manipulation} - -\declaremodule{standard}{macostools} - \platform{Mac} -\modulesynopsis{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 \module{macostools} module defines the following functions: - - -\begin{funcdesc}{copy}{src, dst\optional{, createpath\optional{, copytimes}}} -Copy file \var{src} to \var{dst}. If \var{createpath} is non-zero -the folders leading to \var{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. -\end{funcdesc} - -\begin{funcdesc}{copytree}{src, dst} -Recursively copy a file tree from \var{src} to \var{dst}, creating -folders as needed. \var{src} and \var{dst} should be specified as -pathnames. -\end{funcdesc} - -\begin{funcdesc}{mkalias}{src, dst} -Create a finder alias \var{dst} pointing to \var{src}. -\end{funcdesc} - -\begin{funcdesc}{touched}{dst} -Tell the finder that some bits of finder-information such as creator -or type for file \var{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.} -\end{funcdesc} - -\begin{datadesc}{BUFSIZ} -The buffer size for \code{copy}, default 1 megabyte. -\end{datadesc} - -Note that the process of creating finder aliases is not specified in -the Apple documentation. Hence, aliases created with \function{mkalias()} -could conceivably have incompatible behaviour in some cases. - - -\section{\module{findertools} --- - The \program{finder}'s Apple Events interface} - -\declaremodule{standard}{findertools} - \platform{Mac} -\modulesynopsis{Wrappers around the \program{finder}'s Apple Events interface.} - - -This module contains routines that give Python programs access to some -functionality provided by the finder. They are implemented as wrappers -around the AppleEvent\index{AppleEvents} 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 \module{findertools} module defines the following functions: - - -\begin{funcdesc}{launch}{file} -Tell the finder to launch \var{file}. What launching means depends on the file: -applications are started, folders are opened and documents are opened -in the correct application. -\end{funcdesc} - -\begin{funcdesc}{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. -\end{funcdesc} - -\begin{funcdesc}{copy}{file, destdir} -Tell the finder to copy a file or folder \var{file} to folder -\var{destdir}. The function returns an \class{Alias} object pointing to -the new file. -\end{funcdesc} - -\begin{funcdesc}{move}{file, destdir} -Tell the finder to move a file or folder \var{file} to folder -\var{destdir}. The function returns an \class{Alias} object pointing to -the new file. -\end{funcdesc} - -\begin{funcdesc}{sleep}{} -Tell the finder to put the Macintosh to sleep, if your machine -supports it. -\end{funcdesc} - -\begin{funcdesc}{restart}{} -Tell the finder to perform an orderly restart of the machine. -\end{funcdesc} - -\begin{funcdesc}{shutdown}{} -Tell the finder to perform an orderly shutdown of the machine. -\end{funcdesc} diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex deleted file mode 100644 index db649ab..0000000 --- a/Doc/mac/libmacui.tex +++ /dev/null @@ -1,266 +0,0 @@ -\section{\module{EasyDialogs} --- - Basic Macintosh dialogs} - -\declaremodule{standard}{EasyDialogs} - \platform{Mac} -\modulesynopsis{Basic Macintosh dialogs.} - -The \module{EasyDialogs} module contains some simple dialogs for the -Macintosh. All routines take an optional resource ID parameter \var{id} -with which one can override the \constant{DLOG} resource used for the -dialog, provided that the dialog items correspond (both type and item -number) to those in the default \constant{DLOG} resource. See source -code for details. - -The \module{EasyDialogs} module defines the following functions: - - -\begin{funcdesc}{Message}{str\optional{, id\optional{, ok}}} -Displays a modal dialog with the message text \var{str}, which should be -at most 255 characters long. The button text defaults to ``OK'', but is -set to the string argument \var{ok} if the latter is supplied. Control -is returned when the user clicks the ``OK'' button. -\end{funcdesc} - - -\begin{funcdesc}{AskString}{prompt\optional{, default\optional{, - id\optional{, ok\optional{, cancel}}}}} -Asks the user to input a string value via a modal dialog. \var{prompt} -is the prompt message, and the optional \var{default} supplies the -initial value for the string (otherwise \code{""} is used). The text of -the ``OK'' and ``Cancel'' buttons can be changed with the \var{ok} and -\var{cancel} arguments. All strings can be at most 255 bytes long. -\function{AskString()} returns the string entered or \constant{None} -in case the user cancelled. -\end{funcdesc} - - -\begin{funcdesc}{AskPassword}{prompt\optional{, default\optional{, - id\optional{, ok\optional{, cancel}}}}} -Asks the user to input a string value via a modal dialog. Like -\function{AskString()}, but with the text shown as bullets. The -arguments have the same meaning as for \function{AskString()}. -\end{funcdesc} - - -\begin{funcdesc}{AskYesNoCancel}{question\optional{, default\optional{, - yes\optional{, no\optional{, cancel\optional{, id}}}}}} -Presents a dialog with prompt \var{question} and three buttons labelled -``Yes'', ``No'', and ``Cancel''. Returns \code{1} for ``Yes'', \code{0} -for ``No'' and \code{-1} for ``Cancel''. The value of \var{default} (or -\code{0} if \var{default} is not supplied) is returned when the -\kbd{RETURN} key is pressed. The text of the buttons can be changed with -the \var{yes}, \var{no}, and \var{cancel} arguments; to prevent a button -from appearing, supply \code{""} for the corresponding argument. -\end{funcdesc} - - -\begin{funcdesc}{ProgressBar}{\optional{title\optional{, maxval\optional{, - label\optional{, id}}}}} -Displays a modeless progress-bar dialog. This is the constructor for the -\class{ProgressBar} class described below. \var{title} is the text -string displayed (default ``Working...''), \var{maxval} is the value at -which progress is complete (default \code{0}, indicating that an -indeterminate amount of work remains to be done), and \var{label} is -the text that is displayed above the progress bar itself. -\end{funcdesc} - - -\begin{funcdesc}{GetArgv}{\optional{optionlist\optional{ - commandlist\optional{, addoldfile\optional{, addnewfile\optional{, - addfolder\optional{, id}}}}}}} -Displays a dialog which aids the user in constructing a command-line -argument list. Returns the list in \code{sys.argv} format, suitable for -passing as an argument to \function{getopt.getopt()}. \var{addoldfile}, -\var{addnewfile}, and \var{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 -\function{getopt.getopt()}.) Arguments containing spaces can be -specified by enclosing them within single or double quotes. A -\exception{SystemExit} exception is raised if the user presses the -``Cancel'' button. - -\var{optionlist} is a list that determines a popup menu from which the -allowed options are selected. Its items can take one of two forms: -\var{optstr} or \code{(\var{optstr}, \var{descr})}. When present, -\var{descr} is a short descriptive string that is displayed in the -dialog while this option is selected in the popup menu. The -correspondence between \var{optstr}s and command-line arguments is: - -\begin{tableii}{l|l}{textrm}{\var{optstr} format}{Command-line format} -\lineii{\code{x}} - {\programopt{-x} (short option)} -\lineii{\code{x:} or \code{x=}} - {\programopt{-x} (short option with value)} -\lineii{\code{xyz}} - {\longprogramopt{xyz} (long option)} -\lineii{\code{xyz:} or \code{xyz=}} - {\longprogramopt{xyz} (long option with value)} -\end{tableii} - -\var{commandlist} is a list of items of the form \var{cmdstr} or -\code{(\var{cmdstr}, \var{descr})}, where \var{descr} is as above. The -\var{cmdstr}s will appear in a popup menu. When chosen, the text of -\var{cmdstr} will be appended to the command line as is, except that a -trailing \character{:} or \character{=} (if present) will be trimmed -off. - -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{AskFileForOpen}{ - \optional{message} - \optional{, typeList} - \optional{, defaultLocation} - \optional{, defaultOptionFlags} - \optional{, location} - \optional{, clientName} - \optional{, windowTitle} - \optional{, actionButtonLabel} - \optional{, cancelButtonLabel} - \optional{, preferenceKey} - \optional{, popupExtension} - \optional{, eventProc} - \optional{, previewProc} - \optional{, filterProc} - \optional{, wanted} - } -Post a dialog asking the user for a file to open, and return the file -selected or \constant{None} if the user cancelled. -\var{message} is a text message to display, -\var{typeList} is a list of 4-char filetypes allowable, -\var{defaultLocation} is the pathname, \class{FSSpec} or \class{FSRef} -of the folder to show initially, -\var{location} is the \code{(x, y)} position on the screen where the -dialog is shown, -\var{actionButtonLabel} is a string to show instead of ``Open'' in the -OK button, -\var{cancelButtonLabel} is a string to show instead of ``Cancel'' in the -cancel button, -\var{wanted} is the type of value wanted as a return: \class{str}, -\class{unicode}, \class{FSSpec}, \class{FSRef} and subtypes thereof are -acceptable. - -\index{Navigation Services} -For a description of the other arguments please see the Apple Navigation -Services documentation and the \module{EasyDialogs} source code. -\end{funcdesc} - -\begin{funcdesc}{AskFileForSave}{ - \optional{message} - \optional{, savedFileName} - \optional{, defaultLocation} - \optional{, defaultOptionFlags} - \optional{, location} - \optional{, clientName} - \optional{, windowTitle} - \optional{, actionButtonLabel} - \optional{, cancelButtonLabel} - \optional{, preferenceKey} - \optional{, popupExtension} - \optional{, fileType} - \optional{, fileCreator} - \optional{, eventProc} - \optional{, wanted} - } -Post a dialog asking the user for a file to save to, and return the -file selected or \constant{None} if the user cancelled. -\var{savedFileName} is the default for the file name to save to (the -return value). See \function{AskFileForOpen()} for a description of -the other arguments. -\end{funcdesc} - -\begin{funcdesc}{AskFolder}{ - \optional{message} - \optional{, defaultLocation} - \optional{, defaultOptionFlags} - \optional{, location} - \optional{, clientName} - \optional{, windowTitle} - \optional{, actionButtonLabel} - \optional{, cancelButtonLabel} - \optional{, preferenceKey} - \optional{, popupExtension} - \optional{, eventProc} - \optional{, filterProc} - \optional{, wanted} - } -Post a dialog asking the user to select a folder, and return the -folder selected or \constant{None} if the user cancelled. See -\function{AskFileForOpen()} for a description of the arguments. -\end{funcdesc} - - -\begin{seealso} - \seetitle - [http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/] - {Navigation Services Reference}{Programmer's reference documentation - for the Navigation Services, a part of the Carbon framework.} -\end{seealso} - - -\subsection{ProgressBar Objects \label{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[Support for indeterminate-style progress bars was - added]{2.2} - -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 \exception{KeyboardInterrupt} is -raised (but note that this response does not occur until the progress -bar is next updated, typically via a call to \method{inc()} or -\method{set()}). Otherwise, the bar remains visible until the -\class{ProgressBar} object is discarded. - -\class{ProgressBar} objects possess the following attributes and -methods: - -\begin{memberdesc}[ProgressBar]{curval} -The current value (of type integer or long integer) of the progress -bar. The normal access methods coerce \member{curval} between -\code{0} and \member{maxval}. This attribute should not be altered -directly. -\end{memberdesc} - -\begin{memberdesc}[ProgressBar]{maxval} -The maximum value (of type integer or long integer) of the progress -bar; the progress bar (thermometer style) is full when \member{curval} -equals \member{maxval}. If \member{maxval} is \code{0}, the bar will -be indeterminate (barber-pole). This attribute should not be altered -directly. -\end{memberdesc} - -\begin{methoddesc}[ProgressBar]{title}{\optional{newstr}} -Sets the text in the title bar of the progress dialog to -\var{newstr}. -\end{methoddesc} - -\begin{methoddesc}[ProgressBar]{label}{\optional{newstr}} -Sets the text in the progress box of the progress dialog to -\var{newstr}. -\end{methoddesc} - -\begin{methoddesc}[ProgressBar]{set}{value\optional{, max}} -Sets the progress bar's \member{curval} to \var{value}, and also -\member{maxval} to \var{max} if the latter is provided. \var{value} -is first coerced between 0 and \member{maxval}. The thermometer bar -is updated to reflect the changes, including a change from -indeterminate to determinate or vice versa. -\end{methoddesc} - -\begin{methoddesc}[ProgressBar]{inc}{\optional{n}} -Increments the progress bar's \member{curval} by \var{n}, or by \code{1} -if \var{n} is not provided. (Note that \var{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 \member{curval} is coerced -between 0 and \member{maxval} if incrementing causes it to fall -outside this range. -\end{methoddesc} diff --git a/Doc/mac/libminiae.tex b/Doc/mac/libminiae.tex deleted file mode 100644 index 9d815f0..0000000 --- a/Doc/mac/libminiae.tex +++ /dev/null @@ -1,65 +0,0 @@ -\section{\module{MiniAEFrame} --- - Open Scripting Architecture server support} - -\declaremodule{standard}{MiniAEFrame} - \platform{Mac} -\modulesynopsis{Support to act as an Open Scripting Architecture (OSA) server -(``Apple Events'').} - - -The module \module{MiniAEFrame} provides a framework for an application -that can function as an Open Scripting Architecture -\index{Open Scripting Architecture} -(OSA) server, i.e. receive and process -AppleEvents\index{AppleEvents}. It can be used in conjunction with -\refmodule{FrameWork}\refstmodindex{FrameWork} or standalone. As an -example, it is used in \program{PythonCGISlave}. - - -The \module{MiniAEFrame} module defines the following classes: - - -\begin{classdesc}{AEServer}{} -A class that handles AppleEvent dispatch. Your application should -subclass this class together with either -\class{MiniApplication} or -\class{FrameWork.Application}. Your \method{__init__()} method should -call the \method{__init__()} method for both classes. -\end{classdesc} - -\begin{classdesc}{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. -\end{classdesc} - - -\subsection{AEServer Objects \label{aeserver-objects}} - -\begin{methoddesc}[AEServer]{installaehandler}{classe, type, callback} -Installs an AppleEvent handler. \var{classe} and \var{type} are the -four-character OSA Class and Type designators, \code{'****'} wildcards -are allowed. When a matching AppleEvent is received the parameters are -decoded and your callback is invoked. -\end{methoddesc} - -\begin{methoddesc}[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: \code{_class} and \code{_type} are the Class and Type -designators and \code{_attributes} is a dictionary with the AppleEvent -attributes. - -The return value of your method is packed with -\function{aetools.packevent()} and sent as reply. -\end{methoddesc} - -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. diff --git a/Doc/mac/libscrap.tex b/Doc/mac/libscrap.tex deleted file mode 100644 index aa46278..0000000 --- a/Doc/mac/libscrap.tex +++ /dev/null @@ -1,42 +0,0 @@ -\section{\module{Carbon.Scrap} --- Scrap Manager} -\declaremodule{standard}{Carbon.Scrap} - \platform{Mac} -\modulesynopsis{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. - -The Scrap\index{Scrap Manager} 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 \module{Scrap} module provides low-level access to the functions -of the Scrap Manager. It contains the following functions: - - -\begin{funcdesc}{InfoScrap}{} - Return current information about the scrap. The information is - encoded as a tuple containing the fields \code{(\var{size}, - \var{handle}, \var{count}, \var{state}, \var{path})}. - - \begin{tableii}{l|l}{var}{Field}{Meaning} - \lineii{size}{Size of the scrap in bytes.} - \lineii{handle}{Resource object representing the scrap.} - \lineii{count}{Serial number of the scrap contents.} - \lineii{state}{Integer; positive if in memory, \code{0} if on - disk, negative if uninitialized.} - \lineii{path}{Filename of the scrap when stored on disk.} - \end{tableii} -\end{funcdesc} - - - -\begin{seealso} - \seetitle[http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html] - {Scrap Manager}{Apple's documentation for the Scrap Manager - gives a lot of useful information about using the Scrap - Manager in applications.} -\end{seealso} diff --git a/Doc/mac/mac.tex b/Doc/mac/mac.tex deleted file mode 100644 index 7618057..0000000 --- a/Doc/mac/mac.tex +++ /dev/null @@ -1,88 +0,0 @@ -\documentclass{manual} - -\title{Macintosh Library Modules} - -\input{boilerplate} - -\makeindex % tell \index to actually write the .idx file -\makemodindex % ... and the module index as well. - - -\begin{document} - -\maketitle - -\ifhtml -\chapter*{Front Matter\label{front}} -\fi - -\input{copyright} - -\begin{abstract} - -\noindent -This library reference manual documents Python's extensions for the -Macintosh. It should be used in conjunction with the -\citetitle[../lib/lib.html]{Python Library Reference}, which documents -the standard library and built-in types. - -This manual assumes basic knowledge about the Python language. For an -informal introduction to Python, see the -\citetitle[../tut/tut.html]{Python Tutorial}; the -\citetitle[../ref/ref.html]{Python Reference Manual} remains the -highest authority on syntactic and semantic questions. Finally, the -manual entitled \citetitle[../ext/ext.html]{Extending and Embedding -the Python Interpreter} describes how to add new extensions to Python -and how to embed it in other applications. - -\end{abstract} - -\tableofcontents - - -\input{using.tex} % Using Python on the Macintosh - - -\chapter{MacPython Modules \label{macpython-modules}} - -The following modules are only available on the Macintosh, and are -documented here: - -\localmoduletable - -\input{libmac} -\input{libmacic} -\input{libmacos} -\input{libmacostools} -\input{libmacui} -\input{libframework} -\input{libautogil} - -\input{scripting} - -\input{toolbox} % MacOS Toolbox Modules -\input{libcolorpicker} - -\input{undoc} % Undocumented Modules - -\appendix -\chapter{History and License} -\input{license} - -% -% The ugly "%begin{latexonly}" pseudo-environments are really just to -% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -% not really valuable. -% - -%begin{latexonly} -\renewcommand{\indexname}{Module Index} -%end{latexonly} -\input{modmac.ind} % Module Index - -%begin{latexonly} -\renewcommand{\indexname}{Index} -%end{latexonly} -\input{mac.ind} % Index - -\end{document} diff --git a/Doc/mac/scripting.tex b/Doc/mac/scripting.tex deleted file mode 100644 index 5ec4978..0000000 --- a/Doc/mac/scripting.tex +++ /dev/null @@ -1,101 +0,0 @@ -\chapter{MacPython OSA Modules \label{scripting}} - -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: - -\begin{verbatim} -tell application "Finder" - get name of window 1 -end tell -\end{verbatim} - -In Python, the following code fragment will do the same: - -\begin{verbatim} -import Finder - -f = Finder.Finder() -print f.get(f.window(1).name) -\end{verbatim} - -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 \module{__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 -\module{Standard_Suite} that imports and re-exports everything from -\module{StdSuites.Standard_Suite} but overrides the methods that have -extra functionality. The output of \module{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 -\code{f.get(f.window(1).name)} instead of the more Pythonic -\code{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: -\begin{itemize} - \item spaces are replaced with underscores - \item other non-alphanumeric characters are replaced with - \code{_xx_} where \code{xx} is the hexadecimal character value - \item any Python reserved word gets an underscore appended -\end{itemize} - -Python also has support for creating scriptable applications -in Python, but -The following modules are relevant to MacPython AppleScript support: - -\localmoduletable - -In addition, support modules have been pre-generated for -\module{Finder}, \module{Terminal}, \module{Explorer}, -\module{Netscape}, \module{CodeWarrior}, \module{SystemEvents} and -\module{StdSuites}. - -\input{libgensuitemodule} -\input{libaetools} -\input{libaepack} -\input{libaetypes} -\input{libminiae} diff --git a/Doc/mac/toolbox.tex b/Doc/mac/toolbox.tex deleted file mode 100644 index e7ce24f..0000000 --- a/Doc/mac/toolbox.tex +++ /dev/null @@ -1,173 +0,0 @@ -\chapter{MacOS Toolbox Modules \label{toolbox}} - -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 \member{__doc__} string describing their arguments -and return values, and for additional description you are referred to -\citetitle[http://developer.apple.com/documentation/macos8/mac8.html]{Inside -Macintosh} or similar works. - -These modules all live in a package called \module{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 - -\begin{verbatim} -from Carbon import AE -\end{verbatim} - -\strong{Warning!} These modules are not yet documented. If you -wish to contribute documentation of any of these modules, please get -in touch with \email{docs@python.org}. - -\localmoduletable - - -%\section{Argument Handling for Toolbox Modules} - - -\section{\module{Carbon.AE} --- Apple Events} -\declaremodule{standard}{Carbon.AE} - \platform{Mac} -\modulesynopsis{Interface to the Apple Events toolbox.} - -\section{\module{Carbon.AH} --- Apple Help} -\declaremodule{standard}{Carbon.AH} - \platform{Mac} -\modulesynopsis{Interface to the Apple Help manager.} - - -\section{\module{Carbon.App} --- Appearance Manager} -\declaremodule{standard}{Carbon.App} - \platform{Mac} -\modulesynopsis{Interface to the Appearance Manager.} - - -\section{\module{Carbon.CF} --- Core Foundation} -\declaremodule{standard}{Carbon.CF} - \platform{Mac} -\modulesynopsis{Interface to the Core Foundation.} - -The -\code{CFBase}, \code{CFArray}, \code{CFData}, \code{CFDictionary}, -\code{CFString} and \code{CFURL} objects are supported, some -only partially. - -\section{\module{Carbon.CG} --- Core Graphics} -\declaremodule{standard}{Carbon.CG} - \platform{Mac} -\modulesynopsis{Interface to the Component Manager.} - -\section{\module{Carbon.CarbonEvt} --- Carbon Event Manager} -\declaremodule{standard}{Carbon.CarbonEvt} - \platform{Mac} -\modulesynopsis{Interface to the Carbon Event Manager.} - -\section{\module{Carbon.Cm} --- Component Manager} -\declaremodule{standard}{Carbon.Cm} - \platform{Mac} -\modulesynopsis{Interface to the Component Manager.} - - -\section{\module{Carbon.Ctl} --- Control Manager} -\declaremodule{standard}{Carbon.Ctl} - \platform{Mac} -\modulesynopsis{Interface to the Control Manager.} - - -\section{\module{Carbon.Dlg} --- Dialog Manager} -\declaremodule{standard}{Carbon.Dlg} - \platform{Mac} -\modulesynopsis{Interface to the Dialog Manager.} - - -\section{\module{Carbon.Evt} --- Event Manager} -\declaremodule{standard}{Carbon.Evt} - \platform{Mac} -\modulesynopsis{Interface to the classic Event Manager.} - - -\section{\module{Carbon.Fm} --- Font Manager} -\declaremodule{standard}{Carbon.Fm} - \platform{Mac} -\modulesynopsis{Interface to the Font Manager.} - -\section{\module{Carbon.Folder} --- Folder Manager} -\declaremodule{standard}{Carbon.Folder} - \platform{Mac} -\modulesynopsis{Interface to the Folder Manager.} - - -\section{\module{Carbon.Help} --- Help Manager} -\declaremodule{standard}{Carbon.Help} - \platform{Mac} -\modulesynopsis{Interface to the Carbon Help Manager.} - -\section{\module{Carbon.List} --- List Manager} -\declaremodule{standard}{Carbon.List} - \platform{Mac} -\modulesynopsis{Interface to the List Manager.} - - -\section{\module{Carbon.Menu} --- Menu Manager} -\declaremodule{standard}{Carbon.Menu} - \platform{Mac} -\modulesynopsis{Interface to the Menu Manager.} - - -\section{\module{Carbon.Mlte} --- MultiLingual Text Editor} -\declaremodule{standard}{Carbon.Mlte} - \platform{Mac} -\modulesynopsis{Interface to the MultiLingual Text Editor.} - - -\section{\module{Carbon.Qd} --- QuickDraw} -\declaremodule{builtin}{Carbon.Qd} - \platform{Mac} -\modulesynopsis{Interface to the QuickDraw toolbox.} - - -\section{\module{Carbon.Qdoffs} --- QuickDraw Offscreen} -\declaremodule{builtin}{Carbon.Qdoffs} - \platform{Mac} -\modulesynopsis{Interface to the QuickDraw Offscreen APIs.} - - -\section{\module{Carbon.Qt} --- QuickTime} -\declaremodule{standard}{Carbon.Qt} - \platform{Mac} -\modulesynopsis{Interface to the QuickTime toolbox.} - - -\section{\module{Carbon.Res} --- Resource Manager and Handles} -\declaremodule{standard}{Carbon.Res} - \platform{Mac} -\modulesynopsis{Interface to the Resource Manager and Handles.} - -\section{\module{Carbon.Scrap} --- Scrap Manager} -\declaremodule{standard}{Carbon.Scrap} - \platform{Mac} -\modulesynopsis{Interface to the Carbon Scrap Manager.} - -\section{\module{Carbon.Snd} --- Sound Manager} -\declaremodule{standard}{Carbon.Snd} - \platform{Mac} -\modulesynopsis{Interface to the Sound Manager.} - - -\section{\module{Carbon.TE} --- TextEdit} -\declaremodule{standard}{Carbon.TE} - \platform{Mac} -\modulesynopsis{Interface to TextEdit.} - - -\section{\module{Carbon.Win} --- Window Manager} -\declaremodule{standard}{Carbon.Win} - \platform{Mac} -\modulesynopsis{Interface to the Window Manager.} diff --git a/Doc/mac/undoc.tex b/Doc/mac/undoc.tex deleted file mode 100644 index adbf589..0000000 --- a/Doc/mac/undoc.tex +++ /dev/null @@ -1,85 +0,0 @@ -\chapter{Undocumented Modules \label{undocumented-modules}} - - -The modules in this chapter are poorly documented (if at all). If you -wish to contribute documentation of any of these modules, please get in -touch with -\ulink{\email{docs@python.org}}{mailto:docs@python.org}. - -\localmoduletable - - -\section{\module{applesingle} --- AppleSingle decoder} -\declaremodule{standard}{applesingle} - \platform{Mac} -\modulesynopsis{Rudimentary decoder for AppleSingle format files.} - - -\section{\module{buildtools} --- Helper module for BuildApplet and Friends} -\declaremodule{standard}{buildtools} - \platform{Mac} -\modulesynopsis{Helper module for BuildApplet, BuildApplication and - macfreeze.} - -\deprecated{2.4}{} - -\section{\module{icopen} --- Internet Config replacement for \method{open()}} -\declaremodule{standard}{icopen} - \platform{Mac} -\modulesynopsis{Internet Config replacement for \method{open()}.} - -Importing \module{icopen} will replace the builtin \method{open()} -with a version that uses Internet Config to set file type and creator -for new files. - - -\section{\module{macerrors} --- Mac OS Errors} -\declaremodule{standard}{macerrors} - \platform{Mac} -\modulesynopsis{Constant definitions for many Mac OS error codes.} - -\module{macerrors} contains constant definitions for many Mac OS error -codes. - - -\section{\module{macresource} --- Locate script resources} -\declaremodule{standard}{macresource} - \platform{Mac} -\modulesynopsis{Locate script resources.} - -\module{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. - -\section{\module{Nav} --- NavServices calls} -\declaremodule{standard}{Nav} - \platform{Mac} -\modulesynopsis{Interface to Navigation Services.} - -A low-level interface to Navigation Services. - -\section{\module{PixMapWrapper} --- Wrapper for PixMap objects} -\declaremodule{standard}{PixMapWrapper} - \platform{Mac} -\modulesynopsis{Wrapper for PixMap objects.} - -\module{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 \module{PIL} images. - -\section{\module{videoreader} --- Read QuickTime movies} -\declaremodule{standard}{videoreader} - \platform{Mac} -\modulesynopsis{Read QuickTime movies frame by frame for further processing.} - -\module{videoreader} reads and decodes QuickTime movies and passes -a stream of images to your program. It also provides some support for -audio tracks. - -\section{\module{W} --- Widgets built on \module{FrameWork}} -\declaremodule{standard}{W} - \platform{Mac} -\modulesynopsis{Widgets for the Mac, built on top of \refmodule{FrameWork}.} - -The \module{W} widgets are used extensively in the \program{IDE}. - diff --git a/Doc/mac/using.tex b/Doc/mac/using.tex deleted file mode 100644 index ca522c6..0000000 --- a/Doc/mac/using.tex +++ /dev/null @@ -1,178 +0,0 @@ -\chapter{Using Python on a Macintosh \label{using}} -\sectionauthor{Bob Savage}{bobsavage@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 -\url{http://www.cwi.nl/\textasciitilde jack/macpython} for installers -for the latest 2.3 release for Mac OS 9 and related documentation. - -\section{Getting and Installing MacPython \label{getting-OSX}} - -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 -(\url{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: - -\begin{itemize} -\item 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. - -\item 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/. -\end{itemize} - -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. - - -\subsection{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 -\url{http://www.barebones.com/products/bbedit/index.shtml}) are good choices, as -is \program{TextMate} (see \url{http://macromates.com/}). Other editors include -\program{Gvim} (\url{http://macvim.org}) and \program{Aquamacs} -(\url{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: - -\begin{itemize} -\item Drag it to \program{PythonLauncher} -\item 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. -\end{itemize} - - -\subsection{Running scripts with a GUI \label{osx-gui-scripts}} - -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}. - -\subsection{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{\textasciitilde - /.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}, ``Installing Additional Python Packages.'' - - -\section{The IDE\label{IDE}} - -MacPython ships with the standard IDLE development environment. A good -introduction to using IDLE can be found at -\url{http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html}. - - -\section{Installing Additional Python Packages \label{mac-package-manager}} - -There are several methods to install additional Python packages: - -\begin{itemize} -\item \url{http://pythonmac.org/packages/} contains selected compiled packages - for Python 2.5, 2.4, and 2.3. -\item Packages can be installed via the standard Python distutils mode - (\samp{python setup.py install}). -\item Many packages can also be installed via the \program{setuptools} - extension. -\end{itemize} - - -\section{GUI Programming on the Mac} - -There are several options for building GUI applications on the Mac with Python. - -\emph{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 \url{http://pybojc.sourceforge.net}. - -The standard Python GUI toolkit is \module{Tkinter}, based on the cross-platform -Tk toolkit (\url{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 -\url{http://www.activestate.com}; it can also be built from source. - -\emph{wxPython} is another popular cross-platform GUI toolkit that runs natively -on Mac OS X. Packages and documentation are available from -\url{http://www.wxpython.org}. - -\emph{PyQt} is another popular cross-platform GUI toolkit that runs natively on -Mac OS X. More information can be found at -\url{http://www.riverbankcomputing.co.uk/pyqt/}. - - -\section{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 \url{http://undefined.org/python/\#py2app}. - -\section{Application Scripting} - -Python can also be used to script other Mac applications via Apple's Open -Scripting Architecture (OSA); see -\url{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 \emph{AppleScript} language for automating your Mac. A related -package, \emph{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. - -\section{Other Resources} - -The MacPython mailing list is an excellent support resource for Python users and -developers on the Mac: - -\url{http://www.python.org/community/sigs/current/pythonmac-sig/} - -Another useful resource is the MacPython wiki: - -\url{http://wiki.python.org/moin/MacPython} |