diff options
| -rw-r--r-- | Doc/libmac.tex | 9 | ||||
| -rw-r--r-- | Doc/libmacfs.tex | 16 | ||||
| -rw-r--r-- | Doc/libmacos.tex | 19 | ||||
| -rw-r--r-- | Doc/libmacostools.tex | 70 | ||||
| -rw-r--r-- | Doc/libmacui.tex | 84 | ||||
| -rw-r--r-- | Doc/mac/libmac.tex | 9 | ||||
| -rw-r--r-- | Doc/mac/libmacfs.tex | 16 | ||||
| -rw-r--r-- | Doc/mac/libmacos.tex | 19 | ||||
| -rw-r--r-- | Doc/mac/libmacostools.tex | 70 | ||||
| -rw-r--r-- | Doc/mac/libmacui.tex | 84 |
10 files changed, 374 insertions, 22 deletions
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 @@ The following functions are available in this module: \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 @@ The constants for \var{where} and \var{which} can be obtained from the 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 @@ Set the finder info for the file to the values specified in the \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 @@ 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 \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 @@ different values to use when python runs in the background, otherwise 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 @@ Return the textual description of MacOS error code \var{errno}. 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 @@ The \code{macostools} module defines the following functions: \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 @@ Create a finder alias \var{dst} pointing to \var{src}. Both may be 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 @@ The buffer size for \code{copy}, default 1 megabyte. 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 @@ item it, 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. + +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 @@ whole window on-screen. The window will however always be exact the 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 @@ 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). 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 @@ windows and dialogs, handling drags and resizes, Apple Events, events 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 @@ user. Tracking and such has already been taken care of. \subsection{ScrolledWindow Object} ScrolledWindow objects are ControlsWindow objects with the following -extra mathods: +extra methods: \renewcommand{\indexsubitem}{(ScrolledWindow method)} @@ -296,3 +316,63 @@ Item number \var{item} was hit. You are responsible for redrawing 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 @@ The following functions are available in this module: \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 @@ The constants for \var{where} and \var{which} can be obtained from the 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 @@ Set the finder info for the file to the values specified in the \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 @@ 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 \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 @@ different values to use when python runs in the background, otherwise 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 @@ Return the textual description of MacOS error code \var{errno}. 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 @@ The \code{macostools} module defines the following functions: \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 @@ Create a finder alias \var{dst} pointing to \var{src}. Both may be 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 @@ The buffer size for \code{copy}, default 1 megabyte. 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 @@ item it, 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. + +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 @@ whole window on-screen. The window will however always be exact the 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 @@ 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). 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 @@ windows and dialogs, handling drags and resizes, Apple Events, events 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 @@ user. Tracking and such has already been taken care of. \subsection{ScrolledWindow Object} ScrolledWindow objects are ControlsWindow objects with the following -extra mathods: +extra methods: \renewcommand{\indexsubitem}{(ScrolledWindow method)} @@ -296,3 +316,63 @@ Item number \var{item} was hit. You are responsible for redrawing 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. |