diff options
| -rw-r--r-- | Doc/lib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libframework.tex | 287 | ||||
| -rw-r--r-- | Doc/lib/libminiae.tex | 61 | ||||
| -rw-r--r-- | Doc/libframework.tex | 287 | ||||
| -rw-r--r-- | Doc/libmacui.tex | 351 | ||||
| -rw-r--r-- | Doc/libminiae.tex | 61 | ||||
| -rw-r--r-- | Doc/mac/libframework.tex | 287 | ||||
| -rw-r--r-- | Doc/mac/libmacui.tex | 351 | ||||
| -rw-r--r-- | Doc/mac/libminiae.tex | 61 |
10 files changed, 1048 insertions, 702 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex index 4aee15b..7702c25 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -201,6 +201,8 @@ add new extensions to Python and how to embed it in other applications. \input{libmactcp} \input{libmacspeech} \input{libmacui} +\input{libframework} +\input{libminiae} %\input{libstdwin} % STDWIN ONLY diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 4aee15b..7702c25 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -201,6 +201,8 @@ add new extensions to Python and how to embed it in other applications. \input{libmactcp} \input{libmacspeech} \input{libmacui} +\input{libframework} +\input{libminiae} %\input{libstdwin} % STDWIN ONLY diff --git a/Doc/lib/libframework.tex b/Doc/lib/libframework.tex new file mode 100644 index 0000000..012b8c5 --- /dev/null +++ b/Doc/lib/libframework.tex @@ -0,0 +1,287 @@ +\section{Standard Module \sectcode{FrameWork}} +\stmodindex{FrameWork} +\label{module-FrameWork} + +The \code{FrameWork} module contains classes that together provide a +framework for an interactive Macintosh application. The programmer +builds an application by creating subclasses that override various +methods of the bases classes, thereby implementing the functionality +wanted. Overriding functionality can often be done on various +different levels, i.e. to handle clicks in a single dialog window in a +non-standard way it is not necessary to override the complete event +handling. + +The \code{FrameWork} is still very much work-in-progress, and the +documentation describes only the most important functionality, and not +in the most logical manner at that. Examine the source or the examples +for more details. + +The \code{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 +creates an empty window dictionary and a menu bar with an apple menu. +\end{funcdesc} + +\begin{funcdesc}{MenuBar}{} +An object representing the menubar. This object is usually not created +by the user. +\end{funcdesc} + +\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} +An object representing a menu. Upon creation you pass the +\code{MenuBar} the menu appears in, the \var{title} string and a +position (1-based) \var{after} where the menu should appear (default: +at the end). +\end{funcdesc} + +\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} +Create a menu item object. The arguments are the menu to crate the +item it, the item title string and optionally the keyboard shortcut +and a callback routine. The callback is called with the arguments +menu-id, item number within menu (1-based), current front window and +the event record. + +In stead of a callable object the callback can also be a string. In +this case menu selection causes the lookup of a method in the topmost +window and the application. The method name is the callback string +with \code{'domenu_'} prepended. + +Calling the \code{MenuBar} \code{fixmenudimstate} method sets the +correct dimming for all menu items based on the current front window. +\end{funcdesc} + +\begin{funcdesc}{Separator}{menu} +Add a separator to the end of a menu. +\end{funcdesc} + +\begin{funcdesc}{SubMenu}{menu\, label} +Create a submenu named \var{label} under menu \var{menu}. The menu +object is returned. +\end{funcdesc} + +\begin{funcdesc}{Window}{parent} +Creates a (modeless) window. \var{Parent} is the application object to +which the window belongs. The window is not displayed until later. +\end{funcdesc} + +\begin{funcdesc}{DialogWindow}{parent} +Creates a modeless dialog window. +\end{funcdesc} + +\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} + +\begin{funcdesc}{setwatchcursor}{} +Set the mouse cursor to a watch. +\end{funcdesc} + +\begin{funcdesc}{setarrowcursor}{} +Set the mouse cursor to an arrow. +\end{funcdesc} + +\subsection{Application objects} +Application objects have the following methods, among others: + +\setindexsubitem{(Application method)} + +\begin{funcdesc}{makeusermenus}{} +Override this method if you need menus in your application. Append the +menus to \code{self.menubar}. +\end{funcdesc} + +\begin{funcdesc}{getabouttext}{} +Override this method to return a text string describing your +application. Alternatively, override the \code{do_about} method for +more elaborate about messages. +\end{funcdesc} + +\begin{funcdesc}{mainloop}{\optional{mask\, wait}} +This routine is the main event loop, call it to set your application +rolling. \var{Mask} is the mask of events you want to handle, +\var{wait} is the number of ticks you want to leave to other +concurrent application (default 0, which is probably not a good +idea). While raising \code{self} to exit the mainloop is still +supported it is not recommended, call \code{self._quit} instead. + +The event loop is split into many small parts, each of which can be +overridden. The default methods take care of dispatching events to +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 +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. +\end{funcdesc} + +\begin{funcdesc}{asyncevents}{onoff} +Call this method with a nonzero parameter to enable +asynchronous event handling. This will tell the inner interpreter loop +to call the application event handler \var{async_dispatch} whenever events +are available. This will cause FrameWork window updates and the user +interface to remain working during long computations, but will slow the +interpreter down and may cause surprising results in non-reentrant code +(such as FrameWork itself). By default \var{async_dispatch} will immedeately +call \var{our_dispatch} but you may override this to handle only certain +events asynchronously. Events you do not handle will be passed to Sioux +and such. + +The old on/off value is returned. +\end{funcdesc} + +\begin{funcdesc}{_quit}{} +Terminate the event \code{mainloop} at the next convenient moment. +\end{funcdesc} + +\begin{funcdesc}{do_char}{c\, event} +The user typed character \var{c}. The complete details of the event +can be found in the \var{event} structure. This method can also be +provided in a \code{Window} object, which overrides the +application-wide handler if the window is frontmost. +\end{funcdesc} + +\begin{funcdesc}{do_dialogevent}{event} +Called early in the event loop to handle modeless dialog events. The +default method simply dispatches the event to the relevant dialog (not +through the the \code{DialogWindow} object involved). Override if you +need special handling of dialog events (keyboard shortcuts, etc). +\end{funcdesc} + +\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} + +Window objects have the following methods, among others: + +\setindexsubitem{(Window method)} + +\begin{funcdesc}{open}{} +Override this method to open a window. Store the MacOS window-id in +\code{self.wid} and call \code{self.do_postopen} to register the +window with the parent application. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Override this method to do any special processing on window +close. Call \code{self.do_postclose} to cleanup the parent state. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} +Called after the window is resized. Override if more needs to be done +than calling \code{InvalRect}. +\end{funcdesc} + +\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} +The user clicked in the content part of a window. The arguments are +the coordinates (window-relative), the key modifiers and the raw +event. +\end{funcdesc} + +\begin{funcdesc}{do_update}{macoswindowid\, event} +An update event for the window was received. Redraw the window. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{activate\, event} +The window was activated (\code{activate==1}) or deactivated +(\code{activate==0}). Handle things like focus highlighting, etc. +\end{funcdesc} + +\subsection{ControlsWindow Object} + +ControlsWindow objects have the following methods besides those of +\code{Window} objects: + +\setindexsubitem{(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 methods: + +\setindexsubitem{(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 +\code{Window} objects: + +\setindexsubitem{(DialogWindow method)} + +\begin{funcdesc}{open}{resid} +Create the dialog window, from the DLOG resource with id +\var{resid}. The dialog object is stored in \code{self.wid}. +\end{funcdesc} + +\begin{funcdesc}{do_itemhit}{item\, event} +Item number \var{item} was hit. You are responsible for redrawing +toggle buttons, etc. +\end{funcdesc} diff --git a/Doc/lib/libminiae.tex b/Doc/lib/libminiae.tex new file mode 100644 index 0000000..00666fa --- /dev/null +++ b/Doc/lib/libminiae.tex @@ -0,0 +1,61 @@ +\section{Standard Module \sectcode{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. + +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: + +\setindexsubitem{(in module MiniAEFrame)} + +\begin{funcdesc}{AEServer}{} +A class that handles AppleEvent dispatch. Your application should +subclass this class together with either +\code{MiniAEFrame.MiniApplication} or +\code{FrameWork.Application}. Your \code{__init__} method should call +the \code{__init__} method for both classes. +\end{funcdesc} + +\begin{funcdesc}{MiniApplication}{} +A class that is more or less compatible with +\code{FrameWork.Application} but with less functionality. Its +eventloop supports the apple menu, command-dot and AppleEvents, other +events are passed on to the Python interpreter and/or Sioux. +Useful if your application wants to use \code{AEServer} but does not +provide its own windows, etc. +\end{funcdesc} + +\subsection{AEServer Objects} + +\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 +decoded and your callback is invoked. +\end{funcdesc} + +\begin{funcdesc}{callback}{_object\, **kwargs} +Your callback is called with the OSA Direct Object as first positional +parameter. The other parameters are passed as keyword arguments, with +the 4-char designator as name. Three extra keyword parameters are +passed: \code{_class} and \code{_type} are the Class and Type +designators and \code{_attributes} is a dictionary with the AppleEvent +attributes. + +The return value of your method is packed with +\code{aetools.packevent} and sent as reply. +\end{funcdesc} + +Note that there are some serious problems with the current +design. AppleEvents which have non-identifier 4-char designators for +arguments are not implementable, and it is not possible to return an +error to the originator. This will be addressed in a future release. diff --git a/Doc/libframework.tex b/Doc/libframework.tex new file mode 100644 index 0000000..012b8c5 --- /dev/null +++ b/Doc/libframework.tex @@ -0,0 +1,287 @@ +\section{Standard Module \sectcode{FrameWork}} +\stmodindex{FrameWork} +\label{module-FrameWork} + +The \code{FrameWork} module contains classes that together provide a +framework for an interactive Macintosh application. The programmer +builds an application by creating subclasses that override various +methods of the bases classes, thereby implementing the functionality +wanted. Overriding functionality can often be done on various +different levels, i.e. to handle clicks in a single dialog window in a +non-standard way it is not necessary to override the complete event +handling. + +The \code{FrameWork} is still very much work-in-progress, and the +documentation describes only the most important functionality, and not +in the most logical manner at that. Examine the source or the examples +for more details. + +The \code{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 +creates an empty window dictionary and a menu bar with an apple menu. +\end{funcdesc} + +\begin{funcdesc}{MenuBar}{} +An object representing the menubar. This object is usually not created +by the user. +\end{funcdesc} + +\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} +An object representing a menu. Upon creation you pass the +\code{MenuBar} the menu appears in, the \var{title} string and a +position (1-based) \var{after} where the menu should appear (default: +at the end). +\end{funcdesc} + +\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} +Create a menu item object. The arguments are the menu to crate the +item it, the item title string and optionally the keyboard shortcut +and a callback routine. The callback is called with the arguments +menu-id, item number within menu (1-based), current front window and +the event record. + +In stead of a callable object the callback can also be a string. In +this case menu selection causes the lookup of a method in the topmost +window and the application. The method name is the callback string +with \code{'domenu_'} prepended. + +Calling the \code{MenuBar} \code{fixmenudimstate} method sets the +correct dimming for all menu items based on the current front window. +\end{funcdesc} + +\begin{funcdesc}{Separator}{menu} +Add a separator to the end of a menu. +\end{funcdesc} + +\begin{funcdesc}{SubMenu}{menu\, label} +Create a submenu named \var{label} under menu \var{menu}. The menu +object is returned. +\end{funcdesc} + +\begin{funcdesc}{Window}{parent} +Creates a (modeless) window. \var{Parent} is the application object to +which the window belongs. The window is not displayed until later. +\end{funcdesc} + +\begin{funcdesc}{DialogWindow}{parent} +Creates a modeless dialog window. +\end{funcdesc} + +\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} + +\begin{funcdesc}{setwatchcursor}{} +Set the mouse cursor to a watch. +\end{funcdesc} + +\begin{funcdesc}{setarrowcursor}{} +Set the mouse cursor to an arrow. +\end{funcdesc} + +\subsection{Application objects} +Application objects have the following methods, among others: + +\setindexsubitem{(Application method)} + +\begin{funcdesc}{makeusermenus}{} +Override this method if you need menus in your application. Append the +menus to \code{self.menubar}. +\end{funcdesc} + +\begin{funcdesc}{getabouttext}{} +Override this method to return a text string describing your +application. Alternatively, override the \code{do_about} method for +more elaborate about messages. +\end{funcdesc} + +\begin{funcdesc}{mainloop}{\optional{mask\, wait}} +This routine is the main event loop, call it to set your application +rolling. \var{Mask} is the mask of events you want to handle, +\var{wait} is the number of ticks you want to leave to other +concurrent application (default 0, which is probably not a good +idea). While raising \code{self} to exit the mainloop is still +supported it is not recommended, call \code{self._quit} instead. + +The event loop is split into many small parts, each of which can be +overridden. The default methods take care of dispatching events to +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 +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. +\end{funcdesc} + +\begin{funcdesc}{asyncevents}{onoff} +Call this method with a nonzero parameter to enable +asynchronous event handling. This will tell the inner interpreter loop +to call the application event handler \var{async_dispatch} whenever events +are available. This will cause FrameWork window updates and the user +interface to remain working during long computations, but will slow the +interpreter down and may cause surprising results in non-reentrant code +(such as FrameWork itself). By default \var{async_dispatch} will immedeately +call \var{our_dispatch} but you may override this to handle only certain +events asynchronously. Events you do not handle will be passed to Sioux +and such. + +The old on/off value is returned. +\end{funcdesc} + +\begin{funcdesc}{_quit}{} +Terminate the event \code{mainloop} at the next convenient moment. +\end{funcdesc} + +\begin{funcdesc}{do_char}{c\, event} +The user typed character \var{c}. The complete details of the event +can be found in the \var{event} structure. This method can also be +provided in a \code{Window} object, which overrides the +application-wide handler if the window is frontmost. +\end{funcdesc} + +\begin{funcdesc}{do_dialogevent}{event} +Called early in the event loop to handle modeless dialog events. The +default method simply dispatches the event to the relevant dialog (not +through the the \code{DialogWindow} object involved). Override if you +need special handling of dialog events (keyboard shortcuts, etc). +\end{funcdesc} + +\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} + +Window objects have the following methods, among others: + +\setindexsubitem{(Window method)} + +\begin{funcdesc}{open}{} +Override this method to open a window. Store the MacOS window-id in +\code{self.wid} and call \code{self.do_postopen} to register the +window with the parent application. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Override this method to do any special processing on window +close. Call \code{self.do_postclose} to cleanup the parent state. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} +Called after the window is resized. Override if more needs to be done +than calling \code{InvalRect}. +\end{funcdesc} + +\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} +The user clicked in the content part of a window. The arguments are +the coordinates (window-relative), the key modifiers and the raw +event. +\end{funcdesc} + +\begin{funcdesc}{do_update}{macoswindowid\, event} +An update event for the window was received. Redraw the window. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{activate\, event} +The window was activated (\code{activate==1}) or deactivated +(\code{activate==0}). Handle things like focus highlighting, etc. +\end{funcdesc} + +\subsection{ControlsWindow Object} + +ControlsWindow objects have the following methods besides those of +\code{Window} objects: + +\setindexsubitem{(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 methods: + +\setindexsubitem{(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 +\code{Window} objects: + +\setindexsubitem{(DialogWindow method)} + +\begin{funcdesc}{open}{resid} +Create the dialog window, from the DLOG resource with id +\var{resid}. The dialog object is stored in \code{self.wid}. +\end{funcdesc} + +\begin{funcdesc}{do_itemhit}{item\, event} +Item number \var{item} was hit. You are responsible for redrawing +toggle buttons, etc. +\end{funcdesc} diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex index eb11e14..546065f 100644 --- a/Doc/libmacui.tex +++ b/Doc/libmacui.tex @@ -53,354 +53,3 @@ crashes. Also, all dialogs are modeless and hence expect to be at the top of the stacking order. This is true when the dialogs are created, but windows that pop-up later (like a console window) may also result in crashes. - - -\section{Standard Module \sectcode{FrameWork}} -\stmodindex{FrameWork} -\label{module-FrameWork} - -The \code{FrameWork} module contains classes that together provide a -framework for an interactive Macintosh application. The programmer -builds an application by creating subclasses that override various -methods of the bases classes, thereby implementing the functionality -wanted. Overriding functionality can often be done on various -different levels, i.e. to handle clicks in a single dialog window in a -non-standard way it is not necessary to override the complete event -handling. - -The \code{FrameWork} is still very much work-in-progress, and the -documentation describes only the most important functionality, and not -in the most logical manner at that. Examine the source or the examples -for more details. - -The \code{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 -creates an empty window dictionary and a menu bar with an apple menu. -\end{funcdesc} - -\begin{funcdesc}{MenuBar}{} -An object representing the menubar. This object is usually not created -by the user. -\end{funcdesc} - -\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} -An object representing a menu. Upon creation you pass the -\code{MenuBar} the menu appears in, the \var{title} string and a -position (1-based) \var{after} where the menu should appear (default: -at the end). -\end{funcdesc} - -\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} -Create a menu item object. The arguments are the menu to crate the -item it, the item title string and optionally the keyboard shortcut -and a callback routine. The callback is called with the arguments -menu-id, item number within menu (1-based), current front window and -the event record. - -In stead of a callable object the callback can also be a string. In -this case menu selection causes the lookup of a method in the topmost -window and the application. The method name is the callback string -with \code{'domenu_'} prepended. - -Calling the \code{MenuBar} \code{fixmenudimstate} method sets the -correct dimming for all menu items based on the current front window. -\end{funcdesc} - -\begin{funcdesc}{Separator}{menu} -Add a separator to the end of a menu. -\end{funcdesc} - -\begin{funcdesc}{SubMenu}{menu\, label} -Create a submenu named \var{label} under menu \var{menu}. The menu -object is returned. -\end{funcdesc} - -\begin{funcdesc}{Window}{parent} -Creates a (modeless) window. \var{Parent} is the application object to -which the window belongs. The window is not displayed until later. -\end{funcdesc} - -\begin{funcdesc}{DialogWindow}{parent} -Creates a modeless dialog window. -\end{funcdesc} - -\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} - -\begin{funcdesc}{setwatchcursor}{} -Set the mouse cursor to a watch. -\end{funcdesc} - -\begin{funcdesc}{setarrowcursor}{} -Set the mouse cursor to an arrow. -\end{funcdesc} - -\subsection{Application objects} -Application objects have the following methods, among others: - -\setindexsubitem{(Application method)} - -\begin{funcdesc}{makeusermenus}{} -Override this method if you need menus in your application. Append the -menus to \code{self.menubar}. -\end{funcdesc} - -\begin{funcdesc}{getabouttext}{} -Override this method to return a text string describing your -application. Alternatively, override the \code{do_about} method for -more elaborate about messages. -\end{funcdesc} - -\begin{funcdesc}{mainloop}{\optional{mask\, wait}} -This routine is the main event loop, call it to set your application -rolling. \var{Mask} is the mask of events you want to handle, -\var{wait} is the number of ticks you want to leave to other -concurrent application (default 0, which is probably not a good -idea). While raising \code{self} to exit the mainloop is still -supported it is not recommended, call \code{self._quit} instead. - -The event loop is split into many small parts, each of which can be -overridden. The default methods take care of dispatching events to -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 -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. -\end{funcdesc} - -\begin{funcdesc}{asyncevents}{onoff} -Call this method with a nonzero parameter to enable -asynchronous event handling. This will tell the inner interpreter loop -to call the application event handler \var{async_dispatch} whenever events -are available. This will cause FrameWork window updates and the user -interface to remain working during long computations, but will slow the -interpreter down and may cause surprising results in non-reentrant code -(such as FrameWork itself). By default \var{async_dispatch} will immedeately -call \var{our_dispatch} but you may override this to handle only certain -events asynchronously. Events you do not handle will be passed to Sioux -and such. - -The old on/off value is returned. -\end{funcdesc} - -\begin{funcdesc}{_quit}{} -Terminate the event \code{mainloop} at the next convenient moment. -\end{funcdesc} - -\begin{funcdesc}{do_char}{c\, event} -The user typed character \var{c}. The complete details of the event -can be found in the \var{event} structure. This method can also be -provided in a \code{Window} object, which overrides the -application-wide handler if the window is frontmost. -\end{funcdesc} - -\begin{funcdesc}{do_dialogevent}{event} -Called early in the event loop to handle modeless dialog events. The -default method simply dispatches the event to the relevant dialog (not -through the the \code{DialogWindow} object involved). Override if you -need special handling of dialog events (keyboard shortcuts, etc). -\end{funcdesc} - -\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} - -Window objects have the following methods, among others: - -\setindexsubitem{(Window method)} - -\begin{funcdesc}{open}{} -Override this method to open a window. Store the MacOS window-id in -\code{self.wid} and call \code{self.do_postopen} to register the -window with the parent application. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Override this method to do any special processing on window -close. Call \code{self.do_postclose} to cleanup the parent state. -\end{funcdesc} - -\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} -Called after the window is resized. Override if more needs to be done -than calling \code{InvalRect}. -\end{funcdesc} - -\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} -The user clicked in the content part of a window. The arguments are -the coordinates (window-relative), the key modifiers and the raw -event. -\end{funcdesc} - -\begin{funcdesc}{do_update}{macoswindowid\, event} -An update event for the window was received. Redraw the window. -\end{funcdesc} - -\begin{funcdesc}{do_activate}{activate\, event} -The window was activated (\code{activate==1}) or deactivated -(\code{activate==0}). Handle things like focus highlighting, etc. -\end{funcdesc} - -\subsection{ControlsWindow Object} - -ControlsWindow objects have the following methods besides those of -\code{Window} objects: - -\setindexsubitem{(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 methods: - -\setindexsubitem{(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 -\code{Window} objects: - -\setindexsubitem{(DialogWindow method)} - -\begin{funcdesc}{open}{resid} -Create the dialog window, from the DLOG resource with id -\var{resid}. The dialog object is stored in \code{self.wid}. -\end{funcdesc} - -\begin{funcdesc}{do_itemhit}{item\, event} -Item number \var{item} was hit. You are responsible for redrawing -toggle buttons, etc. -\end{funcdesc} - -\section{Standard Module \sectcode{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. - -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: - -\setindexsubitem{(in module MiniAEFrame)} - -\begin{funcdesc}{AEServer}{} -A class that handles AppleEvent dispatch. Your application should -subclass this class together with either -\code{MiniAEFrame.MiniApplication} or -\code{FrameWork.Application}. Your \code{__init__} method should call -the \code{__init__} method for both classes. -\end{funcdesc} - -\begin{funcdesc}{MiniApplication}{} -A class that is more or less compatible with -\code{FrameWork.Application} but with less functionality. Its -eventloop supports the apple menu, command-dot and AppleEvents, other -events are passed on to the Python interpreter and/or Sioux. -Useful if your application wants to use \code{AEServer} but does not -provide its own windows, etc. -\end{funcdesc} - -\subsection{AEServer Objects} - -\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 -decoded and your callback is invoked. -\end{funcdesc} - -\begin{funcdesc}{callback}{_object\, **kwargs} -Your callback is called with the OSA Direct Object as first positional -parameter. The other parameters are passed as keyword arguments, with -the 4-char designator as name. Three extra keyword parameters are -passed: \code{_class} and \code{_type} are the Class and Type -designators and \code{_attributes} is a dictionary with the AppleEvent -attributes. - -The return value of your method is packed with -\code{aetools.packevent} and sent as reply. -\end{funcdesc} - -Note that there are some serious problems with the current -design. AppleEvents which have non-identifier 4-char designators for -arguments are not implementable, and it is not possible to return an -error to the originator. This will be addressed in a future release. diff --git a/Doc/libminiae.tex b/Doc/libminiae.tex new file mode 100644 index 0000000..00666fa --- /dev/null +++ b/Doc/libminiae.tex @@ -0,0 +1,61 @@ +\section{Standard Module \sectcode{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. + +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: + +\setindexsubitem{(in module MiniAEFrame)} + +\begin{funcdesc}{AEServer}{} +A class that handles AppleEvent dispatch. Your application should +subclass this class together with either +\code{MiniAEFrame.MiniApplication} or +\code{FrameWork.Application}. Your \code{__init__} method should call +the \code{__init__} method for both classes. +\end{funcdesc} + +\begin{funcdesc}{MiniApplication}{} +A class that is more or less compatible with +\code{FrameWork.Application} but with less functionality. Its +eventloop supports the apple menu, command-dot and AppleEvents, other +events are passed on to the Python interpreter and/or Sioux. +Useful if your application wants to use \code{AEServer} but does not +provide its own windows, etc. +\end{funcdesc} + +\subsection{AEServer Objects} + +\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 +decoded and your callback is invoked. +\end{funcdesc} + +\begin{funcdesc}{callback}{_object\, **kwargs} +Your callback is called with the OSA Direct Object as first positional +parameter. The other parameters are passed as keyword arguments, with +the 4-char designator as name. Three extra keyword parameters are +passed: \code{_class} and \code{_type} are the Class and Type +designators and \code{_attributes} is a dictionary with the AppleEvent +attributes. + +The return value of your method is packed with +\code{aetools.packevent} and sent as reply. +\end{funcdesc} + +Note that there are some serious problems with the current +design. AppleEvents which have non-identifier 4-char designators for +arguments are not implementable, and it is not possible to return an +error to the originator. This will be addressed in a future release. diff --git a/Doc/mac/libframework.tex b/Doc/mac/libframework.tex new file mode 100644 index 0000000..012b8c5 --- /dev/null +++ b/Doc/mac/libframework.tex @@ -0,0 +1,287 @@ +\section{Standard Module \sectcode{FrameWork}} +\stmodindex{FrameWork} +\label{module-FrameWork} + +The \code{FrameWork} module contains classes that together provide a +framework for an interactive Macintosh application. The programmer +builds an application by creating subclasses that override various +methods of the bases classes, thereby implementing the functionality +wanted. Overriding functionality can often be done on various +different levels, i.e. to handle clicks in a single dialog window in a +non-standard way it is not necessary to override the complete event +handling. + +The \code{FrameWork} is still very much work-in-progress, and the +documentation describes only the most important functionality, and not +in the most logical manner at that. Examine the source or the examples +for more details. + +The \code{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 +creates an empty window dictionary and a menu bar with an apple menu. +\end{funcdesc} + +\begin{funcdesc}{MenuBar}{} +An object representing the menubar. This object is usually not created +by the user. +\end{funcdesc} + +\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} +An object representing a menu. Upon creation you pass the +\code{MenuBar} the menu appears in, the \var{title} string and a +position (1-based) \var{after} where the menu should appear (default: +at the end). +\end{funcdesc} + +\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} +Create a menu item object. The arguments are the menu to crate the +item it, the item title string and optionally the keyboard shortcut +and a callback routine. The callback is called with the arguments +menu-id, item number within menu (1-based), current front window and +the event record. + +In stead of a callable object the callback can also be a string. In +this case menu selection causes the lookup of a method in the topmost +window and the application. The method name is the callback string +with \code{'domenu_'} prepended. + +Calling the \code{MenuBar} \code{fixmenudimstate} method sets the +correct dimming for all menu items based on the current front window. +\end{funcdesc} + +\begin{funcdesc}{Separator}{menu} +Add a separator to the end of a menu. +\end{funcdesc} + +\begin{funcdesc}{SubMenu}{menu\, label} +Create a submenu named \var{label} under menu \var{menu}. The menu +object is returned. +\end{funcdesc} + +\begin{funcdesc}{Window}{parent} +Creates a (modeless) window. \var{Parent} is the application object to +which the window belongs. The window is not displayed until later. +\end{funcdesc} + +\begin{funcdesc}{DialogWindow}{parent} +Creates a modeless dialog window. +\end{funcdesc} + +\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} + +\begin{funcdesc}{setwatchcursor}{} +Set the mouse cursor to a watch. +\end{funcdesc} + +\begin{funcdesc}{setarrowcursor}{} +Set the mouse cursor to an arrow. +\end{funcdesc} + +\subsection{Application objects} +Application objects have the following methods, among others: + +\setindexsubitem{(Application method)} + +\begin{funcdesc}{makeusermenus}{} +Override this method if you need menus in your application. Append the +menus to \code{self.menubar}. +\end{funcdesc} + +\begin{funcdesc}{getabouttext}{} +Override this method to return a text string describing your +application. Alternatively, override the \code{do_about} method for +more elaborate about messages. +\end{funcdesc} + +\begin{funcdesc}{mainloop}{\optional{mask\, wait}} +This routine is the main event loop, call it to set your application +rolling. \var{Mask} is the mask of events you want to handle, +\var{wait} is the number of ticks you want to leave to other +concurrent application (default 0, which is probably not a good +idea). While raising \code{self} to exit the mainloop is still +supported it is not recommended, call \code{self._quit} instead. + +The event loop is split into many small parts, each of which can be +overridden. The default methods take care of dispatching events to +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 +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. +\end{funcdesc} + +\begin{funcdesc}{asyncevents}{onoff} +Call this method with a nonzero parameter to enable +asynchronous event handling. This will tell the inner interpreter loop +to call the application event handler \var{async_dispatch} whenever events +are available. This will cause FrameWork window updates and the user +interface to remain working during long computations, but will slow the +interpreter down and may cause surprising results in non-reentrant code +(such as FrameWork itself). By default \var{async_dispatch} will immedeately +call \var{our_dispatch} but you may override this to handle only certain +events asynchronously. Events you do not handle will be passed to Sioux +and such. + +The old on/off value is returned. +\end{funcdesc} + +\begin{funcdesc}{_quit}{} +Terminate the event \code{mainloop} at the next convenient moment. +\end{funcdesc} + +\begin{funcdesc}{do_char}{c\, event} +The user typed character \var{c}. The complete details of the event +can be found in the \var{event} structure. This method can also be +provided in a \code{Window} object, which overrides the +application-wide handler if the window is frontmost. +\end{funcdesc} + +\begin{funcdesc}{do_dialogevent}{event} +Called early in the event loop to handle modeless dialog events. The +default method simply dispatches the event to the relevant dialog (not +through the the \code{DialogWindow} object involved). Override if you +need special handling of dialog events (keyboard shortcuts, etc). +\end{funcdesc} + +\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} + +Window objects have the following methods, among others: + +\setindexsubitem{(Window method)} + +\begin{funcdesc}{open}{} +Override this method to open a window. Store the MacOS window-id in +\code{self.wid} and call \code{self.do_postopen} to register the +window with the parent application. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Override this method to do any special processing on window +close. Call \code{self.do_postclose} to cleanup the parent state. +\end{funcdesc} + +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} +Called after the window is resized. Override if more needs to be done +than calling \code{InvalRect}. +\end{funcdesc} + +\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} +The user clicked in the content part of a window. The arguments are +the coordinates (window-relative), the key modifiers and the raw +event. +\end{funcdesc} + +\begin{funcdesc}{do_update}{macoswindowid\, event} +An update event for the window was received. Redraw the window. +\end{funcdesc} + +\begin{funcdesc}{do_activate}{activate\, event} +The window was activated (\code{activate==1}) or deactivated +(\code{activate==0}). Handle things like focus highlighting, etc. +\end{funcdesc} + +\subsection{ControlsWindow Object} + +ControlsWindow objects have the following methods besides those of +\code{Window} objects: + +\setindexsubitem{(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 methods: + +\setindexsubitem{(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 +\code{Window} objects: + +\setindexsubitem{(DialogWindow method)} + +\begin{funcdesc}{open}{resid} +Create the dialog window, from the DLOG resource with id +\var{resid}. The dialog object is stored in \code{self.wid}. +\end{funcdesc} + +\begin{funcdesc}{do_itemhit}{item\, event} +Item number \var{item} was hit. You are responsible for redrawing +toggle buttons, etc. +\end{funcdesc} diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex index eb11e14..546065f 100644 --- a/Doc/mac/libmacui.tex +++ b/Doc/mac/libmacui.tex @@ -53,354 +53,3 @@ crashes. Also, all dialogs are modeless and hence expect to be at the top of the stacking order. This is true when the dialogs are created, but windows that pop-up later (like a console window) may also result in crashes. - - -\section{Standard Module \sectcode{FrameWork}} -\stmodindex{FrameWork} -\label{module-FrameWork} - -The \code{FrameWork} module contains classes that together provide a -framework for an interactive Macintosh application. The programmer -builds an application by creating subclasses that override various -methods of the bases classes, thereby implementing the functionality -wanted. Overriding functionality can often be done on various -different levels, i.e. to handle clicks in a single dialog window in a -non-standard way it is not necessary to override the complete event -handling. - -The \code{FrameWork} is still very much work-in-progress, and the -documentation describes only the most important functionality, and not -in the most logical manner at that. Examine the source or the examples -for more details. - -The \code{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 -creates an empty window dictionary and a menu bar with an apple menu. -\end{funcdesc} - -\begin{funcdesc}{MenuBar}{} -An object representing the menubar. This object is usually not created -by the user. -\end{funcdesc} - -\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} -An object representing a menu. Upon creation you pass the -\code{MenuBar} the menu appears in, the \var{title} string and a -position (1-based) \var{after} where the menu should appear (default: -at the end). -\end{funcdesc} - -\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} -Create a menu item object. The arguments are the menu to crate the -item it, the item title string and optionally the keyboard shortcut -and a callback routine. The callback is called with the arguments -menu-id, item number within menu (1-based), current front window and -the event record. - -In stead of a callable object the callback can also be a string. In -this case menu selection causes the lookup of a method in the topmost -window and the application. The method name is the callback string -with \code{'domenu_'} prepended. - -Calling the \code{MenuBar} \code{fixmenudimstate} method sets the -correct dimming for all menu items based on the current front window. -\end{funcdesc} - -\begin{funcdesc}{Separator}{menu} -Add a separator to the end of a menu. -\end{funcdesc} - -\begin{funcdesc}{SubMenu}{menu\, label} -Create a submenu named \var{label} under menu \var{menu}. The menu -object is returned. -\end{funcdesc} - -\begin{funcdesc}{Window}{parent} -Creates a (modeless) window. \var{Parent} is the application object to -which the window belongs. The window is not displayed until later. -\end{funcdesc} - -\begin{funcdesc}{DialogWindow}{parent} -Creates a modeless dialog window. -\end{funcdesc} - -\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} - -\begin{funcdesc}{setwatchcursor}{} -Set the mouse cursor to a watch. -\end{funcdesc} - -\begin{funcdesc}{setarrowcursor}{} -Set the mouse cursor to an arrow. -\end{funcdesc} - -\subsection{Application objects} -Application objects have the following methods, among others: - -\setindexsubitem{(Application method)} - -\begin{funcdesc}{makeusermenus}{} -Override this method if you need menus in your application. Append the -menus to \code{self.menubar}. -\end{funcdesc} - -\begin{funcdesc}{getabouttext}{} -Override this method to return a text string describing your -application. Alternatively, override the \code{do_about} method for -more elaborate about messages. -\end{funcdesc} - -\begin{funcdesc}{mainloop}{\optional{mask\, wait}} -This routine is the main event loop, call it to set your application -rolling. \var{Mask} is the mask of events you want to handle, -\var{wait} is the number of ticks you want to leave to other -concurrent application (default 0, which is probably not a good -idea). While raising \code{self} to exit the mainloop is still -supported it is not recommended, call \code{self._quit} instead. - -The event loop is split into many small parts, each of which can be -overridden. The default methods take care of dispatching events to -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 -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. -\end{funcdesc} - -\begin{funcdesc}{asyncevents}{onoff} -Call this method with a nonzero parameter to enable -asynchronous event handling. This will tell the inner interpreter loop -to call the application event handler \var{async_dispatch} whenever events -are available. This will cause FrameWork window updates and the user -interface to remain working during long computations, but will slow the -interpreter down and may cause surprising results in non-reentrant code -(such as FrameWork itself). By default \var{async_dispatch} will immedeately -call \var{our_dispatch} but you may override this to handle only certain -events asynchronously. Events you do not handle will be passed to Sioux -and such. - -The old on/off value is returned. -\end{funcdesc} - -\begin{funcdesc}{_quit}{} -Terminate the event \code{mainloop} at the next convenient moment. -\end{funcdesc} - -\begin{funcdesc}{do_char}{c\, event} -The user typed character \var{c}. The complete details of the event -can be found in the \var{event} structure. This method can also be -provided in a \code{Window} object, which overrides the -application-wide handler if the window is frontmost. -\end{funcdesc} - -\begin{funcdesc}{do_dialogevent}{event} -Called early in the event loop to handle modeless dialog events. The -default method simply dispatches the event to the relevant dialog (not -through the the \code{DialogWindow} object involved). Override if you -need special handling of dialog events (keyboard shortcuts, etc). -\end{funcdesc} - -\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} - -Window objects have the following methods, among others: - -\setindexsubitem{(Window method)} - -\begin{funcdesc}{open}{} -Override this method to open a window. Store the MacOS window-id in -\code{self.wid} and call \code{self.do_postopen} to register the -window with the parent application. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Override this method to do any special processing on window -close. Call \code{self.do_postclose} to cleanup the parent state. -\end{funcdesc} - -\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} -Called after the window is resized. Override if more needs to be done -than calling \code{InvalRect}. -\end{funcdesc} - -\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} -The user clicked in the content part of a window. The arguments are -the coordinates (window-relative), the key modifiers and the raw -event. -\end{funcdesc} - -\begin{funcdesc}{do_update}{macoswindowid\, event} -An update event for the window was received. Redraw the window. -\end{funcdesc} - -\begin{funcdesc}{do_activate}{activate\, event} -The window was activated (\code{activate==1}) or deactivated -(\code{activate==0}). Handle things like focus highlighting, etc. -\end{funcdesc} - -\subsection{ControlsWindow Object} - -ControlsWindow objects have the following methods besides those of -\code{Window} objects: - -\setindexsubitem{(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 methods: - -\setindexsubitem{(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 -\code{Window} objects: - -\setindexsubitem{(DialogWindow method)} - -\begin{funcdesc}{open}{resid} -Create the dialog window, from the DLOG resource with id -\var{resid}. The dialog object is stored in \code{self.wid}. -\end{funcdesc} - -\begin{funcdesc}{do_itemhit}{item\, event} -Item number \var{item} was hit. You are responsible for redrawing -toggle buttons, etc. -\end{funcdesc} - -\section{Standard Module \sectcode{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. - -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: - -\setindexsubitem{(in module MiniAEFrame)} - -\begin{funcdesc}{AEServer}{} -A class that handles AppleEvent dispatch. Your application should -subclass this class together with either -\code{MiniAEFrame.MiniApplication} or -\code{FrameWork.Application}. Your \code{__init__} method should call -the \code{__init__} method for both classes. -\end{funcdesc} - -\begin{funcdesc}{MiniApplication}{} -A class that is more or less compatible with -\code{FrameWork.Application} but with less functionality. Its -eventloop supports the apple menu, command-dot and AppleEvents, other -events are passed on to the Python interpreter and/or Sioux. -Useful if your application wants to use \code{AEServer} but does not -provide its own windows, etc. -\end{funcdesc} - -\subsection{AEServer Objects} - -\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 -decoded and your callback is invoked. -\end{funcdesc} - -\begin{funcdesc}{callback}{_object\, **kwargs} -Your callback is called with the OSA Direct Object as first positional -parameter. The other parameters are passed as keyword arguments, with -the 4-char designator as name. Three extra keyword parameters are -passed: \code{_class} and \code{_type} are the Class and Type -designators and \code{_attributes} is a dictionary with the AppleEvent -attributes. - -The return value of your method is packed with -\code{aetools.packevent} and sent as reply. -\end{funcdesc} - -Note that there are some serious problems with the current -design. AppleEvents which have non-identifier 4-char designators for -arguments are not implementable, and it is not possible to return an -error to the originator. This will be addressed in a future release. diff --git a/Doc/mac/libminiae.tex b/Doc/mac/libminiae.tex new file mode 100644 index 0000000..00666fa --- /dev/null +++ b/Doc/mac/libminiae.tex @@ -0,0 +1,61 @@ +\section{Standard Module \sectcode{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. + +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: + +\setindexsubitem{(in module MiniAEFrame)} + +\begin{funcdesc}{AEServer}{} +A class that handles AppleEvent dispatch. Your application should +subclass this class together with either +\code{MiniAEFrame.MiniApplication} or +\code{FrameWork.Application}. Your \code{__init__} method should call +the \code{__init__} method for both classes. +\end{funcdesc} + +\begin{funcdesc}{MiniApplication}{} +A class that is more or less compatible with +\code{FrameWork.Application} but with less functionality. Its +eventloop supports the apple menu, command-dot and AppleEvents, other +events are passed on to the Python interpreter and/or Sioux. +Useful if your application wants to use \code{AEServer} but does not +provide its own windows, etc. +\end{funcdesc} + +\subsection{AEServer Objects} + +\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 +decoded and your callback is invoked. +\end{funcdesc} + +\begin{funcdesc}{callback}{_object\, **kwargs} +Your callback is called with the OSA Direct Object as first positional +parameter. The other parameters are passed as keyword arguments, with +the 4-char designator as name. Three extra keyword parameters are +passed: \code{_class} and \code{_type} are the Class and Type +designators and \code{_attributes} is a dictionary with the AppleEvent +attributes. + +The return value of your method is packed with +\code{aetools.packevent} and sent as reply. +\end{funcdesc} + +Note that there are some serious problems with the current +design. AppleEvents which have non-identifier 4-char designators for +arguments are not implementable, and it is not possible to return an +error to the originator. This will be addressed in a future release. |