Patches for Mac module docs by Jack
diff --git a/Doc/libmac.tex b/Doc/libmac.tex
index 344d300..270620a 100644
--- a/Doc/libmac.tex
+++ b/Doc/libmac.tex
@@ -58,7 +58,14 @@
\code{sync},
\code{unlink},
\code{write},
-as well as the exception \code{error}.
+as well as the exception \code{error}. Note that the times returned by
+\code{stat} are floating-point values, like all time values in
+MacPython.
+
+One additional function is available: \code{xstat}. This function
+returns the same information as \code{stat}, but with three extra
+values appended: the size of the resource fork of the file and its
+4-char creator and type.
\section{Standard Module \sectcode{macpath}}
diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex
index f4a7034..be566cb 100644
--- a/Doc/libmacfs.tex
+++ b/Doc/libmacfs.tex
@@ -89,6 +89,11 @@
standard module \var{MACFS}.
\end{funcdesc}
+\begin{funcdesc}{FindApplication}{creator}
+Locate the application with 4-char creator code \var{creator}. The
+function returns an FSSpec object pointing to the application.
+\end{funcdesc}
+
\subsection{FSSpec objects}
\renewcommand{\indexsubitem}{(FSSpec object attribute)}
@@ -134,6 +139,17 @@
\var{finfo} object.
\end{funcdesc}
+\begin{funcdesc}{GetDates}{}
+Return a tuple with three floating point values representing the
+creation date, modification date and backup date of the file.
+\end{funcdesc}
+
+\begin{funcdesc}{SetDates}{crdate\, moddate\, backupdate}
+Set the creation, modification and backup date of the file. The values
+are in the standard floating point format used for times throughout
+Python.
+\end{funcdesc}
+
\subsection{alias objects}
\renewcommand{\indexsubitem}{(alias object attribute)}
diff --git a/Doc/libmacos.tex b/Doc/libmacos.tex
index e48a0c3..2b7628f 100644
--- a/Doc/libmacos.tex
+++ b/Doc/libmacos.tex
@@ -15,6 +15,8 @@
functions in this module or from other mac-specific modules like the
toolbox interfaces. The arguments are the integer error code (the
\var{OSErr} value) and a textual description of the error code.
+Symbolic names for all known error codes are defined in the standard
+module \var{macerrors}.
\end{excdesc}
\begin{funcdesc}{SetHighLevelEventHandler}{handler}
@@ -42,8 +44,8 @@
the background values will be set the the same as the foreground
values. The function returns nothing.
-The default values, which are based on nothing at all, are 12, 6, 1
-and 12 respectively.
+The default values, which are based on minimal empirical testing, are 12, 1, 6
+and 2 respectively.
\end{funcdesc}
\begin{funcdesc}{EnableAppswitch}{onoff}
@@ -77,11 +79,22 @@
This function will put a splash window
on-screen, with the contents of the DLOG resource specified by
\code{resid}. Calling with a zero argument will remove the splash
-screen. This function is useful if you want to post a splash screen
+screen. This function is useful if you want an applet to post a splash screen
early in initialization without first having to load numerous
extension modules.
\end{funcdesc}
+\begin{funcdesc}{DebugStr}{message \optional{\, object}}
+Drop to the low-level debugger with message \var{message}. The
+optional \var{object} argument is not used, but can easily be
+inspected from the debugger.
+
+Note that you should use this function with extreme care: if no
+low-level debugger like MacsBug is installed this call will crash your
+system. It is intended mainly for developers of Python extension
+modules.
+\end{funcdesc}
+
\begin{funcdesc}{openrf}{name \optional{\, mode}}
Open the resource fork of a file. Arguments are the same as for the
builtin function \code{open}. The object returned has file-like
diff --git a/Doc/libmacostools.tex b/Doc/libmacostools.tex
index 1e60983..3a3c3a3 100644
--- a/Doc/libmacostools.tex
+++ b/Doc/libmacostools.tex
@@ -9,14 +9,17 @@
\renewcommand{\indexsubitem}{(in module macostools)}
-\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}}
+\begin{funcdesc}{copy}{src\, dst\optional{\, createpath, copytimes}}
Copy file \var{src} to \var{dst}. The files can be specified as
pathnames or \code{FSSpec} objects. If \var{createpath} is non-zero
\var{dst} must be a pathname and the folders leading to the
-destination are created if necessary.
-The method copies data and resource fork and some finder information
-(creator, type and flags). Custom icons, comments and icon position
-are not copied.
+destination 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.
+
+If the source is an alias the original to which the alias points is
+copied, not the aliasfile.
\end{funcdesc}
\begin{funcdesc}{copytree}{src\, dst}
@@ -30,6 +33,13 @@
specified as pathnames or \var{FSSpec} objects.
\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 prod the finder into redrawing the
+files icon.
+\end{funcdesc}
+
\begin{datadesc}{BUFSIZ}
The buffer size for \code{copy}, default 1 megabyte.
\end{datadesc}
@@ -37,3 +47,53 @@
Note that the process of creating finder aliases is not specified in
the Apple documentation. Hence, aliases created with \code{mkalias}
could conceivably have incompatible behaviour in some cases.
+
+\section{Standard module \sectcode{findertools}}
+\stmodindex{findertools}
+
+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 \code{FSSpec} objects.
+
+The \code{findertools} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macostools)}
+
+\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 (again specified by full pathname or
+FSSpec). The behaviour is identical to selecting the file and using
+the print command in the finder.
+\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 \code{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 \code{Alias} object pointing to
+the new file.
+\end{funcdesc}
+
+\begin{funcdesc}{sleep}{}
+Tell the finder to put the mac 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/libmacui.tex b/Doc/libmacui.tex
index 1c2df7c..56a00c3 100644
--- a/Doc/libmacui.tex
+++ b/Doc/libmacui.tex
@@ -97,6 +97,14 @@
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.
+
+In stead 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} \code{fixmenudimstate} method sets the
+correct dimming for all menu items based on the current front window.
\end{funcdesc}
\begin{funcdesc}{Separator}{menu}
@@ -125,6 +133,13 @@
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}
Application objects have the following methods, among others:
@@ -147,7 +162,8 @@
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). This method does not return until \code{self} is raised.
+idea). While raising \code{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
@@ -155,6 +171,10 @@
for non-FrameWork windows, etc.
\end{funcdesc}
+\begin{funcdesc}{_quit}{}
+Terminate the event \code{mainloop} at the next convenient moment.
+\end{funcdesc}
+
\begin{funcdesc}{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
@@ -226,7 +246,7 @@
\subsection{ScrolledWindow Object}
ScrolledWindow objects are ControlsWindow objects with the following
-extra mathods:
+extra methods:
\renewcommand{\indexsubitem}{(ScrolledWindow method)}
@@ -296,3 +316,63 @@
toggle buttons, etc.
\end{funcdesc}
+\section{Standard module \sectcode{MiniAEFrame}}
+\stmodindex{MiniAEFrame}
+
+The module \var{MiniAEFrame} provides a framework for an application
+that can function as an OSA server, i.e. receive and process
+AppleEvents. It can be used in conjunction with \var{FrameWork} or
+standalone.
+
+This module is temporary, it will eventually be replaced by a module
+that handles argument names better and possibly automates making your
+application scriptable.
+
+The \var{MiniAEFrame} module defines the following classes:
+
+\renewcommand{\indexsubitem}{(in module MiniAEFrame)}
+
+\begin{funcdesc}{AEServer}{}
+A class that handles AppleEvent dispatch. Your application should
+subclass this class together with either
+\code{MiniAEFrame.MiniApplication} or
+\code{FrameWork.Application}. Your \code{__init__} method should call
+the \code{__init__} method for both classes.
+\end{funcdesc}
+
+\begin{funcdesc}{MiniApplication}{}
+A class that is more or less compatible with
+\code{FrameWork.Application} but with less functionality. Its
+eventloop 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 \code{AEServer} but does not
+provide its own windows, etc.
+\end{funcdesc}
+
+\subsection{AEServer Objects}
+
+\renewcommand{\indexsubitem}{(AEServer method)}
+
+\begin{funcdesc}{installaehandler}{classe\, type\, callback}
+Installs an AppleEvent handler. \code{Classe} and \code{type} are the
+four-char 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{funcdesc}
+
+\begin{funcdesc}{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-char 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
+\code{aetools.packevent} and sent as reply.
+\end{funcdesc}
+
+Note that there are some serious problems with the current
+design. AppleEvents which have non-identifier 4-char 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/libmac.tex b/Doc/mac/libmac.tex
index 344d300..270620a 100644
--- a/Doc/mac/libmac.tex
+++ b/Doc/mac/libmac.tex
@@ -58,7 +58,14 @@
\code{sync},
\code{unlink},
\code{write},
-as well as the exception \code{error}.
+as well as the exception \code{error}. Note that the times returned by
+\code{stat} are floating-point values, like all time values in
+MacPython.
+
+One additional function is available: \code{xstat}. This function
+returns the same information as \code{stat}, but with three extra
+values appended: the size of the resource fork of the file and its
+4-char creator and type.
\section{Standard Module \sectcode{macpath}}
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index f4a7034..be566cb 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -89,6 +89,11 @@
standard module \var{MACFS}.
\end{funcdesc}
+\begin{funcdesc}{FindApplication}{creator}
+Locate the application with 4-char creator code \var{creator}. The
+function returns an FSSpec object pointing to the application.
+\end{funcdesc}
+
\subsection{FSSpec objects}
\renewcommand{\indexsubitem}{(FSSpec object attribute)}
@@ -134,6 +139,17 @@
\var{finfo} object.
\end{funcdesc}
+\begin{funcdesc}{GetDates}{}
+Return a tuple with three floating point values representing the
+creation date, modification date and backup date of the file.
+\end{funcdesc}
+
+\begin{funcdesc}{SetDates}{crdate\, moddate\, backupdate}
+Set the creation, modification and backup date of the file. The values
+are in the standard floating point format used for times throughout
+Python.
+\end{funcdesc}
+
\subsection{alias objects}
\renewcommand{\indexsubitem}{(alias object attribute)}
diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex
index e48a0c3..2b7628f 100644
--- a/Doc/mac/libmacos.tex
+++ b/Doc/mac/libmacos.tex
@@ -15,6 +15,8 @@
functions in this module or from other mac-specific modules like the
toolbox interfaces. The arguments are the integer error code (the
\var{OSErr} value) and a textual description of the error code.
+Symbolic names for all known error codes are defined in the standard
+module \var{macerrors}.
\end{excdesc}
\begin{funcdesc}{SetHighLevelEventHandler}{handler}
@@ -42,8 +44,8 @@
the background values will be set the the same as the foreground
values. The function returns nothing.
-The default values, which are based on nothing at all, are 12, 6, 1
-and 12 respectively.
+The default values, which are based on minimal empirical testing, are 12, 1, 6
+and 2 respectively.
\end{funcdesc}
\begin{funcdesc}{EnableAppswitch}{onoff}
@@ -77,11 +79,22 @@
This function will put a splash window
on-screen, with the contents of the DLOG resource specified by
\code{resid}. Calling with a zero argument will remove the splash
-screen. This function is useful if you want to post a splash screen
+screen. This function is useful if you want an applet to post a splash screen
early in initialization without first having to load numerous
extension modules.
\end{funcdesc}
+\begin{funcdesc}{DebugStr}{message \optional{\, object}}
+Drop to the low-level debugger with message \var{message}. The
+optional \var{object} argument is not used, but can easily be
+inspected from the debugger.
+
+Note that you should use this function with extreme care: if no
+low-level debugger like MacsBug is installed this call will crash your
+system. It is intended mainly for developers of Python extension
+modules.
+\end{funcdesc}
+
\begin{funcdesc}{openrf}{name \optional{\, mode}}
Open the resource fork of a file. Arguments are the same as for the
builtin function \code{open}. The object returned has file-like
diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex
index 1e60983..3a3c3a3 100644
--- a/Doc/mac/libmacostools.tex
+++ b/Doc/mac/libmacostools.tex
@@ -9,14 +9,17 @@
\renewcommand{\indexsubitem}{(in module macostools)}
-\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}}
+\begin{funcdesc}{copy}{src\, dst\optional{\, createpath, copytimes}}
Copy file \var{src} to \var{dst}. The files can be specified as
pathnames or \code{FSSpec} objects. If \var{createpath} is non-zero
\var{dst} must be a pathname and the folders leading to the
-destination are created if necessary.
-The method copies data and resource fork and some finder information
-(creator, type and flags). Custom icons, comments and icon position
-are not copied.
+destination 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.
+
+If the source is an alias the original to which the alias points is
+copied, not the aliasfile.
\end{funcdesc}
\begin{funcdesc}{copytree}{src\, dst}
@@ -30,6 +33,13 @@
specified as pathnames or \var{FSSpec} objects.
\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 prod the finder into redrawing the
+files icon.
+\end{funcdesc}
+
\begin{datadesc}{BUFSIZ}
The buffer size for \code{copy}, default 1 megabyte.
\end{datadesc}
@@ -37,3 +47,53 @@
Note that the process of creating finder aliases is not specified in
the Apple documentation. Hence, aliases created with \code{mkalias}
could conceivably have incompatible behaviour in some cases.
+
+\section{Standard module \sectcode{findertools}}
+\stmodindex{findertools}
+
+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 \code{FSSpec} objects.
+
+The \code{findertools} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macostools)}
+
+\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 (again specified by full pathname or
+FSSpec). The behaviour is identical to selecting the file and using
+the print command in the finder.
+\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 \code{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 \code{Alias} object pointing to
+the new file.
+\end{funcdesc}
+
+\begin{funcdesc}{sleep}{}
+Tell the finder to put the mac 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
index 1c2df7c..56a00c3 100644
--- a/Doc/mac/libmacui.tex
+++ b/Doc/mac/libmacui.tex
@@ -97,6 +97,14 @@
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.
+
+In stead 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} \code{fixmenudimstate} method sets the
+correct dimming for all menu items based on the current front window.
\end{funcdesc}
\begin{funcdesc}{Separator}{menu}
@@ -125,6 +133,13 @@
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}
Application objects have the following methods, among others:
@@ -147,7 +162,8 @@
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). This method does not return until \code{self} is raised.
+idea). While raising \code{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
@@ -155,6 +171,10 @@
for non-FrameWork windows, etc.
\end{funcdesc}
+\begin{funcdesc}{_quit}{}
+Terminate the event \code{mainloop} at the next convenient moment.
+\end{funcdesc}
+
\begin{funcdesc}{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
@@ -226,7 +246,7 @@
\subsection{ScrolledWindow Object}
ScrolledWindow objects are ControlsWindow objects with the following
-extra mathods:
+extra methods:
\renewcommand{\indexsubitem}{(ScrolledWindow method)}
@@ -296,3 +316,63 @@
toggle buttons, etc.
\end{funcdesc}
+\section{Standard module \sectcode{MiniAEFrame}}
+\stmodindex{MiniAEFrame}
+
+The module \var{MiniAEFrame} provides a framework for an application
+that can function as an OSA server, i.e. receive and process
+AppleEvents. It can be used in conjunction with \var{FrameWork} or
+standalone.
+
+This module is temporary, it will eventually be replaced by a module
+that handles argument names better and possibly automates making your
+application scriptable.
+
+The \var{MiniAEFrame} module defines the following classes:
+
+\renewcommand{\indexsubitem}{(in module MiniAEFrame)}
+
+\begin{funcdesc}{AEServer}{}
+A class that handles AppleEvent dispatch. Your application should
+subclass this class together with either
+\code{MiniAEFrame.MiniApplication} or
+\code{FrameWork.Application}. Your \code{__init__} method should call
+the \code{__init__} method for both classes.
+\end{funcdesc}
+
+\begin{funcdesc}{MiniApplication}{}
+A class that is more or less compatible with
+\code{FrameWork.Application} but with less functionality. Its
+eventloop 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 \code{AEServer} but does not
+provide its own windows, etc.
+\end{funcdesc}
+
+\subsection{AEServer Objects}
+
+\renewcommand{\indexsubitem}{(AEServer method)}
+
+\begin{funcdesc}{installaehandler}{classe\, type\, callback}
+Installs an AppleEvent handler. \code{Classe} and \code{type} are the
+four-char 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{funcdesc}
+
+\begin{funcdesc}{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-char 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
+\code{aetools.packevent} and sent as reply.
+\end{funcdesc}
+
+Note that there are some serious problems with the current
+design. AppleEvents which have non-identifier 4-char 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.