diff options
Diffstat (limited to 'Doc/libframework.tex')
| -rw-r--r-- | Doc/libframework.tex | 294 |
1 files changed, 0 insertions, 294 deletions
diff --git a/Doc/libframework.tex b/Doc/libframework.tex deleted file mode 100644 index 5bd2e2a..0000000 --- a/Doc/libframework.tex +++ /dev/null @@ -1,294 +0,0 @@ -\section{Standard Module \module{FrameWork}} -\stmodindex{FrameWork} -\label{module-FrameWork} - -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 -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 \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 \module{FrameWork} module defines the following functions: - - -\begin{funcdesc}{Application}{} -An object representing the complete application. See below for a -description of the methods. The default \method{__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} -\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 the attribute \member{menubar}. -\end{funcdesc} - -\begin{funcdesc}{getabouttext}{} -Override this method to return a text string describing your -application. Alternatively, override the \method{do_about()} method -for more elaborate ``about'' messages. -\end{funcdesc} - -\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 -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 \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 \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} -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 running \method{mainloop()} call 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} -\label{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} -\label{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} -\label{scrolledwindow-object} - -ScrolledWindow objects are ControlsWindow objects with the following -extra methods: - -\setindexsubitem{(ScrolledWindow method)} - -\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{(\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 -\method{getscrollbarvalues()} and update the scrollbars. -\end{funcdesc} - -\begin{funcdesc}{scrollbar_callback}{which, what, value} -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'}, \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 -\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} - -\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} -\label{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} |