diff options
Diffstat (limited to 'Doc/mac/libframework.tex')
| -rw-r--r-- | Doc/mac/libframework.tex | 312 |
1 files changed, 0 insertions, 312 deletions
diff --git a/Doc/mac/libframework.tex b/Doc/mac/libframework.tex deleted file mode 100644 index edc76c1..0000000 --- a/Doc/mac/libframework.tex +++ /dev/null @@ -1,312 +0,0 @@ -\section{\module{FrameWork} --- - Interactive application framework} - -\declaremodule{standard}{FrameWork} - \platform{Mac} -\modulesynopsis{Interactive application 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. - -Work on the \module{FrameWork} has pretty much stopped, now that -\module{PyObjC} is available for full Cocoa access from Python, 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 following are some comments posted on the -MacPython newsgroup about the strengths and limitations of -\module{FrameWork}: - -\begin{quotation} -The strong point of \module{FrameWork} is that it allows you to break -into the control-flow at many different places. \refmodule{W}, for -instance, uses a different way to enable/disable menus and that plugs -right in leaving the rest intact. The weak points of -\module{FrameWork} are that it has no abstract command interface (but -that shouldn't be difficult), that its dialog support is minimal and -that its control/toolbar support is non-existent. -\end{quotation} - - -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 create, 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. - -Instead 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} \method{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{(\var{left}, \var{top}, \var{right}, \var{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. However, the window will -however always be the exact 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: - - -\begin{methoddesc}[Application]{makeusermenus}{} -Override this method if you need menus in your application. Append the -menus to the attribute \member{menubar}. -\end{methoddesc} - -\begin{methoddesc}[Application]{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{methoddesc} - -\begin{methoddesc}[Application]{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 \var{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{methoddesc} - -\begin{methoddesc}[Application]{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 immediately -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{methoddesc} - -\begin{methoddesc}[Application]{_quit}{} -Terminate the running \method{mainloop()} call at the next convenient -moment. -\end{methoddesc} - -\begin{methoddesc}[Application]{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{methoddesc} - -\begin{methoddesc}[Application]{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 \code{DialogWindow} object involved). Override if you -need special handling of dialog events (keyboard shortcuts, etc). -\end{methoddesc} - -\begin{methoddesc}[Application]{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{methoddesc} - - -\subsection{Window Objects \label{window-objects}} - -Window objects have the following methods, among others: - -\begin{methoddesc}[Window]{open}{} -Override this method to open a window. Store the MacOS window-id in -\member{self.wid} and call the \method{do_postopen()} method to -register the window with the parent application. -\end{methoddesc} - -\begin{methoddesc}[Window]{close}{} -Override this method to do any special processing on window -close. Call the \method{do_postclose()} method to cleanup the parent -state. -\end{methoddesc} - -\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid} -Called after the window is resized. Override if more needs to be done -than calling \code{InvalRect}. -\end{methoddesc} - -\begin{methoddesc}[Window]{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{methoddesc} - -\begin{methoddesc}[Window]{do_update}{macoswindowid, event} -An update event for the window was received. Redraw the window. -\end{methoddesc} - -\begin{methoddesc}[Window]{do_activate}{activate, event} -The window was activated (\code{\var{activate} == 1}) or deactivated -(\code{\var{activate} == 0}). Handle things like focus highlighting, -etc. -\end{methoddesc} - - -\subsection{ControlsWindow Object \label{controlswindow-object}} - -ControlsWindow objects have the following methods besides those of -\code{Window} objects: - - -\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control, - pcode, event} -Part \var{pcode} of control \var{control} was hit by the -user. Tracking and such has already been taken care of. -\end{methoddesc} - - -\subsection{ScrolledWindow Object \label{scrolledwindow-object}} - -ScrolledWindow objects are ControlsWindow objects with the following -extra methods: - - -\begin{methoddesc}[ScrolledWindow]{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{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{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{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{} -Call this method when the document has changed. It will call -\method{getscrollbarvalues()} and update the scrollbars. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{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{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{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{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{do_activate}{onoff, event} -Takes care of dimming/highlighting scrollbars when a window becomes -frontmost. If you override this method, call this one at the end of -your method. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window} -Moves scrollbars to the correct position. Call this method initially -if you override it. -\end{methoddesc} - -\begin{methoddesc}[ScrolledWindow]{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{methoddesc} - - -\subsection{DialogWindow Objects \label{dialogwindow-objects}} - -DialogWindow objects have the following methods besides those of -\code{Window} objects: - - -\begin{methoddesc}[DialogWindow]{open}{resid} -Create the dialog window, from the DLOG resource with id -\var{resid}. The dialog object is stored in \member{self.wid}. -\end{methoddesc} - -\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event} -Item number \var{item} was hit. You are responsible for redrawing -toggle buttons, etc. -\end{methoddesc} |