diff options
| -rw-r--r-- | Doc/lib/libframework.tex | 59 | ||||
| -rw-r--r-- | Doc/lib/libminiae.tex | 64 | ||||
| -rw-r--r-- | Doc/libctb.tex | 107 | ||||
| -rw-r--r-- | Doc/libframework.tex | 59 | ||||
| -rw-r--r-- | Doc/libmacconsole.tex | 1 | ||||
| -rw-r--r-- | Doc/libmacdnr.tex | 51 | ||||
| -rw-r--r-- | Doc/libmacfs.tex | 202 | ||||
| -rw-r--r-- | Doc/libmacic.tex | 21 | ||||
| -rw-r--r-- | Doc/libmacspeech.tex | 66 | ||||
| -rw-r--r-- | Doc/libmacui.tex | 33 | ||||
| -rw-r--r-- | Doc/libminiae.tex | 64 | ||||
| -rw-r--r-- | Doc/mac/libctb.tex | 107 | ||||
| -rw-r--r-- | Doc/mac/libframework.tex | 59 | ||||
| -rw-r--r-- | Doc/mac/libmacconsole.tex | 1 | ||||
| -rw-r--r-- | Doc/mac/libmacdnr.tex | 51 | ||||
| -rw-r--r-- | Doc/mac/libmacfs.tex | 202 | ||||
| -rw-r--r-- | Doc/mac/libmacic.tex | 21 | ||||
| -rw-r--r-- | Doc/mac/libmacspeech.tex | 66 | ||||
| -rw-r--r-- | Doc/mac/libmacui.tex | 33 | ||||
| -rw-r--r-- | Doc/mac/libminiae.tex | 64 |
20 files changed, 692 insertions, 639 deletions
diff --git a/Doc/lib/libframework.tex b/Doc/lib/libframework.tex index 85e3156..6e77870 100644 --- a/Doc/lib/libframework.tex +++ b/Doc/lib/libframework.tex @@ -2,7 +2,7 @@ \stmodindex{FrameWork} \label{module-FrameWork} -The \code{FrameWork} module contains classes that together provide a +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 @@ -11,18 +11,17 @@ 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 +The \module{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 or the examples for more details. -The \code{FrameWork} module defines the following functions: +The \module{FrameWork} module defines the following functions: -\setindexsubitem{(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 +description of the methods. The default \method{__init__()} routine creates an empty window dictionary and a menu bar with an apple menu. \end{funcdesc} @@ -88,23 +87,25 @@ Set the mouse cursor to a watch. Set the mouse cursor to an arrow. \end{funcdesc} -\subsection{Application objects} +\subsection{Application Objects} +\label{application-objects} + Application objects have the following methods, among others: \setindexsubitem{(Application method)} \begin{funcdesc}{makeusermenus}{} Override this method if you need menus in your application. Append the -menus to \code{self.menubar}. +menus to the attribute \member{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. +application. Alternatively, override the \method{do_about()} method +for more elaborate ``about'' messages. \end{funcdesc} -\begin{funcdesc}{mainloop}{\optional{mask, wait}} +\begin{funcdesc}{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 @@ -117,13 +118,14 @@ overridden. The default methods take care of dispatching events to windows and dialogs, handling drags and resizes, Apple Events, events for non-FrameWork windows, etc. -In general, all event handlers should return 1 if the event is fully -handled and 0 otherwise (because the front window was not a FrameWork +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 \code{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. +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{funcdesc} \begin{funcdesc}{asyncevents}{onoff} @@ -142,7 +144,8 @@ The old on/off value is returned. \end{funcdesc} \begin{funcdesc}{_quit}{} -Terminate the event \code{mainloop} at the next convenient moment. +Terminate the running \method{mainloop()} call at the next convenient +moment. \end{funcdesc} \begin{funcdesc}{do_char}{c, event} @@ -165,6 +168,7 @@ null-event is passed (so you can look at mouse position, etc). \end{funcdesc} \subsection{Window Objects} +\label{window-objects} Window objects have the following methods, among others: @@ -202,6 +206,7 @@ The window was activated (\code{activate==1}) or deactivated \end{funcdesc} \subsection{ControlsWindow Object} +\label{controlswindow-object} ControlsWindow objects have the following methods besides those of \code{Window} objects: @@ -214,40 +219,41 @@ user. Tracking and such has already been taken care of. \end{funcdesc} \subsection{ScrolledWindow Object} +\label{scrolledwindow-object} ScrolledWindow objects are ControlsWindow objects with the following extra methods: \setindexsubitem{(ScrolledWindow method)} -\begin{funcdesc}{scrollbars}{\optional{wantx, wanty}} +\begin{funcdesc}{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{funcdesc} \begin{funcdesc}{getscrollbarvalues}{} -You must supply this method. It should return a tuple \code{x, 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. +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{funcdesc} \begin{funcdesc}{updatescrollbars}{} Call this method when the document has changed. It will call -\code{getscrollbarvalues} and update the scrollbars. +\method{getscrollbarvalues()} and update the scrollbars. \end{funcdesc} \begin{funcdesc}{scrollbar_callback}{which, what, value} -Supplied by you and called after user interaction. \code{Which} will -be \code{'x'} or \code{'y'}, \code{what} will be \code{'-'}, +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'}, \code{value} will contain the new scrollbar position. +\code{'set'}, \var{value} will contain the new scrollbar position. \end{funcdesc} \begin{funcdesc}{scalebarvalues}{absmin, absmax, curmin, curmax} Auxiliary method to help you calculate values to return from -\code{getscrollbarvalues}. You pass document minimum and maximum value +\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{funcdesc} @@ -270,6 +276,7 @@ and has been handled. \end{funcdesc} \subsection{DialogWindow Objects} +\label{dialogwindow-objects} DialogWindow objects have the following methods besides those of \code{Window} objects: diff --git a/Doc/lib/libminiae.tex b/Doc/lib/libminiae.tex index d898551..a1cd6f4 100644 --- a/Doc/lib/libminiae.tex +++ b/Doc/lib/libminiae.tex @@ -1,61 +1,63 @@ -\section{Standard Module \sectcode{MiniAEFrame}} +\section{Standard Module \module{MiniAEFrame}} \stmodindex{MiniAEFrame} \label{module-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. +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 +\module{FrameWork}\refstmodindex{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: +The \module{MiniAEFrame} module defines the following classes: -\setindexsubitem{(in module MiniAEFrame)} -\begin{funcdesc}{AEServer}{} +\begin{classdesc}{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} +\class{MiniApplication} or +\class{FrameWork.Application}. Your \method{__init__()} method should +call the \method{__init__()} method for both classes. +\end{classdesc} -\begin{funcdesc}{MiniApplication}{} +\begin{classdesc}{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 +\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 \code{AEServer} but does not +Useful if your application wants to use \class{AEServer} but does not provide its own windows, etc. -\end{funcdesc} +\end{classdesc} -\subsection{AEServer Objects} -\setindexsubitem{(AEServer method)} +\subsection{AEServer Objects} +\label{aeserver-objects} -\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 +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{callback}{_object, **kwargs} +\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-char designator as name. Three extra keyword parameters are +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 -\code{aetools.packevent} and sent as reply. -\end{funcdesc} +\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-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. +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/libctb.tex b/Doc/libctb.tex index cd8c72c..de0636d 100644 --- a/Doc/libctb.tex +++ b/Doc/libctb.tex @@ -1,11 +1,13 @@ \section{Built-in Module \sectcode{ctb}} \label{module-ctb} \bimodindex{ctb} -\setindexsubitem{(in module ctb)} This module provides a partial interface to the Macintosh Communications Toolbox. Currently, only Connection Manager tools are supported. It may not be available in all Mac Python versions. +\index{Communications Toolbox, Macintosh} +\index{Macintosh Communications Toolbox} +\index{Connection Manager} \begin{datadesc}{error} The exception raised on errors. @@ -14,40 +16,41 @@ The exception raised on errors. \begin{datadesc}{cmData} \dataline{cmCntl} \dataline{cmAttn} -Flags for the \var{channel} argument of the \var{Read} and \var{Write} -methods. +Flags for the \var{channel} argument of the \method{Read()} and +\method{Write()} methods. \end{datadesc} \begin{datadesc}{cmFlagsEOM} -End-of-message flag for \var{Read} and \var{Write}. +End-of-message flag for \method{Read()} and \method{Write()}. \end{datadesc} \begin{datadesc}{choose*} -Values returned by \var{Choose}. +Values returned by \method{Choose()}. \end{datadesc} \begin{datadesc}{cmStatus*} -Bits in the status as returned by \var{Status}. +Bits in the status as returned by \method{Status()}. \end{datadesc} \begin{funcdesc}{available}{} -Return 1 if the communication toolbox is available, zero otherwise. +Return \code{1} if the Communication Toolbox is available, zero otherwise. \end{funcdesc} \begin{funcdesc}{CMNew}{name, sizes} Create a connection object using the connection tool named \var{name}. \var{sizes} is a 6-tuple given buffer sizes for data in, data out, control in, control out, attention in and attention out. -Alternatively, passing \code{None} will result in default buffer sizes. +Alternatively, passing \code{None} for \var{sizes} will result in +default buffer sizes. \end{funcdesc} \subsection{connection object} +\label{connection-object} + For all connection methods that take a \var{timeout} argument, a value of \code{-1} is indefinite, meaning that the command runs to completion. -\setindexsubitem{(connection object attribute)} - -\begin{datadesc}{callback} +\begin{memberdesc}[connection]{callback} If this member is set to a value other than \code{None} it should point to a function accepting a single argument (the connection object). This will make all connection object methods work @@ -57,94 +60,92 @@ completion. \emph{Note:} for reasons beyond my understanding the callback routine is currently never called. You are advised against using asynchronous calls for the time being. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(connection object method)} - -\begin{funcdesc}{Open}{timeout} +\begin{methoddesc}[connection]{Open}{timeout} Open an outgoing connection, waiting at most \var{timeout} seconds for the connection to be established. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Listen}{timeout} +\begin{methoddesc}[connection]{Listen}{timeout} Wait for an incoming connection. Stop waiting after \var{timeout} seconds. This call is only meaningful to some tools. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{accept}{yesno} +\begin{methoddesc}[connection]{accept}{yesno} Accept (when \var{yesno} is non-zero) or reject an incoming call after -\var{Listen} returned. -\end{funcdesc} +\method{Listen()} returned. +\end{methoddesc} -\begin{funcdesc}{Close}{timeout, now} +\begin{methoddesc}[connection]{Close}{timeout, now} Close a connection. When \var{now} is zero, the close is orderly (i.e.\ outstanding output is flushed, etc.)\ with a timeout of \var{timeout} seconds. When \var{now} is non-zero the close is immediate, discarding output. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Read}{len, chan, timeout} -Read \var{len} bytes, or until \var{timeout} seconds have passed, from -the channel \var{chan} (which is one of \var{cmData}, \var{cmCntl} or -\var{cmAttn}). Return a 2-tuple:\ the data read and the end-of-message -flag. -\end{funcdesc} +\begin{methoddesc}[connection]{Read}{len, chan, timeout} +Read \var{len} bytes, or until \var{timeout} seconds have passed, from +the channel \var{chan} (which is one of \constant{cmData}, +\constant{cmCntl} or \constant{cmAttn}). Return a 2-tuple:\ the data +read and the end-of-message flag, \constant{cmFlagsEOM}. +\end{methoddesc} -\begin{funcdesc}{Write}{buf, chan, timeout, eom} +\begin{methoddesc}[connection]{Write}{buf, chan, timeout, eom} Write \var{buf} to channel \var{chan}, aborting after \var{timeout} -seconds. When \var{eom} has the value \var{cmFlagsEOM} an +seconds. When \var{eom} has the value \constant{cmFlagsEOM}, an end-of-message indicator will be written after the data (if this concept has a meaning for this communication tool). The method returns the number of bytes written. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Status}{} +\begin{methoddesc}[connection]{Status}{} Return connection status as the 2-tuple \code{(\var{sizes}, \var{flags})}. \var{sizes} is a 6-tuple giving the actual buffer sizes used -(see \var{CMNew}), \var{flags} is a set of bits describing the state +(see \function{CMNew()}), \var{flags} is a set of bits describing the state of the connection. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetConfig}{} +\begin{methoddesc}[connection]{GetConfig}{} Return the configuration string of the communication tool. These configuration strings are tool-dependent, but usually easily parsed and modified. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetConfig}{str} +\begin{methoddesc}[connection]{SetConfig}{str} Set the configuration string for the tool. The strings are parsed left-to-right, with later values taking precedence. This means individual configuration parameters can be modified by simply appending something like \code{'baud 4800'} to the end of the string returned by -\var{GetConfig} and passing that to this method. The method returns +\method{GetConfig()} and passing that to this method. The method returns the number of characters actually parsed by the tool before it encountered an error (or completed successfully). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Choose}{} +\begin{methoddesc}[connection]{Choose}{} Present the user with a dialog to choose a communication tool and configure it. If there is an outstanding connection some choices (like selecting a different tool) may cause the connection to be -aborted. The return value (one of the \var{choose*} constants) will +aborted. The return value (one of the \constant{choose*} constants) will indicate this. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Idle}{} +\begin{methoddesc}[connection]{Idle}{} Give the tool a chance to use the processor. You should call this method regularly. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Abort}{} -Abort an outstanding asynchronous \var{Open} or \var{Listen}. -\end{funcdesc} +\begin{methoddesc}[connection]{Abort}{} +Abort an outstanding asynchronous \method{Open()} or \method{Listen()}. +\end{methoddesc} -\begin{funcdesc}{Reset}{} +\begin{methoddesc}[connection]{Reset}{} Reset a connection. Exact meaning depends on the tool. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Break}{length} +\begin{methoddesc}[connection]{Break}{length} Send a break. Whether this means anything, what it means and -interpretation of the \var{length} parameter depend on the tool in +interpretation of the \var{length} parameter depends on the tool in use. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libframework.tex b/Doc/libframework.tex index 85e3156..6e77870 100644 --- a/Doc/libframework.tex +++ b/Doc/libframework.tex @@ -2,7 +2,7 @@ \stmodindex{FrameWork} \label{module-FrameWork} -The \code{FrameWork} module contains classes that together provide a +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 @@ -11,18 +11,17 @@ 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 +The \module{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 or the examples for more details. -The \code{FrameWork} module defines the following functions: +The \module{FrameWork} module defines the following functions: -\setindexsubitem{(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 +description of the methods. The default \method{__init__()} routine creates an empty window dictionary and a menu bar with an apple menu. \end{funcdesc} @@ -88,23 +87,25 @@ Set the mouse cursor to a watch. Set the mouse cursor to an arrow. \end{funcdesc} -\subsection{Application objects} +\subsection{Application Objects} +\label{application-objects} + Application objects have the following methods, among others: \setindexsubitem{(Application method)} \begin{funcdesc}{makeusermenus}{} Override this method if you need menus in your application. Append the -menus to \code{self.menubar}. +menus to the attribute \member{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. +application. Alternatively, override the \method{do_about()} method +for more elaborate ``about'' messages. \end{funcdesc} -\begin{funcdesc}{mainloop}{\optional{mask, wait}} +\begin{funcdesc}{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 @@ -117,13 +118,14 @@ overridden. The default methods take care of dispatching events to windows and dialogs, handling drags and resizes, Apple Events, events for non-FrameWork windows, etc. -In general, all event handlers should return 1 if the event is fully -handled and 0 otherwise (because the front window was not a FrameWork +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 \code{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. +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{funcdesc} \begin{funcdesc}{asyncevents}{onoff} @@ -142,7 +144,8 @@ The old on/off value is returned. \end{funcdesc} \begin{funcdesc}{_quit}{} -Terminate the event \code{mainloop} at the next convenient moment. +Terminate the running \method{mainloop()} call at the next convenient +moment. \end{funcdesc} \begin{funcdesc}{do_char}{c, event} @@ -165,6 +168,7 @@ null-event is passed (so you can look at mouse position, etc). \end{funcdesc} \subsection{Window Objects} +\label{window-objects} Window objects have the following methods, among others: @@ -202,6 +206,7 @@ The window was activated (\code{activate==1}) or deactivated \end{funcdesc} \subsection{ControlsWindow Object} +\label{controlswindow-object} ControlsWindow objects have the following methods besides those of \code{Window} objects: @@ -214,40 +219,41 @@ user. Tracking and such has already been taken care of. \end{funcdesc} \subsection{ScrolledWindow Object} +\label{scrolledwindow-object} ScrolledWindow objects are ControlsWindow objects with the following extra methods: \setindexsubitem{(ScrolledWindow method)} -\begin{funcdesc}{scrollbars}{\optional{wantx, wanty}} +\begin{funcdesc}{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{funcdesc} \begin{funcdesc}{getscrollbarvalues}{} -You must supply this method. It should return a tuple \code{x, 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. +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{funcdesc} \begin{funcdesc}{updatescrollbars}{} Call this method when the document has changed. It will call -\code{getscrollbarvalues} and update the scrollbars. +\method{getscrollbarvalues()} and update the scrollbars. \end{funcdesc} \begin{funcdesc}{scrollbar_callback}{which, what, value} -Supplied by you and called after user interaction. \code{Which} will -be \code{'x'} or \code{'y'}, \code{what} will be \code{'-'}, +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'}, \code{value} will contain the new scrollbar position. +\code{'set'}, \var{value} will contain the new scrollbar position. \end{funcdesc} \begin{funcdesc}{scalebarvalues}{absmin, absmax, curmin, curmax} Auxiliary method to help you calculate values to return from -\code{getscrollbarvalues}. You pass document minimum and maximum value +\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{funcdesc} @@ -270,6 +276,7 @@ and has been handled. \end{funcdesc} \subsection{DialogWindow Objects} +\label{dialogwindow-objects} DialogWindow objects have the following methods besides those of \code{Window} objects: diff --git a/Doc/libmacconsole.tex b/Doc/libmacconsole.tex index 1916025..beda8e3 100644 --- a/Doc/libmacconsole.tex +++ b/Doc/libmacconsole.tex @@ -2,7 +2,6 @@ \label{module-macconsole} \bimodindex{macconsole} -\setindexsubitem{(in module macconsole)} This module is available on the Macintosh, provided Python has been built using the Think \C{} compiler. It provides an interface to the diff --git a/Doc/libmacdnr.tex b/Doc/libmacdnr.tex index decd953..1df4a58 100644 --- a/Doc/libmacdnr.tex +++ b/Doc/libmacdnr.tex @@ -4,8 +4,10 @@ This module provides an interface to the Macintosh Domain Name Resolver. It is usually used in conjunction with the \module{mactcp} -module, to map hostnames to IP-addresses. It may not be available in +module, to map hostnames to IP addresses. It may not be available in all Mac Python versions. +\index{Macintosh Domain Name Resolver} +\index{Domain Name Resolver, Macintosh} The \module{macdnr} module defines the following functions: @@ -46,11 +48,12 @@ variety. \begin{funcdesc}{MXInfo}{domain} Query the nameservers for a mail exchanger for \var{domain}. This is -the hostname of a host willing to accept SMTP mail for the given -domain. Returns a dnr result object of the ``mx'' variety. +the hostname of a host willing to accept SMTP\index{SMTP} mail for the +given domain. Returns a dnr result object of the ``mx'' variety. \end{funcdesc} \subsection{dnr result object} +\label{dnr-result-object} Since the DNR calls all execute asynchronously you do not get the results back immediately. Instead, you get a dnr result object. You @@ -64,50 +67,48 @@ The \member{rtnCode} and \member{cname} attributes are always available, the others depend on the type of query (address, hinfo or mx). -\setindexsubitem{(dnr result method)} % Add args, as in {arg1, arg2 \optional{, arg3}} -\begin{funcdesc}{wait}{} +\begin{methoddesc}[dnr result]{wait}{} Wait for the query to complete. -\end{funcdesc} +\end{methoddesc} % Add args, as in {arg1, arg2 \optional{, arg3}} -\begin{funcdesc}{isdone}{} +\begin{methoddesc}[dnr result]{isdone}{} Return \code{1} if the query is complete. -\end{funcdesc} +\end{methoddesc} -\setindexsubitem{(dnr result attribute)} -\begin{datadesc}{rtnCode} +\begin{memberdesc}[dnr result]{rtnCode} The error code returned by the query. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{cname} +\begin{memberdesc}[dnr result]{cname} The canonical name of the host that was queried. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ip0} -\dataline{ip1} -\dataline{ip2} -\dataline{ip3} +\begin{memberdesc}[dnr result]{ip0} +\memberline[dnr result]{ip1} +\memberline[dnr result]{ip2} +\memberline[dnr result]{ip3} At most four integer IP addresses for this host. Unused entries are zero. Valid only for address queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{cpuType} -\dataline{osType} +\begin{memberdesc}[dnr result]{cpuType} +\memberline[dnr result]{osType} Textual strings giving the machine type an OS name. Valid for ``hinfo'' queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{exchange} +\begin{memberdesc}[dnr result]{exchange} The name of a mail-exchanger host. Valid for ``mx'' queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{preference} +\begin{memberdesc}[dnr result]{preference} The preference of this mx record. Not too useful, since the Macintosh will only return a single mx record. Valid for ``mx'' queries only. -\end{datadesc} +\end{memberdesc} The simplest way to use the module to convert names to dotted-decimal strings, without worrying about idle time, etc: diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex index 5373d31..6bb4bbf 100644 --- a/Doc/libmacfs.tex +++ b/Doc/libmacfs.tex @@ -4,75 +4,80 @@ This module provides access to Macintosh FSSpec handling, the Alias -Manager, finder aliases and the Standard File package. +Manager, \program{finder} aliases and the Standard File package. +\index{Macintosh Alias Manager} +\index{Alias Manager, Macintosh} +\index{Standard File} Whenever a function or method expects a \var{file} argument, this argument can be one of three things:\ (1) a full or partial Macintosh -pathname, (2) an FSSpec object or (3) a 3-tuple \code{(\var{wdRefNum}, -\var{parID}, \var{name})} as described in \emph{Inside Macintosh -VI}\@. A description of aliases and the standard file package can also -be found there. +pathname, (2) an \pytype{FSSpec} object or (3) a 3-tuple \code{(\var{wdRefNum}, +\var{parID}, \var{name})} as described in \emph{Inside +Macintosh:\ Files}\@. A description of aliases and the Standard File +package can also be found there. \begin{funcdesc}{FSSpec}{file} -Create an FSSpec object for the specified file. +Create an \pytype{FSSpec} object for the specified file. \end{funcdesc} \begin{funcdesc}{RawFSSpec}{data} -Create an FSSpec object given the raw data for the C structure for the -FSSpec as a string. This is mainly useful if you have obtained an -FSSpec structure over a network. +Create an \pytype{FSSpec} object given the raw data for the \C{} +structure for the \pytype{FSSpec} as a string. This is mainly useful +if you have obtained an \pytype{FSSpec} structure over a network. \end{funcdesc} \begin{funcdesc}{RawAlias}{data} -Create an Alias object given the raw data for the C structure for the -alias as a string. This is mainly useful if you have obtained an -FSSpec structure over a network. +Create an \pytype{Alias} object given the raw data for the \C{} +structure for the alias as a string. This is mainly useful if you +have obtained an \pytype{FSSpec} structure over a network. \end{funcdesc} \begin{funcdesc}{FInfo}{} -Create a zero-filled FInfo object. +Create a zero-filled \pytype{FInfo} object. \end{funcdesc} \begin{funcdesc}{ResolveAliasFile}{file} -Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, \var{isfolder}, -\var{aliased})} where \var{fsspec} is the resulting FSSpec object, -\var{isfolder} is true if \var{fsspec} points to a folder and -\var{aliased} is true if the file was an alias in the first place -(otherwise the FSSpec object for the file itself is returned). +Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, +\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting +\pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points +to a folder and \var{aliased} is true if the file was an alias in the +first place (otherwise the \pytype{FSSpec} object for the file itself +is returned). \end{funcdesc} \begin{funcdesc}{StandardGetFile}{\optional{type, ...}} Present the user with a standard ``open input file'' -dialog. Optionally, you can pass up to four 4-char file types to limit -the files the user can choose from. The function returns an FSSpec +dialog. Optionally, you can pass up to four 4-character file types to limit +the files the user can choose from. The function returns an \pytype{FSSpec} object and a flag indicating that the user completed the dialog without cancelling. \end{funcdesc} \begin{funcdesc}{PromptGetFile}{prompt\optional{, type, ...}} -Similar to \var{StandardGetFile} but allows you to specify a prompt. +Similar to \function{StandardGetFile()} but allows you to specify a +prompt. \end{funcdesc} \begin{funcdesc}{StandardPutFile}{prompt, \optional{default}} Present the user with a standard ``open output file'' dialog. \var{prompt} is the prompt string, and the optional \var{default} argument initializes the output file name. The function -returns an FSSpec object and a flag indicating that the user completed -the dialog without cancelling. +returns an \pytype{FSSpec} object and a flag indicating that the user +completed the dialog without cancelling. \end{funcdesc} \begin{funcdesc}{GetDirectory}{\optional{prompt}} Present the user with a non-standard ``select a directory'' dialog. \var{prompt} is the prompt string, and the optional. -Return an FSSpec object and a success-indicator. +Return an \pytype{FSSpec} object and a success-indicator. \end{funcdesc} \begin{funcdesc}{SetFolder}{\optional{fsspec}} Set the folder that is initially presented to the user when one of -the file selection dialogs is presented. \var{Fsspec} should point to +the file selection dialogs is presented. \var{fsspec} should point to a file in the folder, not the folder itself (the file need not exist, though). If no argument is passed the folder will be set to the -current directory, i.e. what \code{os.getcwd()} returns. +current directory, i.e. what \function{os.getcwd()} returns. Note that starting with system 7.5 the user can change Standard File behaviour with the ``general controls'' controlpanel, thereby making @@ -81,16 +86,16 @@ this call inoperative. \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, \var{which} is the 4-char string specifying which folder to +the trash or the Preferences folder. \var{where} is the disk to +search, \var{which} is the 4-character 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. +does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple. \end{funcdesc} \begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname} -Return a minimal alias record object that points to the given file, which +Return a minimal \pytype{alias} object that points to the given file, which must be specified as a full pathname. This is the only way to create an -alias record pointing to a non-existing file. +\pytype{Alias} pointing to a non-existing file. The constants for \var{where} and \var{which} can be obtained from the standard module \var{MACFS}. @@ -98,122 +103,123 @@ standard module \var{MACFS}. \begin{funcdesc}{FindApplication}{creator} Locate the application with 4-char creator code \var{creator}. The -function returns an FSSpec object pointing to the application. +function returns an \pytype{FSSpec} object pointing to the application. \end{funcdesc} \subsection{FSSpec objects} +\label{fsspec-objects} -\setindexsubitem{(FSSpec object attribute)} -\begin{datadesc}{data} +\begin{memberdesc}[FSSpec]{data} The raw data from the FSSpec object, suitable for passing to other applications, for instance. -\end{datadesc} +\end{memberdesc} \setindexsubitem{(FSSpec object method)} -\begin{funcdesc}{as_pathname}{} -Return the full pathname of the file described by the FSSpec object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{as_pathname}{} +Return the full pathname of the file described by the \pytype{FSSpec} +object. +\end{methoddesc} -\begin{funcdesc}{as_tuple}{} -Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of the file described -by the FSSpec object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{as_tuple}{} +Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of +the file described by the \pytype{FSSpec} object. +\end{methoddesc} -\begin{funcdesc}{NewAlias}{\optional{file}} +\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}} Create an Alias object pointing to the file described by this FSSpec. If the optional \var{file} parameter is present the alias will be relative to that file, otherwise it will be absolute. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{NewAliasMinimal}{} +\begin{methoddesc}[FSSpec]{NewAliasMinimal}{} Create a minimal alias pointing to this file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetCreatorType}{} -Return the 4-char creator and type of the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{GetCreatorType}{} +Return the 4-character creator and type of the file. +\end{methoddesc} -\begin{funcdesc}{SetCreatorType}{creator, type} -Set the 4-char creator and type of the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type} +Set the 4-character creator and type of the file. +\end{methoddesc} -\begin{funcdesc}{GetFInfo}{} -Return a FInfo object describing the finder info for the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{GetFInfo}{} +Return a \pytype{FInfo} object describing the finder info for the file. +\end{methoddesc} -\begin{funcdesc}{SetFInfo}{finfo} -Set the finder info for the file to the values specified in the -\var{finfo} object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{SetFInfo}{finfo} +Set the finder info for the file to the values given as \var{finfo} +(an \pytype{FInfo} object). +\end{methoddesc} -\begin{funcdesc}{GetDates}{} +\begin{methoddesc}[FSSpec]{GetDates}{} Return a tuple with three floating point values representing the creation date, modification date and backup date of the file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetDates}{crdate, moddate, backupdate} +\begin{methoddesc}[FSSpec]{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} +\end{methoddesc} + -\subsection{alias objects} +\subsection{Alias Objects} +\label{alias-objects} -\setindexsubitem{(alias object attribute)} -\begin{datadesc}{data} +\begin{memberdesc}[Alias]{data} The raw data for the Alias record, suitable for storing in a resource or transmitting to other programs. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(alias object method)} -\begin{funcdesc}{Resolve}{\optional{file}} +\begin{methoddesc}[Alias]{Resolve}{\optional{file}} Resolve the alias. If the alias was created as a relative alias you should pass the file relative to which it is. Return the FSSpec for -the file pointed to and a flag indicating whether the alias object +the file pointed to and a flag indicating whether the \pytype{Alias} object itself was modified during the search process. If the file does not exist but the path leading up to it does exist a valid fsspec is returned. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetInfo}{num} -An interface to the C routine \code{GetAliasInfo()}. -\end{funcdesc} +\begin{methoddesc}[Alias]{GetInfo}{num} +An interface to the \C{} routine \cfunction{GetAliasInfo()}. +\end{methoddesc} -\begin{funcdesc}{Update}{file, \optional{file2}} +\begin{methoddesc}[Alias]{Update}{file, \optional{file2}} Update the alias to point to the \var{file} given. If \var{file2} is present a relative alias will be created. -\end{funcdesc} +\end{methoddesc} -Note that it is currently not possible to directly manipulate a resource -as an alias object. Hence, after calling \var{Update} or after -\var{Resolve} indicates that the alias has changed the Python program -is responsible for getting the \var{data} from the alias object and -modifying the resource. +Note that it is currently not possible to directly manipulate a +resource as an \pytype{Alias} object. Hence, after calling +\method{Update()} or after \method{Resolve()} indicates that the alias +has changed the Python program is responsible for getting the +\var{data} from the \pytype{Alias} object and modifying the resource. -\subsection{FInfo objects} +\subsection{FInfo Objects} +\label{finfo-objects} -See Inside Mac for a complete description of what the various fields -mean. +See \emph{Inside Macintosh: Files} for a complete description of what +the various fields mean. -\setindexsubitem{(FInfo object attribute)} -\begin{datadesc}{Creator} -The 4-char creator code of the file. -\end{datadesc} +\begin{memberdesc}[FInfo]{Creator} +The 4-character creator code of the file. +\end{memberdesc} -\begin{datadesc}{Type} -The 4-char type code of the file. -\end{datadesc} +\begin{memberdesc}[FInfo]{Type} +The 4-character type code of the file. +\end{memberdesc} -\begin{datadesc}{Flags} +\begin{memberdesc}[FInfo]{Flags} 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} +\var{Flags} are defined in standard module \module{MACFS}. +\end{memberdesc} -\begin{datadesc}{Location} +\begin{memberdesc}[FInfo]{Location} A Point giving the position of the file's icon in its folder. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{Fldr} +\begin{memberdesc}[FInfo]{Fldr} The folder the file is in (as an integer). -\end{datadesc} +\end{memberdesc} diff --git a/Doc/libmacic.tex b/Doc/libmacic.tex index 734ac11..7cd0557 100644 --- a/Doc/libmacic.tex +++ b/Doc/libmacic.tex @@ -30,7 +30,7 @@ Exception raised on errors in the \module{ic} module. The \module{ic} module defines the following functions: \begin{funcdesc}{IC}{\optional{signature\optional{, ic}}} -Create an internet config object. The signature is a 4-char creator +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 @@ -62,7 +62,7 @@ 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 -\var{data} attribute. Objects of this type are also acceptable values +\member{data} attribute. Objects of this type are also acceptable values for assignment. Besides the dictionary interface IC objects have the following methods: @@ -82,21 +82,22 @@ 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 textfield you can pass the whole textfield and the click-position in \var{start} and this routine will return the whole URL in which the -user clicked. \var{Hint} is again an optional scheme used to complete -incomplete URLs. +user clicked. As above, \var{hint} is an optional scheme used to +complete incomplete URLs. \end{funcdesc} \begin{funcdesc}{mapfile}{file} Return the mapping entry for the given \var{file}, which can be passed -as either a filename or an \code{macfs.FSSpec} object, and which need -not exist. +as either a filename or an \function{macfs.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}\code{)}, where \var{version} is the entry version -number, \var{type} is the 4-char filetype, \var{creator} is the 4-char -creator type, \var{postcreator} is the 4-char creator code of an +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 @@ -107,7 +108,7 @@ file and \var{entryname} is the name of this entry. \end{funcdesc} \begin{funcdesc}{maptypecreator}{type, creator\optional{, filename}} -Return the mapping entry for files with given 4-char \var{type} and +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). @@ -117,7 +118,7 @@ The mapping entry is returned in the same format as for \var{mapfile}. \begin{funcdesc}{settypecreator}{file} Given an existing \var{file}, specified either as a filename or as an -\code{macfs.FSSpec} record, set its creator and type correctly based +\function{macfs.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{funcdesc} diff --git a/Doc/libmacspeech.tex b/Doc/libmacspeech.tex index 8c74268..14a9c61 100644 --- a/Doc/libmacspeech.tex +++ b/Doc/libmacspeech.tex @@ -1,19 +1,21 @@ -\section{Built-in Module \sectcode{macspeech}} +\section{Built-in Module \module{macspeech}} \label{module-macspeech} \bimodindex{macspeech} -\setindexsubitem{(in module macspeech)} This module provides an interface to the Macintosh Speech Manager, +\index{Macintosh Speech Manager} +\index{Speech Manager, Macintosh} allowing you to let the Macintosh utter phrases. You need a version of -the speech manager extension (version 1 and 2 have been tested) in -your \code{Extensions} folder for this to work. The module does not +the Speech Manager extension (version 1 and 2 have been tested) in +your \file{Extensions} folder for this to work. The module does not provide full access to all features of the Speech Manager yet. It may not be available in all Mac Python versions. \begin{funcdesc}{Available}{} Test availability of the Speech Manager extension (and, on the -PowerPC, the Speech Manager shared library). Return 0 or 1. +PowerPC, the Speech Manager shared library). Return \code{0} or +\code{1}. \end{funcdesc} \begin{funcdesc}{Version}{} @@ -23,7 +25,7 @@ Return the (integer) version number of the Speech Manager. \begin{funcdesc}{SpeakString}{str} Utter the string \var{str} using the default voice, asynchronously. This aborts any speech that may still be active from -prior \code{SpeakString} invocations. +prior \function{SpeakString()} invocations. \end{funcdesc} \begin{funcdesc}{Busy}{} @@ -35,53 +37,57 @@ Return the number of different voices available. \end{funcdesc} \begin{funcdesc}{GetIndVoice}{num} -Return a voice object for voice number \var{num}. +Return a \pytype{Voice} object for voice number \var{num}. \end{funcdesc} -\subsection{voice objects} +\subsection{Voice Objects} +\label{voice-objects} + Voice objects contain the description of a voice. It is currently not yet possible to access the parameters of a voice. \setindexsubitem{(voice object method)} -\begin{funcdesc}{GetGender}{} -Return the gender of the voice: 0 for male, 1 for female and -1 for neuter. -\end{funcdesc} +\begin{methoddesc}[Voice]{GetGender}{} +Return the gender of the voice: \code{0} for male, \code{1} for female +and \code{-1} for neuter. +\end{methoddesc} -\begin{funcdesc}{NewChannel}{} -Return a new speech channel object using this voice. -\end{funcdesc} +\begin{methoddesc}[Voice]{NewChannel}{} +Return a new Speech Channel object using this voice. +\end{methoddesc} -\subsection{speech channel objects} -A speech channel object allows you to speak strings with slightly more -control than \code{SpeakString()}, and allows you to use multiple +\subsection{Speech Channel Objects} +\label{speech-channel-objects} + +A Speech Channel object allows you to speak strings with slightly more +control than \function{SpeakString()}, and allows you to use multiple speakers at the same time. Please note that channel pitch and rate are interrelated in some way, so that to make your Macintosh sing you will have to adjust both. -\setindexsubitem{(speech channel object method)} -\begin{funcdesc}{SpeakText}{str} +\begin{methoddesc}[Speech Channel]{SpeakText}{str} Start uttering the given string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Stop}{} +\begin{methoddesc}[Speech Channel]{Stop}{} Stop babbling. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetPitch}{} +\begin{methoddesc}[Speech Channel]{GetPitch}{} Return the current pitch of the channel, as a floating-point number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetPitch}{pitch} +\begin{methoddesc}[Speech Channel]{SetPitch}{pitch} Set the pitch of the channel. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetRate}{} +\begin{methoddesc}[Speech Channel]{GetRate}{} Get the speech rate (utterances per minute) of the channel as a floating point number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetRate}{rate} +\begin{methoddesc}[Speech Channel]{SetRate}{rate} Set the speech rate of the channel. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex index bf8a30f..7f5237b 100644 --- a/Doc/libmacui.tex +++ b/Doc/libmacui.tex @@ -1,16 +1,15 @@ -\section{Standard Module \sectcode{EasyDialogs}} +\section{Standard Module \module{EasyDialogs}} \label{module-EasyDialogs} \stmodindex{EasyDialogs} -The \code{EasyDialogs} module contains some simple dialogs for -the Macintosh, modelled after the \code{stdwin} dialogs with similar +The \module{EasyDialogs} module contains some simple dialogs for +the Macintosh, modelled after the \module{stdwin} dialogs with similar names. All routines have an optional parameter \var{id} with which you can override the DLOG resource used for the dialog, as long as the item numbers correspond. See the source for details. + +The \module{EasyDialogs} module defines the following functions: -The \code{EasyDialogs} module defines the following functions: - -\setindexsubitem{(in module EasyDialogs)} \begin{funcdesc}{Message}{str} A modal dialog with the message text \var{str}, which should be at @@ -19,11 +18,11 @@ 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} +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. +long. \function{AskString()} returns the string entered or \code{None} +in case the user cancelled. \end{funcdesc} \begin{funcdesc}{AskYesNoCancel}{question\optional{, default}} @@ -34,19 +33,19 @@ hitting return is \code{0}. This can be changed with the optional \var{default} argument. \end{funcdesc} -\begin{funcdesc}{ProgressBar}{\optional{label, maxval}} -Display a modeless progress dialog with a thermometer bar. \var{Label} -is the textstring displayed (default ``Working...''), \var{maxval} is -the value at which progress is complete (default 100). The returned -object has one method, \code{set(value)}, which sets the value of the -progress bar. The bar remains visible until the object returned is -discarded. +\begin{funcdesc}{ProgressBar}{\optional{label\optional{, maxval}}} +Display a modeless progress dialog with a thermometer bar. \var{label} +is the text string displayed (default ``Working...''), \var{maxval} is +the value at which progress is complete (default \code{100}). The +returned object has one method, \code{set(\var{value})}, which sets +the value of the progress bar. The bar remains visible until the +object returned is discarded. The progress bar has a ``cancel'' button, but it is currently non-functional. \end{funcdesc} -Note that \code{EasyDialogs} does not currently use the notification +Note that \module{EasyDialogs} does not currently use the notification manager. This means that displaying dialogs while the program is in the background will lead to unexpected results and possibly crashes. Also, all dialogs are modeless and hence expect to be at the diff --git a/Doc/libminiae.tex b/Doc/libminiae.tex index d898551..a1cd6f4 100644 --- a/Doc/libminiae.tex +++ b/Doc/libminiae.tex @@ -1,61 +1,63 @@ -\section{Standard Module \sectcode{MiniAEFrame}} +\section{Standard Module \module{MiniAEFrame}} \stmodindex{MiniAEFrame} \label{module-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. +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 +\module{FrameWork}\refstmodindex{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: +The \module{MiniAEFrame} module defines the following classes: -\setindexsubitem{(in module MiniAEFrame)} -\begin{funcdesc}{AEServer}{} +\begin{classdesc}{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} +\class{MiniApplication} or +\class{FrameWork.Application}. Your \method{__init__()} method should +call the \method{__init__()} method for both classes. +\end{classdesc} -\begin{funcdesc}{MiniApplication}{} +\begin{classdesc}{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 +\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 \code{AEServer} but does not +Useful if your application wants to use \class{AEServer} but does not provide its own windows, etc. -\end{funcdesc} +\end{classdesc} -\subsection{AEServer Objects} -\setindexsubitem{(AEServer method)} +\subsection{AEServer Objects} +\label{aeserver-objects} -\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 +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{callback}{_object, **kwargs} +\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-char designator as name. Three extra keyword parameters are +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 -\code{aetools.packevent} and sent as reply. -\end{funcdesc} +\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-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. +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/libctb.tex b/Doc/mac/libctb.tex index cd8c72c..de0636d 100644 --- a/Doc/mac/libctb.tex +++ b/Doc/mac/libctb.tex @@ -1,11 +1,13 @@ \section{Built-in Module \sectcode{ctb}} \label{module-ctb} \bimodindex{ctb} -\setindexsubitem{(in module ctb)} This module provides a partial interface to the Macintosh Communications Toolbox. Currently, only Connection Manager tools are supported. It may not be available in all Mac Python versions. +\index{Communications Toolbox, Macintosh} +\index{Macintosh Communications Toolbox} +\index{Connection Manager} \begin{datadesc}{error} The exception raised on errors. @@ -14,40 +16,41 @@ The exception raised on errors. \begin{datadesc}{cmData} \dataline{cmCntl} \dataline{cmAttn} -Flags for the \var{channel} argument of the \var{Read} and \var{Write} -methods. +Flags for the \var{channel} argument of the \method{Read()} and +\method{Write()} methods. \end{datadesc} \begin{datadesc}{cmFlagsEOM} -End-of-message flag for \var{Read} and \var{Write}. +End-of-message flag for \method{Read()} and \method{Write()}. \end{datadesc} \begin{datadesc}{choose*} -Values returned by \var{Choose}. +Values returned by \method{Choose()}. \end{datadesc} \begin{datadesc}{cmStatus*} -Bits in the status as returned by \var{Status}. +Bits in the status as returned by \method{Status()}. \end{datadesc} \begin{funcdesc}{available}{} -Return 1 if the communication toolbox is available, zero otherwise. +Return \code{1} if the Communication Toolbox is available, zero otherwise. \end{funcdesc} \begin{funcdesc}{CMNew}{name, sizes} Create a connection object using the connection tool named \var{name}. \var{sizes} is a 6-tuple given buffer sizes for data in, data out, control in, control out, attention in and attention out. -Alternatively, passing \code{None} will result in default buffer sizes. +Alternatively, passing \code{None} for \var{sizes} will result in +default buffer sizes. \end{funcdesc} \subsection{connection object} +\label{connection-object} + For all connection methods that take a \var{timeout} argument, a value of \code{-1} is indefinite, meaning that the command runs to completion. -\setindexsubitem{(connection object attribute)} - -\begin{datadesc}{callback} +\begin{memberdesc}[connection]{callback} If this member is set to a value other than \code{None} it should point to a function accepting a single argument (the connection object). This will make all connection object methods work @@ -57,94 +60,92 @@ completion. \emph{Note:} for reasons beyond my understanding the callback routine is currently never called. You are advised against using asynchronous calls for the time being. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(connection object method)} - -\begin{funcdesc}{Open}{timeout} +\begin{methoddesc}[connection]{Open}{timeout} Open an outgoing connection, waiting at most \var{timeout} seconds for the connection to be established. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Listen}{timeout} +\begin{methoddesc}[connection]{Listen}{timeout} Wait for an incoming connection. Stop waiting after \var{timeout} seconds. This call is only meaningful to some tools. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{accept}{yesno} +\begin{methoddesc}[connection]{accept}{yesno} Accept (when \var{yesno} is non-zero) or reject an incoming call after -\var{Listen} returned. -\end{funcdesc} +\method{Listen()} returned. +\end{methoddesc} -\begin{funcdesc}{Close}{timeout, now} +\begin{methoddesc}[connection]{Close}{timeout, now} Close a connection. When \var{now} is zero, the close is orderly (i.e.\ outstanding output is flushed, etc.)\ with a timeout of \var{timeout} seconds. When \var{now} is non-zero the close is immediate, discarding output. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Read}{len, chan, timeout} -Read \var{len} bytes, or until \var{timeout} seconds have passed, from -the channel \var{chan} (which is one of \var{cmData}, \var{cmCntl} or -\var{cmAttn}). Return a 2-tuple:\ the data read and the end-of-message -flag. -\end{funcdesc} +\begin{methoddesc}[connection]{Read}{len, chan, timeout} +Read \var{len} bytes, or until \var{timeout} seconds have passed, from +the channel \var{chan} (which is one of \constant{cmData}, +\constant{cmCntl} or \constant{cmAttn}). Return a 2-tuple:\ the data +read and the end-of-message flag, \constant{cmFlagsEOM}. +\end{methoddesc} -\begin{funcdesc}{Write}{buf, chan, timeout, eom} +\begin{methoddesc}[connection]{Write}{buf, chan, timeout, eom} Write \var{buf} to channel \var{chan}, aborting after \var{timeout} -seconds. When \var{eom} has the value \var{cmFlagsEOM} an +seconds. When \var{eom} has the value \constant{cmFlagsEOM}, an end-of-message indicator will be written after the data (if this concept has a meaning for this communication tool). The method returns the number of bytes written. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Status}{} +\begin{methoddesc}[connection]{Status}{} Return connection status as the 2-tuple \code{(\var{sizes}, \var{flags})}. \var{sizes} is a 6-tuple giving the actual buffer sizes used -(see \var{CMNew}), \var{flags} is a set of bits describing the state +(see \function{CMNew()}), \var{flags} is a set of bits describing the state of the connection. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetConfig}{} +\begin{methoddesc}[connection]{GetConfig}{} Return the configuration string of the communication tool. These configuration strings are tool-dependent, but usually easily parsed and modified. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetConfig}{str} +\begin{methoddesc}[connection]{SetConfig}{str} Set the configuration string for the tool. The strings are parsed left-to-right, with later values taking precedence. This means individual configuration parameters can be modified by simply appending something like \code{'baud 4800'} to the end of the string returned by -\var{GetConfig} and passing that to this method. The method returns +\method{GetConfig()} and passing that to this method. The method returns the number of characters actually parsed by the tool before it encountered an error (or completed successfully). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Choose}{} +\begin{methoddesc}[connection]{Choose}{} Present the user with a dialog to choose a communication tool and configure it. If there is an outstanding connection some choices (like selecting a different tool) may cause the connection to be -aborted. The return value (one of the \var{choose*} constants) will +aborted. The return value (one of the \constant{choose*} constants) will indicate this. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Idle}{} +\begin{methoddesc}[connection]{Idle}{} Give the tool a chance to use the processor. You should call this method regularly. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Abort}{} -Abort an outstanding asynchronous \var{Open} or \var{Listen}. -\end{funcdesc} +\begin{methoddesc}[connection]{Abort}{} +Abort an outstanding asynchronous \method{Open()} or \method{Listen()}. +\end{methoddesc} -\begin{funcdesc}{Reset}{} +\begin{methoddesc}[connection]{Reset}{} Reset a connection. Exact meaning depends on the tool. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Break}{length} +\begin{methoddesc}[connection]{Break}{length} Send a break. Whether this means anything, what it means and -interpretation of the \var{length} parameter depend on the tool in +interpretation of the \var{length} parameter depends on the tool in use. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/mac/libframework.tex b/Doc/mac/libframework.tex index 85e3156..6e77870 100644 --- a/Doc/mac/libframework.tex +++ b/Doc/mac/libframework.tex @@ -2,7 +2,7 @@ \stmodindex{FrameWork} \label{module-FrameWork} -The \code{FrameWork} module contains classes that together provide a +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 @@ -11,18 +11,17 @@ 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 +The \module{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 or the examples for more details. -The \code{FrameWork} module defines the following functions: +The \module{FrameWork} module defines the following functions: -\setindexsubitem{(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 +description of the methods. The default \method{__init__()} routine creates an empty window dictionary and a menu bar with an apple menu. \end{funcdesc} @@ -88,23 +87,25 @@ Set the mouse cursor to a watch. Set the mouse cursor to an arrow. \end{funcdesc} -\subsection{Application objects} +\subsection{Application Objects} +\label{application-objects} + Application objects have the following methods, among others: \setindexsubitem{(Application method)} \begin{funcdesc}{makeusermenus}{} Override this method if you need menus in your application. Append the -menus to \code{self.menubar}. +menus to the attribute \member{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. +application. Alternatively, override the \method{do_about()} method +for more elaborate ``about'' messages. \end{funcdesc} -\begin{funcdesc}{mainloop}{\optional{mask, wait}} +\begin{funcdesc}{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 @@ -117,13 +118,14 @@ overridden. The default methods take care of dispatching events to windows and dialogs, handling drags and resizes, Apple Events, events for non-FrameWork windows, etc. -In general, all event handlers should return 1 if the event is fully -handled and 0 otherwise (because the front window was not a FrameWork +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 \code{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. +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{funcdesc} \begin{funcdesc}{asyncevents}{onoff} @@ -142,7 +144,8 @@ The old on/off value is returned. \end{funcdesc} \begin{funcdesc}{_quit}{} -Terminate the event \code{mainloop} at the next convenient moment. +Terminate the running \method{mainloop()} call at the next convenient +moment. \end{funcdesc} \begin{funcdesc}{do_char}{c, event} @@ -165,6 +168,7 @@ null-event is passed (so you can look at mouse position, etc). \end{funcdesc} \subsection{Window Objects} +\label{window-objects} Window objects have the following methods, among others: @@ -202,6 +206,7 @@ The window was activated (\code{activate==1}) or deactivated \end{funcdesc} \subsection{ControlsWindow Object} +\label{controlswindow-object} ControlsWindow objects have the following methods besides those of \code{Window} objects: @@ -214,40 +219,41 @@ user. Tracking and such has already been taken care of. \end{funcdesc} \subsection{ScrolledWindow Object} +\label{scrolledwindow-object} ScrolledWindow objects are ControlsWindow objects with the following extra methods: \setindexsubitem{(ScrolledWindow method)} -\begin{funcdesc}{scrollbars}{\optional{wantx, wanty}} +\begin{funcdesc}{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{funcdesc} \begin{funcdesc}{getscrollbarvalues}{} -You must supply this method. It should return a tuple \code{x, 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. +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{funcdesc} \begin{funcdesc}{updatescrollbars}{} Call this method when the document has changed. It will call -\code{getscrollbarvalues} and update the scrollbars. +\method{getscrollbarvalues()} and update the scrollbars. \end{funcdesc} \begin{funcdesc}{scrollbar_callback}{which, what, value} -Supplied by you and called after user interaction. \code{Which} will -be \code{'x'} or \code{'y'}, \code{what} will be \code{'-'}, +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'}, \code{value} will contain the new scrollbar position. +\code{'set'}, \var{value} will contain the new scrollbar position. \end{funcdesc} \begin{funcdesc}{scalebarvalues}{absmin, absmax, curmin, curmax} Auxiliary method to help you calculate values to return from -\code{getscrollbarvalues}. You pass document minimum and maximum value +\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{funcdesc} @@ -270,6 +276,7 @@ and has been handled. \end{funcdesc} \subsection{DialogWindow Objects} +\label{dialogwindow-objects} DialogWindow objects have the following methods besides those of \code{Window} objects: diff --git a/Doc/mac/libmacconsole.tex b/Doc/mac/libmacconsole.tex index 1916025..beda8e3 100644 --- a/Doc/mac/libmacconsole.tex +++ b/Doc/mac/libmacconsole.tex @@ -2,7 +2,6 @@ \label{module-macconsole} \bimodindex{macconsole} -\setindexsubitem{(in module macconsole)} This module is available on the Macintosh, provided Python has been built using the Think \C{} compiler. It provides an interface to the diff --git a/Doc/mac/libmacdnr.tex b/Doc/mac/libmacdnr.tex index decd953..1df4a58 100644 --- a/Doc/mac/libmacdnr.tex +++ b/Doc/mac/libmacdnr.tex @@ -4,8 +4,10 @@ This module provides an interface to the Macintosh Domain Name Resolver. It is usually used in conjunction with the \module{mactcp} -module, to map hostnames to IP-addresses. It may not be available in +module, to map hostnames to IP addresses. It may not be available in all Mac Python versions. +\index{Macintosh Domain Name Resolver} +\index{Domain Name Resolver, Macintosh} The \module{macdnr} module defines the following functions: @@ -46,11 +48,12 @@ variety. \begin{funcdesc}{MXInfo}{domain} Query the nameservers for a mail exchanger for \var{domain}. This is -the hostname of a host willing to accept SMTP mail for the given -domain. Returns a dnr result object of the ``mx'' variety. +the hostname of a host willing to accept SMTP\index{SMTP} mail for the +given domain. Returns a dnr result object of the ``mx'' variety. \end{funcdesc} \subsection{dnr result object} +\label{dnr-result-object} Since the DNR calls all execute asynchronously you do not get the results back immediately. Instead, you get a dnr result object. You @@ -64,50 +67,48 @@ The \member{rtnCode} and \member{cname} attributes are always available, the others depend on the type of query (address, hinfo or mx). -\setindexsubitem{(dnr result method)} % Add args, as in {arg1, arg2 \optional{, arg3}} -\begin{funcdesc}{wait}{} +\begin{methoddesc}[dnr result]{wait}{} Wait for the query to complete. -\end{funcdesc} +\end{methoddesc} % Add args, as in {arg1, arg2 \optional{, arg3}} -\begin{funcdesc}{isdone}{} +\begin{methoddesc}[dnr result]{isdone}{} Return \code{1} if the query is complete. -\end{funcdesc} +\end{methoddesc} -\setindexsubitem{(dnr result attribute)} -\begin{datadesc}{rtnCode} +\begin{memberdesc}[dnr result]{rtnCode} The error code returned by the query. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{cname} +\begin{memberdesc}[dnr result]{cname} The canonical name of the host that was queried. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{ip0} -\dataline{ip1} -\dataline{ip2} -\dataline{ip3} +\begin{memberdesc}[dnr result]{ip0} +\memberline[dnr result]{ip1} +\memberline[dnr result]{ip2} +\memberline[dnr result]{ip3} At most four integer IP addresses for this host. Unused entries are zero. Valid only for address queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{cpuType} -\dataline{osType} +\begin{memberdesc}[dnr result]{cpuType} +\memberline[dnr result]{osType} Textual strings giving the machine type an OS name. Valid for ``hinfo'' queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{exchange} +\begin{memberdesc}[dnr result]{exchange} The name of a mail-exchanger host. Valid for ``mx'' queries. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{preference} +\begin{memberdesc}[dnr result]{preference} The preference of this mx record. Not too useful, since the Macintosh will only return a single mx record. Valid for ``mx'' queries only. -\end{datadesc} +\end{memberdesc} The simplest way to use the module to convert names to dotted-decimal strings, without worrying about idle time, etc: diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex index 5373d31..6bb4bbf 100644 --- a/Doc/mac/libmacfs.tex +++ b/Doc/mac/libmacfs.tex @@ -4,75 +4,80 @@ This module provides access to Macintosh FSSpec handling, the Alias -Manager, finder aliases and the Standard File package. +Manager, \program{finder} aliases and the Standard File package. +\index{Macintosh Alias Manager} +\index{Alias Manager, Macintosh} +\index{Standard File} Whenever a function or method expects a \var{file} argument, this argument can be one of three things:\ (1) a full or partial Macintosh -pathname, (2) an FSSpec object or (3) a 3-tuple \code{(\var{wdRefNum}, -\var{parID}, \var{name})} as described in \emph{Inside Macintosh -VI}\@. A description of aliases and the standard file package can also -be found there. +pathname, (2) an \pytype{FSSpec} object or (3) a 3-tuple \code{(\var{wdRefNum}, +\var{parID}, \var{name})} as described in \emph{Inside +Macintosh:\ Files}\@. A description of aliases and the Standard File +package can also be found there. \begin{funcdesc}{FSSpec}{file} -Create an FSSpec object for the specified file. +Create an \pytype{FSSpec} object for the specified file. \end{funcdesc} \begin{funcdesc}{RawFSSpec}{data} -Create an FSSpec object given the raw data for the C structure for the -FSSpec as a string. This is mainly useful if you have obtained an -FSSpec structure over a network. +Create an \pytype{FSSpec} object given the raw data for the \C{} +structure for the \pytype{FSSpec} as a string. This is mainly useful +if you have obtained an \pytype{FSSpec} structure over a network. \end{funcdesc} \begin{funcdesc}{RawAlias}{data} -Create an Alias object given the raw data for the C structure for the -alias as a string. This is mainly useful if you have obtained an -FSSpec structure over a network. +Create an \pytype{Alias} object given the raw data for the \C{} +structure for the alias as a string. This is mainly useful if you +have obtained an \pytype{FSSpec} structure over a network. \end{funcdesc} \begin{funcdesc}{FInfo}{} -Create a zero-filled FInfo object. +Create a zero-filled \pytype{FInfo} object. \end{funcdesc} \begin{funcdesc}{ResolveAliasFile}{file} -Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, \var{isfolder}, -\var{aliased})} where \var{fsspec} is the resulting FSSpec object, -\var{isfolder} is true if \var{fsspec} points to a folder and -\var{aliased} is true if the file was an alias in the first place -(otherwise the FSSpec object for the file itself is returned). +Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, +\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting +\pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points +to a folder and \var{aliased} is true if the file was an alias in the +first place (otherwise the \pytype{FSSpec} object for the file itself +is returned). \end{funcdesc} \begin{funcdesc}{StandardGetFile}{\optional{type, ...}} Present the user with a standard ``open input file'' -dialog. Optionally, you can pass up to four 4-char file types to limit -the files the user can choose from. The function returns an FSSpec +dialog. Optionally, you can pass up to four 4-character file types to limit +the files the user can choose from. The function returns an \pytype{FSSpec} object and a flag indicating that the user completed the dialog without cancelling. \end{funcdesc} \begin{funcdesc}{PromptGetFile}{prompt\optional{, type, ...}} -Similar to \var{StandardGetFile} but allows you to specify a prompt. +Similar to \function{StandardGetFile()} but allows you to specify a +prompt. \end{funcdesc} \begin{funcdesc}{StandardPutFile}{prompt, \optional{default}} Present the user with a standard ``open output file'' dialog. \var{prompt} is the prompt string, and the optional \var{default} argument initializes the output file name. The function -returns an FSSpec object and a flag indicating that the user completed -the dialog without cancelling. +returns an \pytype{FSSpec} object and a flag indicating that the user +completed the dialog without cancelling. \end{funcdesc} \begin{funcdesc}{GetDirectory}{\optional{prompt}} Present the user with a non-standard ``select a directory'' dialog. \var{prompt} is the prompt string, and the optional. -Return an FSSpec object and a success-indicator. +Return an \pytype{FSSpec} object and a success-indicator. \end{funcdesc} \begin{funcdesc}{SetFolder}{\optional{fsspec}} Set the folder that is initially presented to the user when one of -the file selection dialogs is presented. \var{Fsspec} should point to +the file selection dialogs is presented. \var{fsspec} should point to a file in the folder, not the folder itself (the file need not exist, though). If no argument is passed the folder will be set to the -current directory, i.e. what \code{os.getcwd()} returns. +current directory, i.e. what \function{os.getcwd()} returns. Note that starting with system 7.5 the user can change Standard File behaviour with the ``general controls'' controlpanel, thereby making @@ -81,16 +86,16 @@ this call inoperative. \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, \var{which} is the 4-char string specifying which folder to +the trash or the Preferences folder. \var{where} is the disk to +search, \var{which} is the 4-character 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. +does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple. \end{funcdesc} \begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname} -Return a minimal alias record object that points to the given file, which +Return a minimal \pytype{alias} object that points to the given file, which must be specified as a full pathname. This is the only way to create an -alias record pointing to a non-existing file. +\pytype{Alias} pointing to a non-existing file. The constants for \var{where} and \var{which} can be obtained from the standard module \var{MACFS}. @@ -98,122 +103,123 @@ standard module \var{MACFS}. \begin{funcdesc}{FindApplication}{creator} Locate the application with 4-char creator code \var{creator}. The -function returns an FSSpec object pointing to the application. +function returns an \pytype{FSSpec} object pointing to the application. \end{funcdesc} \subsection{FSSpec objects} +\label{fsspec-objects} -\setindexsubitem{(FSSpec object attribute)} -\begin{datadesc}{data} +\begin{memberdesc}[FSSpec]{data} The raw data from the FSSpec object, suitable for passing to other applications, for instance. -\end{datadesc} +\end{memberdesc} \setindexsubitem{(FSSpec object method)} -\begin{funcdesc}{as_pathname}{} -Return the full pathname of the file described by the FSSpec object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{as_pathname}{} +Return the full pathname of the file described by the \pytype{FSSpec} +object. +\end{methoddesc} -\begin{funcdesc}{as_tuple}{} -Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of the file described -by the FSSpec object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{as_tuple}{} +Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of +the file described by the \pytype{FSSpec} object. +\end{methoddesc} -\begin{funcdesc}{NewAlias}{\optional{file}} +\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}} Create an Alias object pointing to the file described by this FSSpec. If the optional \var{file} parameter is present the alias will be relative to that file, otherwise it will be absolute. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{NewAliasMinimal}{} +\begin{methoddesc}[FSSpec]{NewAliasMinimal}{} Create a minimal alias pointing to this file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetCreatorType}{} -Return the 4-char creator and type of the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{GetCreatorType}{} +Return the 4-character creator and type of the file. +\end{methoddesc} -\begin{funcdesc}{SetCreatorType}{creator, type} -Set the 4-char creator and type of the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type} +Set the 4-character creator and type of the file. +\end{methoddesc} -\begin{funcdesc}{GetFInfo}{} -Return a FInfo object describing the finder info for the file. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{GetFInfo}{} +Return a \pytype{FInfo} object describing the finder info for the file. +\end{methoddesc} -\begin{funcdesc}{SetFInfo}{finfo} -Set the finder info for the file to the values specified in the -\var{finfo} object. -\end{funcdesc} +\begin{methoddesc}[FSSpec]{SetFInfo}{finfo} +Set the finder info for the file to the values given as \var{finfo} +(an \pytype{FInfo} object). +\end{methoddesc} -\begin{funcdesc}{GetDates}{} +\begin{methoddesc}[FSSpec]{GetDates}{} Return a tuple with three floating point values representing the creation date, modification date and backup date of the file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetDates}{crdate, moddate, backupdate} +\begin{methoddesc}[FSSpec]{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} +\end{methoddesc} + -\subsection{alias objects} +\subsection{Alias Objects} +\label{alias-objects} -\setindexsubitem{(alias object attribute)} -\begin{datadesc}{data} +\begin{memberdesc}[Alias]{data} The raw data for the Alias record, suitable for storing in a resource or transmitting to other programs. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(alias object method)} -\begin{funcdesc}{Resolve}{\optional{file}} +\begin{methoddesc}[Alias]{Resolve}{\optional{file}} Resolve the alias. If the alias was created as a relative alias you should pass the file relative to which it is. Return the FSSpec for -the file pointed to and a flag indicating whether the alias object +the file pointed to and a flag indicating whether the \pytype{Alias} object itself was modified during the search process. If the file does not exist but the path leading up to it does exist a valid fsspec is returned. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetInfo}{num} -An interface to the C routine \code{GetAliasInfo()}. -\end{funcdesc} +\begin{methoddesc}[Alias]{GetInfo}{num} +An interface to the \C{} routine \cfunction{GetAliasInfo()}. +\end{methoddesc} -\begin{funcdesc}{Update}{file, \optional{file2}} +\begin{methoddesc}[Alias]{Update}{file, \optional{file2}} Update the alias to point to the \var{file} given. If \var{file2} is present a relative alias will be created. -\end{funcdesc} +\end{methoddesc} -Note that it is currently not possible to directly manipulate a resource -as an alias object. Hence, after calling \var{Update} or after -\var{Resolve} indicates that the alias has changed the Python program -is responsible for getting the \var{data} from the alias object and -modifying the resource. +Note that it is currently not possible to directly manipulate a +resource as an \pytype{Alias} object. Hence, after calling +\method{Update()} or after \method{Resolve()} indicates that the alias +has changed the Python program is responsible for getting the +\var{data} from the \pytype{Alias} object and modifying the resource. -\subsection{FInfo objects} +\subsection{FInfo Objects} +\label{finfo-objects} -See Inside Mac for a complete description of what the various fields -mean. +See \emph{Inside Macintosh: Files} for a complete description of what +the various fields mean. -\setindexsubitem{(FInfo object attribute)} -\begin{datadesc}{Creator} -The 4-char creator code of the file. -\end{datadesc} +\begin{memberdesc}[FInfo]{Creator} +The 4-character creator code of the file. +\end{memberdesc} -\begin{datadesc}{Type} -The 4-char type code of the file. -\end{datadesc} +\begin{memberdesc}[FInfo]{Type} +The 4-character type code of the file. +\end{memberdesc} -\begin{datadesc}{Flags} +\begin{memberdesc}[FInfo]{Flags} 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} +\var{Flags} are defined in standard module \module{MACFS}. +\end{memberdesc} -\begin{datadesc}{Location} +\begin{memberdesc}[FInfo]{Location} A Point giving the position of the file's icon in its folder. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{Fldr} +\begin{memberdesc}[FInfo]{Fldr} The folder the file is in (as an integer). -\end{datadesc} +\end{memberdesc} diff --git a/Doc/mac/libmacic.tex b/Doc/mac/libmacic.tex index 734ac11..7cd0557 100644 --- a/Doc/mac/libmacic.tex +++ b/Doc/mac/libmacic.tex @@ -30,7 +30,7 @@ Exception raised on errors in the \module{ic} module. The \module{ic} module defines the following functions: \begin{funcdesc}{IC}{\optional{signature\optional{, ic}}} -Create an internet config object. The signature is a 4-char creator +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 @@ -62,7 +62,7 @@ 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 -\var{data} attribute. Objects of this type are also acceptable values +\member{data} attribute. Objects of this type are also acceptable values for assignment. Besides the dictionary interface IC objects have the following methods: @@ -82,21 +82,22 @@ 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 textfield you can pass the whole textfield and the click-position in \var{start} and this routine will return the whole URL in which the -user clicked. \var{Hint} is again an optional scheme used to complete -incomplete URLs. +user clicked. As above, \var{hint} is an optional scheme used to +complete incomplete URLs. \end{funcdesc} \begin{funcdesc}{mapfile}{file} Return the mapping entry for the given \var{file}, which can be passed -as either a filename or an \code{macfs.FSSpec} object, and which need -not exist. +as either a filename or an \function{macfs.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}\code{)}, where \var{version} is the entry version -number, \var{type} is the 4-char filetype, \var{creator} is the 4-char -creator type, \var{postcreator} is the 4-char creator code of an +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 @@ -107,7 +108,7 @@ file and \var{entryname} is the name of this entry. \end{funcdesc} \begin{funcdesc}{maptypecreator}{type, creator\optional{, filename}} -Return the mapping entry for files with given 4-char \var{type} and +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). @@ -117,7 +118,7 @@ The mapping entry is returned in the same format as for \var{mapfile}. \begin{funcdesc}{settypecreator}{file} Given an existing \var{file}, specified either as a filename or as an -\code{macfs.FSSpec} record, set its creator and type correctly based +\function{macfs.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{funcdesc} diff --git a/Doc/mac/libmacspeech.tex b/Doc/mac/libmacspeech.tex index 8c74268..14a9c61 100644 --- a/Doc/mac/libmacspeech.tex +++ b/Doc/mac/libmacspeech.tex @@ -1,19 +1,21 @@ -\section{Built-in Module \sectcode{macspeech}} +\section{Built-in Module \module{macspeech}} \label{module-macspeech} \bimodindex{macspeech} -\setindexsubitem{(in module macspeech)} This module provides an interface to the Macintosh Speech Manager, +\index{Macintosh Speech Manager} +\index{Speech Manager, Macintosh} allowing you to let the Macintosh utter phrases. You need a version of -the speech manager extension (version 1 and 2 have been tested) in -your \code{Extensions} folder for this to work. The module does not +the Speech Manager extension (version 1 and 2 have been tested) in +your \file{Extensions} folder for this to work. The module does not provide full access to all features of the Speech Manager yet. It may not be available in all Mac Python versions. \begin{funcdesc}{Available}{} Test availability of the Speech Manager extension (and, on the -PowerPC, the Speech Manager shared library). Return 0 or 1. +PowerPC, the Speech Manager shared library). Return \code{0} or +\code{1}. \end{funcdesc} \begin{funcdesc}{Version}{} @@ -23,7 +25,7 @@ Return the (integer) version number of the Speech Manager. \begin{funcdesc}{SpeakString}{str} Utter the string \var{str} using the default voice, asynchronously. This aborts any speech that may still be active from -prior \code{SpeakString} invocations. +prior \function{SpeakString()} invocations. \end{funcdesc} \begin{funcdesc}{Busy}{} @@ -35,53 +37,57 @@ Return the number of different voices available. \end{funcdesc} \begin{funcdesc}{GetIndVoice}{num} -Return a voice object for voice number \var{num}. +Return a \pytype{Voice} object for voice number \var{num}. \end{funcdesc} -\subsection{voice objects} +\subsection{Voice Objects} +\label{voice-objects} + Voice objects contain the description of a voice. It is currently not yet possible to access the parameters of a voice. \setindexsubitem{(voice object method)} -\begin{funcdesc}{GetGender}{} -Return the gender of the voice: 0 for male, 1 for female and -1 for neuter. -\end{funcdesc} +\begin{methoddesc}[Voice]{GetGender}{} +Return the gender of the voice: \code{0} for male, \code{1} for female +and \code{-1} for neuter. +\end{methoddesc} -\begin{funcdesc}{NewChannel}{} -Return a new speech channel object using this voice. -\end{funcdesc} +\begin{methoddesc}[Voice]{NewChannel}{} +Return a new Speech Channel object using this voice. +\end{methoddesc} -\subsection{speech channel objects} -A speech channel object allows you to speak strings with slightly more -control than \code{SpeakString()}, and allows you to use multiple +\subsection{Speech Channel Objects} +\label{speech-channel-objects} + +A Speech Channel object allows you to speak strings with slightly more +control than \function{SpeakString()}, and allows you to use multiple speakers at the same time. Please note that channel pitch and rate are interrelated in some way, so that to make your Macintosh sing you will have to adjust both. -\setindexsubitem{(speech channel object method)} -\begin{funcdesc}{SpeakText}{str} +\begin{methoddesc}[Speech Channel]{SpeakText}{str} Start uttering the given string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{Stop}{} +\begin{methoddesc}[Speech Channel]{Stop}{} Stop babbling. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetPitch}{} +\begin{methoddesc}[Speech Channel]{GetPitch}{} Return the current pitch of the channel, as a floating-point number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetPitch}{pitch} +\begin{methoddesc}[Speech Channel]{SetPitch}{pitch} Set the pitch of the channel. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{GetRate}{} +\begin{methoddesc}[Speech Channel]{GetRate}{} Get the speech rate (utterances per minute) of the channel as a floating point number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{SetRate}{rate} +\begin{methoddesc}[Speech Channel]{SetRate}{rate} Set the speech rate of the channel. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex index bf8a30f..7f5237b 100644 --- a/Doc/mac/libmacui.tex +++ b/Doc/mac/libmacui.tex @@ -1,16 +1,15 @@ -\section{Standard Module \sectcode{EasyDialogs}} +\section{Standard Module \module{EasyDialogs}} \label{module-EasyDialogs} \stmodindex{EasyDialogs} -The \code{EasyDialogs} module contains some simple dialogs for -the Macintosh, modelled after the \code{stdwin} dialogs with similar +The \module{EasyDialogs} module contains some simple dialogs for +the Macintosh, modelled after the \module{stdwin} dialogs with similar names. All routines have an optional parameter \var{id} with which you can override the DLOG resource used for the dialog, as long as the item numbers correspond. See the source for details. + +The \module{EasyDialogs} module defines the following functions: -The \code{EasyDialogs} module defines the following functions: - -\setindexsubitem{(in module EasyDialogs)} \begin{funcdesc}{Message}{str} A modal dialog with the message text \var{str}, which should be at @@ -19,11 +18,11 @@ 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} +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. +long. \function{AskString()} returns the string entered or \code{None} +in case the user cancelled. \end{funcdesc} \begin{funcdesc}{AskYesNoCancel}{question\optional{, default}} @@ -34,19 +33,19 @@ hitting return is \code{0}. This can be changed with the optional \var{default} argument. \end{funcdesc} -\begin{funcdesc}{ProgressBar}{\optional{label, maxval}} -Display a modeless progress dialog with a thermometer bar. \var{Label} -is the textstring displayed (default ``Working...''), \var{maxval} is -the value at which progress is complete (default 100). The returned -object has one method, \code{set(value)}, which sets the value of the -progress bar. The bar remains visible until the object returned is -discarded. +\begin{funcdesc}{ProgressBar}{\optional{label\optional{, maxval}}} +Display a modeless progress dialog with a thermometer bar. \var{label} +is the text string displayed (default ``Working...''), \var{maxval} is +the value at which progress is complete (default \code{100}). The +returned object has one method, \code{set(\var{value})}, which sets +the value of the progress bar. The bar remains visible until the +object returned is discarded. The progress bar has a ``cancel'' button, but it is currently non-functional. \end{funcdesc} -Note that \code{EasyDialogs} does not currently use the notification +Note that \module{EasyDialogs} does not currently use the notification manager. This means that displaying dialogs while the program is in the background will lead to unexpected results and possibly crashes. Also, all dialogs are modeless and hence expect to be at the diff --git a/Doc/mac/libminiae.tex b/Doc/mac/libminiae.tex index d898551..a1cd6f4 100644 --- a/Doc/mac/libminiae.tex +++ b/Doc/mac/libminiae.tex @@ -1,61 +1,63 @@ -\section{Standard Module \sectcode{MiniAEFrame}} +\section{Standard Module \module{MiniAEFrame}} \stmodindex{MiniAEFrame} \label{module-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. +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 +\module{FrameWork}\refstmodindex{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: +The \module{MiniAEFrame} module defines the following classes: -\setindexsubitem{(in module MiniAEFrame)} -\begin{funcdesc}{AEServer}{} +\begin{classdesc}{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} +\class{MiniApplication} or +\class{FrameWork.Application}. Your \method{__init__()} method should +call the \method{__init__()} method for both classes. +\end{classdesc} -\begin{funcdesc}{MiniApplication}{} +\begin{classdesc}{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 +\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 \code{AEServer} but does not +Useful if your application wants to use \class{AEServer} but does not provide its own windows, etc. -\end{funcdesc} +\end{classdesc} -\subsection{AEServer Objects} -\setindexsubitem{(AEServer method)} +\subsection{AEServer Objects} +\label{aeserver-objects} -\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 +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{callback}{_object, **kwargs} +\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-char designator as name. Three extra keyword parameters are +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 -\code{aetools.packevent} and sent as reply. -\end{funcdesc} +\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-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. +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. |