traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Logical markup. 

Index entries.
This commit is contained in:
Fred Drake 1998-04-04 06:23:02 +00:00
parent 9b28fe285d
commit 41788db3e2
20 changed files with 692 additions and 639 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
Doc/lib/libframework.tex
View File

@ -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:

64
Doc/lib/libminiae.tex
View File

@ -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}
\label{aeserver-objects}
\setindexsubitem{(AEServer method)}
\begin{funcdesc}{installaehandler}{classe, type, callback}
Installs an AppleEvent handler. \code{Classe} and \code{type} are the
four-char OSA Class and Type designators, \code{'****'} wildcards are
allowed. When a matching AppleEvent is received the parameters are
\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.

105
Doc/libctb.tex
View File

@ -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}
\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 \var{cmData}, \var{cmCntl} or
\var{cmAttn}). Return a 2-tuple:\ the data read and the end-of-message
flag.
\end{funcdesc}
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}

59
Doc/libframework.tex
View File

@ -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:

1
Doc/libmacconsole.tex
View File

@ -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

51
Doc/libmacdnr.tex
View File

@ -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:

202
Doc/libmacfs.tex
View File

@ -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}
\setindexsubitem{(alias object attribute)}
\begin{datadesc}{data}
\subsection{Alias Objects}
\label{alias-objects}
\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}

21
Doc/libmacic.tex
View File

@ -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}

66
Doc/libmacspeech.tex
View File

@ -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}

31
Doc/libmacui.tex
View File

@ -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 \code{EasyDialogs} module defines the following functions:
The \module{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

64
Doc/libminiae.tex
View File

@ -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}
\label{aeserver-objects}
\setindexsubitem{(AEServer method)}
\begin{funcdesc}{installaehandler}{classe, type, callback}
Installs an AppleEvent handler. \code{Classe} and \code{type} are the
four-char OSA Class and Type designators, \code{'****'} wildcards are
allowed. When a matching AppleEvent is received the parameters are
\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.

105
Doc/mac/libctb.tex
View File

@ -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}
\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 \var{cmData}, \var{cmCntl} or
\var{cmAttn}). Return a 2-tuple:\ the data read and the end-of-message
flag.
\end{funcdesc}
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}

59
Doc/mac/libframework.tex
View File

@ -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:

1
Doc/mac/libmacconsole.tex
View File

@ -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

51
Doc/mac/libmacdnr.tex
View File

@ -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:

202
Doc/mac/libmacfs.tex
View File

@ -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}
\setindexsubitem{(alias object attribute)}
\begin{datadesc}{data}
\subsection{Alias Objects}
\label{alias-objects}
\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}

21
Doc/mac/libmacic.tex
View File

@ -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}

66
Doc/mac/libmacspeech.tex
View File

@ -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}

31
Doc/mac/libmacui.tex
View File

@ -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 \code{EasyDialogs} module defines the following functions:
The \module{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

64
Doc/mac/libminiae.tex
View File

@ -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}
\label{aeserver-objects}
\setindexsubitem{(AEServer method)}
\begin{funcdesc}{installaehandler}{classe, type, callback}
Installs an AppleEvent handler. \code{Classe} and \code{type} are the
four-char OSA Class and Type designators, \code{'****'} wildcards are
allowed. When a matching AppleEvent is received the parameters are
\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.