From 66774a973babca294045b3e8162db1f13c2d50de Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Sun, 21 Jul 1996 02:20:58 +0000 Subject: changes by Jack to Mac docs --- Doc/libmac.tex | 42 +++++++++++++++++++++++++ Doc/libmacos.tex | 16 ++++++++++ Doc/libmactcp.tex | 8 ++--- Doc/libmacui.tex | 87 ++++++++++++++++++++++++++++++++++++++++++++++++--- Doc/mac/libmac.tex | 42 +++++++++++++++++++++++++ Doc/mac/libmacos.tex | 16 ++++++++++ Doc/mac/libmactcp.tex | 8 ++--- Doc/mac/libmacui.tex | 87 ++++++++++++++++++++++++++++++++++++++++++++++++--- 8 files changed, 288 insertions(+), 18 deletions(-) diff --git a/Doc/libmac.tex b/Doc/libmac.tex index af07142..344d300 100644 --- a/Doc/libmac.tex +++ b/Doc/libmac.tex @@ -2,6 +2,37 @@ The modules in this chapter are available on the Apple Macintosh only. +Aside from the modules described here there are also interfaces to +various MacOS toolboxes, which are currently not extensively +described. The toolboxes for which modules exist are: +\code{AE} (Apple Events), +\code{Cm} (Component Manager), +\code{Ctl} (Control Manager), +\code{Dlg} (Dialog Manager), +\code{Evt} (Event Manager), +\code{Fm} (Font Manager), +\code{List} (List Manager), +\code{Menu} (Moenu Manager), +\code{Qd} (QuickDraw), +\code{Qt} (QuickTime), +\code{Res} (Resource Manager and Handles), +\code{Scrap} (Scrap Manager), +\code{Snd} (Sound Manager), +\code{TE} (TextEdit), +\code{Waste} (non-Apple TextEdit replacement) and +\code{Win} (Window Manager). + +If applicable the module will define a number of Python objects for +the various structures declared by the toolbox, and operations will be +implemented as methods of the object. Other operations will be +implemented as functions in the module. Not all operations possible in +C will also be possible in Python (callbacks are often a problem), and +parameters will occasionally be different in Python (input and output +buffers, especially). All methods and functions have a \code{__doc__} +string describing their arguments and return values, and for +additional description you are referred to Inside Mac or similar +works. + \section{Built-in Module \sectcode{mac}} \bimodindex{mac} @@ -12,14 +43,21 @@ It is best accessed through the more portable standard module The following functions are available in this module: \code{chdir}, +\code{close}, +\code{dup}, +\code{fdopen}, \code{getcwd}, +\code{lseek}, \code{listdir}, \code{mkdir}, +\code{open}, +\code{read}, \code{rename}, \code{rmdir}, \code{stat}, \code{sync}, \code{unlink}, +\code{write}, as well as the exception \code{error}. \section{Standard Module \sectcode{macpath}} @@ -32,9 +70,13 @@ best accessed through the more portable standard module \code{os}, as The following functions are available in this module: \code{normcase}, +\code{normpath}, \code{isabs}, \code{join}, \code{split}, \code{isdir}, \code{isfile}, +\code{walk}, \code{exists}. +For other functions available in \code{posixpath} dummy counterparts +are available. diff --git a/Doc/libmacos.tex b/Doc/libmacos.tex index 6618754..e48a0c3 100644 --- a/Doc/libmacos.tex +++ b/Doc/libmacos.tex @@ -72,3 +72,19 @@ window-switching capability. \begin{funcdesc}{GetErrorString}{errno} Return the textual description of MacOS error code \var{errno}. \end{funcdesc} + +\begin{funcdesc}{splash}{resid} +This function will put a splash window +on-screen, with the contents of the DLOG resource specified by +\code{resid}. Calling with a zero argument will remove the splash +screen. This function is useful if you want to post a splash screen +early in initialization without first having to load numerous +extension modules. +\end{funcdesc} + +\begin{funcdesc}{openrf}{name \optional{\, mode}} +Open the resource fork of a file. Arguments are the same as for the +builtin function \code{open}. The object returned has file-like +semantics, but it is not a python file object, so there may be subtle +differences. +\end{funcdesc} diff --git a/Doc/libmactcp.tex b/Doc/libmactcp.tex index 6c5a78b..80e19ca 100644 --- a/Doc/libmactcp.tex +++ b/Doc/libmactcp.tex @@ -6,10 +6,10 @@ This module provides an interface to the Macintosh TCP/IP driver MacTCP\@. There is an accompanying module \code{macdnr} which provides an interface to the name-server (allowing you to translate hostnames to -ip-addresses), a module \code{MACTCP} which has symbolic names for -constants constants used by MacTCP and a wrapper module \code{socket} -which mimics the \UNIX{} socket interface (as far as possible). It may -not be available in all Mac Python versions. +ip-addresses), a module \code{MACTCPconst} which has symbolic names for +constants constants used by MacTCP. Since the builtin module +\code{socket} is also available on the mac it is usually easier to use +sockets in stead of the mac-specific MacTCP API. A complete description of the MacTCP interface can be found in the Apple MacTCP API documentation. diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex index f785679..1c2df7c 100644 --- a/Doc/libmacui.tex +++ b/Doc/libmacui.tex @@ -66,10 +66,10 @@ handling. The \code{FrameWork} is still very much work-in-progress, and the documentation describes only the most important functionality, and not -in the most logical manner at that. Examine the source for more -esoteric needs. +in the most logical manner at that. Examine the source or the examples +for more details. -The \code{EasyDialogs} module defines the following functions: +The \code{FrameWork} module defines the following functions: \renewcommand{\indexsubitem}{(in module FrameWork)} @@ -117,6 +117,14 @@ which the window belongs. The window is not displayed until later. Creates a modeless dialog window. \end{funcdesc} +\begin{funcdesc}{windowbounds}{width\, height} +Return a \code{(left, top, right, bottom)} tuple suitable for creation +of a window of given width and height. The window will be staggered +with respect to previous windows, and an attempt is made to keep the +whole window on-screen. The window will however always be exact the +size given, so parts may be offscreen. +\end{funcdesc} + \subsection{Application objects} Application objects have the following methods, among others: @@ -161,8 +169,9 @@ through the the \code{DialogWindow} object involved). Override if you need special handling of dialog events (keyboard shortcuts, etc). \end{funcdesc} -\begin{funcdesc}{idle}{} -Called by the main event loop when no events are available. +\begin{funcdesc}{idle}{event} +Called by the main event loop when no events are available. The +null-event is passed (so you can look at mouse position, etc). \end{funcdesc} \subsection{Window Objects} @@ -202,6 +211,74 @@ The window was activated (\code{activate==1}) or deactivated (\code{activate==0}). Handle things like focus highlighting, etc. \end{funcdesc} +\subsection{ControlsWindow Object} + +ControlsWindow objects have the following methods besides those of +\code{Window} objects: + +\renewcommand{\indexsubitem}{(ControlsWindow method)} + +\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event} +Part \code{pcode} of control \code{control} was hit by the +user. Tracking and such has already been taken care of. +\end{funcdesc} + +\subsection{ScrolledWindow Object} + +ScrolledWindow objects are ControlsWindow objects with the following +extra mathods: + +\renewcommand{\indexsubitem}{(ScrolledWindow method)} + +\begin{funcdesc}{scrollbars}{\optional{wantx\, 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. +\end{funcdesc} + +\begin{funcdesc}{updatescrollbars}{} +Call this method when the document has changed. It will call +\code{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{'-'}, +\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For +\code{'set'}, \code{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 +and topmost (leftmost) and bottommost (rightmost) visible values and +it returns the correct number or \code{None}. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{onoff\, event} +Takes care of dimming/highlighting scrollbars when a window becomes +frontmost vv. If you override this method call this one at the end of +your method. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, window} +Moves scrollbars to the correct position. Call this method initially +if you override it. +\end{funcdesc} + +\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event} +Handles scrollbar interaction. If you override it call this method +first, a nonzero return value indicates the hit was in the scrollbars +and has been handled. +\end{funcdesc} + \subsection{DialogWindow Objects} DialogWindow objects have the following methods besides those of diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex index af07142..344d300 100644 --- a/Doc/mac/libmac.tex +++ b/Doc/mac/libmac.tex @@ -2,6 +2,37 @@ The modules in this chapter are available on the Apple Macintosh only. +Aside from the modules described here there are also interfaces to +various MacOS toolboxes, which are currently not extensively +described. The toolboxes for which modules exist are: +\code{AE} (Apple Events), +\code{Cm} (Component Manager), +\code{Ctl} (Control Manager), +\code{Dlg} (Dialog Manager), +\code{Evt} (Event Manager), +\code{Fm} (Font Manager), +\code{List} (List Manager), +\code{Menu} (Moenu Manager), +\code{Qd} (QuickDraw), +\code{Qt} (QuickTime), +\code{Res} (Resource Manager and Handles), +\code{Scrap} (Scrap Manager), +\code{Snd} (Sound Manager), +\code{TE} (TextEdit), +\code{Waste} (non-Apple TextEdit replacement) and +\code{Win} (Window Manager). + +If applicable the module will define a number of Python objects for +the various structures declared by the toolbox, and operations will be +implemented as methods of the object. Other operations will be +implemented as functions in the module. Not all operations possible in +C will also be possible in Python (callbacks are often a problem), and +parameters will occasionally be different in Python (input and output +buffers, especially). All methods and functions have a \code{__doc__} +string describing their arguments and return values, and for +additional description you are referred to Inside Mac or similar +works. + \section{Built-in Module \sectcode{mac}} \bimodindex{mac} @@ -12,14 +43,21 @@ It is best accessed through the more portable standard module The following functions are available in this module: \code{chdir}, +\code{close}, +\code{dup}, +\code{fdopen}, \code{getcwd}, +\code{lseek}, \code{listdir}, \code{mkdir}, +\code{open}, +\code{read}, \code{rename}, \code{rmdir}, \code{stat}, \code{sync}, \code{unlink}, +\code{write}, as well as the exception \code{error}. \section{Standard Module \sectcode{macpath}} @@ -32,9 +70,13 @@ best accessed through the more portable standard module \code{os}, as The following functions are available in this module: \code{normcase}, +\code{normpath}, \code{isabs}, \code{join}, \code{split}, \code{isdir}, \code{isfile}, +\code{walk}, \code{exists}. +For other functions available in \code{posixpath} dummy counterparts +are available. diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex index 6618754..e48a0c3 100644 --- a/Doc/mac/libmacos.tex +++ b/Doc/mac/libmacos.tex @@ -72,3 +72,19 @@ window-switching capability. \begin{funcdesc}{GetErrorString}{errno} Return the textual description of MacOS error code \var{errno}. \end{funcdesc} + +\begin{funcdesc}{splash}{resid} +This function will put a splash window +on-screen, with the contents of the DLOG resource specified by +\code{resid}. Calling with a zero argument will remove the splash +screen. This function is useful if you want to post a splash screen +early in initialization without first having to load numerous +extension modules. +\end{funcdesc} + +\begin{funcdesc}{openrf}{name \optional{\, mode}} +Open the resource fork of a file. Arguments are the same as for the +builtin function \code{open}. The object returned has file-like +semantics, but it is not a python file object, so there may be subtle +differences. +\end{funcdesc} diff --git a/Doc/mac/libmactcp.tex b/Doc/mac/libmactcp.tex index 6c5a78b..80e19ca 100644 --- a/Doc/mac/libmactcp.tex +++ b/Doc/mac/libmactcp.tex @@ -6,10 +6,10 @@ This module provides an interface to the Macintosh TCP/IP driver MacTCP\@. There is an accompanying module \code{macdnr} which provides an interface to the name-server (allowing you to translate hostnames to -ip-addresses), a module \code{MACTCP} which has symbolic names for -constants constants used by MacTCP and a wrapper module \code{socket} -which mimics the \UNIX{} socket interface (as far as possible). It may -not be available in all Mac Python versions. +ip-addresses), a module \code{MACTCPconst} which has symbolic names for +constants constants used by MacTCP. Since the builtin module +\code{socket} is also available on the mac it is usually easier to use +sockets in stead of the mac-specific MacTCP API. A complete description of the MacTCP interface can be found in the Apple MacTCP API documentation. diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex index f785679..1c2df7c 100644 --- a/Doc/mac/libmacui.tex +++ b/Doc/mac/libmacui.tex @@ -66,10 +66,10 @@ handling. The \code{FrameWork} is still very much work-in-progress, and the documentation describes only the most important functionality, and not -in the most logical manner at that. Examine the source for more -esoteric needs. +in the most logical manner at that. Examine the source or the examples +for more details. -The \code{EasyDialogs} module defines the following functions: +The \code{FrameWork} module defines the following functions: \renewcommand{\indexsubitem}{(in module FrameWork)} @@ -117,6 +117,14 @@ which the window belongs. The window is not displayed until later. Creates a modeless dialog window. \end{funcdesc} +\begin{funcdesc}{windowbounds}{width\, height} +Return a \code{(left, top, right, bottom)} tuple suitable for creation +of a window of given width and height. The window will be staggered +with respect to previous windows, and an attempt is made to keep the +whole window on-screen. The window will however always be exact the +size given, so parts may be offscreen. +\end{funcdesc} + \subsection{Application objects} Application objects have the following methods, among others: @@ -161,8 +169,9 @@ through the the \code{DialogWindow} object involved). Override if you need special handling of dialog events (keyboard shortcuts, etc). \end{funcdesc} -\begin{funcdesc}{idle}{} -Called by the main event loop when no events are available. +\begin{funcdesc}{idle}{event} +Called by the main event loop when no events are available. The +null-event is passed (so you can look at mouse position, etc). \end{funcdesc} \subsection{Window Objects} @@ -202,6 +211,74 @@ The window was activated (\code{activate==1}) or deactivated (\code{activate==0}). Handle things like focus highlighting, etc. \end{funcdesc} +\subsection{ControlsWindow Object} + +ControlsWindow objects have the following methods besides those of +\code{Window} objects: + +\renewcommand{\indexsubitem}{(ControlsWindow method)} + +\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event} +Part \code{pcode} of control \code{control} was hit by the +user. Tracking and such has already been taken care of. +\end{funcdesc} + +\subsection{ScrolledWindow Object} + +ScrolledWindow objects are ControlsWindow objects with the following +extra mathods: + +\renewcommand{\indexsubitem}{(ScrolledWindow method)} + +\begin{funcdesc}{scrollbars}{\optional{wantx\, 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. +\end{funcdesc} + +\begin{funcdesc}{updatescrollbars}{} +Call this method when the document has changed. It will call +\code{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{'-'}, +\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For +\code{'set'}, \code{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 +and topmost (leftmost) and bottommost (rightmost) visible values and +it returns the correct number or \code{None}. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{onoff\, event} +Takes care of dimming/highlighting scrollbars when a window becomes +frontmost vv. If you override this method call this one at the end of +your method. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, window} +Moves scrollbars to the correct position. Call this method initially +if you override it. +\end{funcdesc} + +\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event} +Handles scrollbar interaction. If you override it call this method +first, a nonzero return value indicates the hit was in the scrollbars +and has been handled. +\end{funcdesc} + \subsection{DialogWindow Objects} DialogWindow objects have the following methods besides those of -- cgit v0.12