| \section{Standard Module \sectcode{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} |