diff options
| -rw-r--r-- | Doc/Makefile | 3 | ||||
| -rw-r--r-- | Doc/lib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 2 | ||||
| -rw-r--r-- | Doc/libmacfs.tex | 16 | ||||
| -rw-r--r-- | Doc/libmacostools.tex | 39 | ||||
| -rw-r--r-- | Doc/libmacui.tex | 201 | ||||
| -rw-r--r-- | Doc/mac/libmacfs.tex | 16 | ||||
| -rw-r--r-- | Doc/mac/libmacostools.tex | 39 | ||||
| -rw-r--r-- | Doc/mac/libmacui.tex | 201 |
9 files changed, 504 insertions, 15 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 9dafd35..50b4782 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -111,7 +111,8 @@ libhtmllib.tex libhttplib.tex \ libimageop.tex libimgfile.tex libintro.tex \ libjpeg.tex \ libmac.tex libmacconsole.tex libmacdnr.tex \ - libmacfs.tex libmacos.tex libmactcp.tex libmacspeech.tex \ + libmacfs.tex libmacos.tex libmacostools.tex libmactcp.tex \ + libmacspeech.tex libmacui.tex \ libmain.tex libmarshal.tex libmath.tex \ libmd5.tex libmimetools.tex libmisc.tex \ libmm.tex libmpz.tex \ diff --git a/Doc/lib.tex b/Doc/lib.tex index 049b0ce..f8a957f 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -160,8 +160,10 @@ to Python and how to embed it in other applications. \input{libmacdnr} \input{libmacfs} \input{libmacos} +\input{libmacostools} \input{libmactcp} \input{libmacspeech} +\input{libmacui} \input{libstdwin} % STDWIN ONLY diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 049b0ce..f8a957f 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -160,8 +160,10 @@ to Python and how to embed it in other applications. \input{libmacdnr} \input{libmacfs} \input{libmacos} +\input{libmacostools} \input{libmactcp} \input{libmacspeech} +\input{libmacui} \input{libstdwin} % STDWIN ONLY diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex index fd7ac3f..254ed25 100644 --- a/Doc/libmacfs.tex +++ b/Doc/libmacfs.tex @@ -68,12 +68,13 @@ Return an FSSpec object and a success-indicator. \begin{funcdesc}{FindFolder}{where\, which\, create} Locates one of the ``special'' folders that MacOS knows about, such as -the trash or the Preferences folder. \var{Where} is the disk to search -(\code{0x8000} for the boot disk), \var{which} is the 4-char string -specifying which folder to locate. Setting \var{create} causes the -folder to be created if it does not exist. Returns a \code{(vrefnum, -dirid)} tuple. See Inside Mac VI for a complete description, including -4-char names. +the trash or the Preferences folder. \var{Where} is the disk to +search, \var{which} is the 4-char string specifying which folder to +locate. Setting \var{create} causes the folder to be created if it +does not exist. Returns a \code{(vrefnum, dirid)} tuple. + +The constants for \var{where} and \var{which} can be obtained from the +standard module \var{MACFS}. \end{funcdesc} \subsection{FSSpec objects} @@ -168,7 +169,8 @@ The 4-char type code of the file. \end{datadesc} \begin{datadesc}{Flags} -The finder flags for the file as 16-bit integer. +The finder flags for the file as 16-bit integer. The bit values in +\var{Flags} are defined in standard module \var{MACFS}. \end{datadesc} \begin{datadesc}{Location} diff --git a/Doc/libmacostools.tex b/Doc/libmacostools.tex new file mode 100644 index 0000000..1e60983 --- /dev/null +++ b/Doc/libmacostools.tex @@ -0,0 +1,39 @@ + +\section{Standard module \sectcode{macostools}} +\stmodindex{macostools} + +This module contains some convenience routines for file-manipulation +on the Macintosh. + +The \code{macostools} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module macostools)} + +\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}} +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. +\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}. Both may be +specified as pathnames or \var{FSSpec} objects. +\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 \code{mkalias} +could conceivably have incompatible behaviour in some cases. diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex new file mode 100644 index 0000000..08f0236 --- /dev/null +++ b/Doc/libmacui.tex @@ -0,0 +1,201 @@ +\section{Standard module \sectcode{EasyDialogs}} +\stmodindex{EasyDialogs} + +The \code{EasyDialogs} module contains some simple dialogs for +the Macintosh, modelled after the \code{stdwin} dialogs with similar +names. + +The \code{EasyDialogs} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module EasyDialogs)} + +\begin{funcdesc}{Message}{str} +A modal dialog with the message text \var{str}, which should be at +most 255 characters long, is displayed. Control is returned when the +user clicks ``OK''. +\end{funcdesc} + +\begin{funcdesc}{AskString}{prompt\optional{\, default}} +Ask the user to input a string value, in a modal dialog. \var{Prompt} +is the promt message, the optional \var{default} arg is the initial +value for the string. All strings can be at most 255 bytes +long. \var{AskString} returns the string entered or \code{None} in +case the user cancelled. +\end{funcdesc} + +\begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}} +Present a dialog with text \var{question} and three buttons labelled +``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for +no and \code{-1} for cancel. The default return value chosen by +hitting return is \code{0}. This can be changed with the optional +\var{default} argument. +\end{funcdesc} + +Note that \code{EasyDialogs} does not currently use the notification +manager. This means that displaying dialogs while the program is in +the background will need to unexpected results and possibly crashes. + + +\section{Standard module \sectcode{FrameWork}} +\stmodindex{FrameWork} + +The \code{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. + +The \code{FrameWork} is still very much work-in-progress, and the +documentation describes only the most important functionality, and not +in the most logical manner at that. Examine the source for more +esoteric needs. + +The \code{EasyDialogs} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module FrameWork)} + +\begin{funcdesc}{Application}{} +An object representing the complete application. See below for a +description of the methods. The default \code{__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 crate the +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. +\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} + + +\subsection{Application objects} +Application objects have the following methods, among others: + +\renewcommand{\indexsubitem}{(Application method)} + +\begin{funcdesc}{makeusermenus}{} +Override this method if you need menus in your application. Append the +menus to \code{self.menubar}. +\end{funcdesc} + +\begin{funcdesc}{getabouttext}{} +Override this method to return a text string describing your +application. Alternatively, override the \code{do_about} method for +more elaborate about messages. +\end{funcdesc} + +\begin{funcdesc}{mainloop}{\optional{mask\, 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). This method does not return until \code{self} is raised. + +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. +\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 +provided in a \code{Window} object, which overrides the +application-wide handler if the window is frontmost. +\end{funcdesc} + +\begin{funcdesc}{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 the \code{DialogWindow} object involved). Override if you +need special handling of dialog events (keyboard shortcuts, etc). +\end{funcdesc} + +\subsection{Window Objects} + +Window objects have the following methods, among others: + +\renewcommand{\indexsubitem}{(Window method)} + +\begin{funcdesc}{open}{} +Override this method to open a window. Store the MacOS window-id in +\code{self.wid} and call \code{self.do_postopen} to register the +window with the parent application. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Override this method to do any special processing on window +close. Call \code{self.do_postclose} to cleanup the parent state. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} +Called after the window is resized. Override if more needs to be done +than calling \code{InvalRect}. +\end{funcdesc} + +\begin{funcdesc}{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{funcdesc} + +\begin{funcdesc}{do_update}{macoswindowid\, event} +An update event for the window was received. Redraw the window. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{activate\, event} +The window was activated (\code{activate==1}) or deactivated +(\code{activate==0}). Handle things like focus highlighting, etc. +\end{funcdesc} + +\subsection{DialogWindow Objects} + +DialogWindow objects have the following methods besides those of +\code{Window} objects: + +\renewcommand{\indexsubitem}{(DialogWindow method)} + +\begin{funcdesc}{open}{resid} +Create the dialog window, from the DLOG resource with id +\var{resid}. The dialog object is stored in \code{self.wid}. +\end{funcdesc} + +\begin{funcdesc}{do_itemhit}{item\, event} +Item number \var{item} was hit. You are responsible for redrawing +toggle buttons, etc. +\end{funcdesc} + diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex index fd7ac3f..254ed25 100644 --- a/Doc/mac/libmacfs.tex +++ b/Doc/mac/libmacfs.tex @@ -68,12 +68,13 @@ Return an FSSpec object and a success-indicator. \begin{funcdesc}{FindFolder}{where\, which\, create} Locates one of the ``special'' folders that MacOS knows about, such as -the trash or the Preferences folder. \var{Where} is the disk to search -(\code{0x8000} for the boot disk), \var{which} is the 4-char string -specifying which folder to locate. Setting \var{create} causes the -folder to be created if it does not exist. Returns a \code{(vrefnum, -dirid)} tuple. See Inside Mac VI for a complete description, including -4-char names. +the trash or the Preferences folder. \var{Where} is the disk to +search, \var{which} is the 4-char string specifying which folder to +locate. Setting \var{create} causes the folder to be created if it +does not exist. Returns a \code{(vrefnum, dirid)} tuple. + +The constants for \var{where} and \var{which} can be obtained from the +standard module \var{MACFS}. \end{funcdesc} \subsection{FSSpec objects} @@ -168,7 +169,8 @@ The 4-char type code of the file. \end{datadesc} \begin{datadesc}{Flags} -The finder flags for the file as 16-bit integer. +The finder flags for the file as 16-bit integer. The bit values in +\var{Flags} are defined in standard module \var{MACFS}. \end{datadesc} \begin{datadesc}{Location} diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex new file mode 100644 index 0000000..1e60983 --- /dev/null +++ b/Doc/mac/libmacostools.tex @@ -0,0 +1,39 @@ + +\section{Standard module \sectcode{macostools}} +\stmodindex{macostools} + +This module contains some convenience routines for file-manipulation +on the Macintosh. + +The \code{macostools} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module macostools)} + +\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}} +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. +\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}. Both may be +specified as pathnames or \var{FSSpec} objects. +\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 \code{mkalias} +could conceivably have incompatible behaviour in some cases. diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex new file mode 100644 index 0000000..08f0236 --- /dev/null +++ b/Doc/mac/libmacui.tex @@ -0,0 +1,201 @@ +\section{Standard module \sectcode{EasyDialogs}} +\stmodindex{EasyDialogs} + +The \code{EasyDialogs} module contains some simple dialogs for +the Macintosh, modelled after the \code{stdwin} dialogs with similar +names. + +The \code{EasyDialogs} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module EasyDialogs)} + +\begin{funcdesc}{Message}{str} +A modal dialog with the message text \var{str}, which should be at +most 255 characters long, is displayed. Control is returned when the +user clicks ``OK''. +\end{funcdesc} + +\begin{funcdesc}{AskString}{prompt\optional{\, default}} +Ask the user to input a string value, in a modal dialog. \var{Prompt} +is the promt message, the optional \var{default} arg is the initial +value for the string. All strings can be at most 255 bytes +long. \var{AskString} returns the string entered or \code{None} in +case the user cancelled. +\end{funcdesc} + +\begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}} +Present a dialog with text \var{question} and three buttons labelled +``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for +no and \code{-1} for cancel. The default return value chosen by +hitting return is \code{0}. This can be changed with the optional +\var{default} argument. +\end{funcdesc} + +Note that \code{EasyDialogs} does not currently use the notification +manager. This means that displaying dialogs while the program is in +the background will need to unexpected results and possibly crashes. + + +\section{Standard module \sectcode{FrameWork}} +\stmodindex{FrameWork} + +The \code{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. + +The \code{FrameWork} is still very much work-in-progress, and the +documentation describes only the most important functionality, and not +in the most logical manner at that. Examine the source for more +esoteric needs. + +The \code{EasyDialogs} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module FrameWork)} + +\begin{funcdesc}{Application}{} +An object representing the complete application. See below for a +description of the methods. The default \code{__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 crate the +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. +\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} + + +\subsection{Application objects} +Application objects have the following methods, among others: + +\renewcommand{\indexsubitem}{(Application method)} + +\begin{funcdesc}{makeusermenus}{} +Override this method if you need menus in your application. Append the +menus to \code{self.menubar}. +\end{funcdesc} + +\begin{funcdesc}{getabouttext}{} +Override this method to return a text string describing your +application. Alternatively, override the \code{do_about} method for +more elaborate about messages. +\end{funcdesc} + +\begin{funcdesc}{mainloop}{\optional{mask\, 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). This method does not return until \code{self} is raised. + +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. +\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 +provided in a \code{Window} object, which overrides the +application-wide handler if the window is frontmost. +\end{funcdesc} + +\begin{funcdesc}{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 the \code{DialogWindow} object involved). Override if you +need special handling of dialog events (keyboard shortcuts, etc). +\end{funcdesc} + +\subsection{Window Objects} + +Window objects have the following methods, among others: + +\renewcommand{\indexsubitem}{(Window method)} + +\begin{funcdesc}{open}{} +Override this method to open a window. Store the MacOS window-id in +\code{self.wid} and call \code{self.do_postopen} to register the +window with the parent application. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Override this method to do any special processing on window +close. Call \code{self.do_postclose} to cleanup the parent state. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} +Called after the window is resized. Override if more needs to be done +than calling \code{InvalRect}. +\end{funcdesc} + +\begin{funcdesc}{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{funcdesc} + +\begin{funcdesc}{do_update}{macoswindowid\, event} +An update event for the window was received. Redraw the window. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{activate\, event} +The window was activated (\code{activate==1}) or deactivated +(\code{activate==0}). Handle things like focus highlighting, etc. +\end{funcdesc} + +\subsection{DialogWindow Objects} + +DialogWindow objects have the following methods besides those of +\code{Window} objects: + +\renewcommand{\indexsubitem}{(DialogWindow method)} + +\begin{funcdesc}{open}{resid} +Create the dialog window, from the DLOG resource with id +\var{resid}. The dialog object is stored in \code{self.wid}. +\end{funcdesc} + +\begin{funcdesc}{do_itemhit}{item\, event} +Item number \var{item} was hit. You are responsible for redrawing +toggle buttons, etc. +\end{funcdesc} + |