blob: 8723d7302e8d3103e9306c637b12b59c2da63735 [file] [log] [blame]
Fred Drakec817e271998-08-10 18:40:22 +00001\section{\module{FrameWork} ---
Fred Drakef6863c11999-03-02 16:37:17 +00002 Interactive application framework}
Fred Drakefe7f3bc1998-07-23 17:55:31 +00003
Fred Drakef6863c11999-03-02 16:37:17 +00004\declaremodule{standard}{FrameWork}
5 \platform{Mac}
Fred Drakefe7f3bc1998-07-23 17:55:31 +00006\modulesynopsis{Interactive application framework.}
7
Fred Drakeb4efb6c1998-02-18 17:19:11 +00008
Fred Drake41788db1998-04-04 06:23:02 +00009The \module{FrameWork} module contains classes that together provide a
Fred Drakeb4efb6c1998-02-18 17:19:11 +000010framework for an interactive Macintosh application. The programmer
11builds an application by creating subclasses that override various
12methods of the bases classes, thereby implementing the functionality
13wanted. Overriding functionality can often be done on various
14different levels, i.e. to handle clicks in a single dialog window in a
15non-standard way it is not necessary to override the complete event
16handling.
17
Fred Drake41788db1998-04-04 06:23:02 +000018The \module{FrameWork} is still very much work-in-progress, and the
Fred Drakeb4efb6c1998-02-18 17:19:11 +000019documentation describes only the most important functionality, and not
20in the most logical manner at that. Examine the source or the examples
Fred Drake658865c2000-10-14 04:53:31 +000021for more details. The following are some comments posted on the
22MacPython newsgroup about the strengths and limitations of
23\module{FrameWork}:
24
25\begin{quotation}
26The strong point of \module{FrameWork} is that it allows you to break
27into the control-flow at many different places. \refmodule{W}, for
28instance, uses a different way to enable/disable menus and that plugs
29right in leaving the rest intact. The weak points of
30\module{FrameWork} are that it has no abstract command interface (but
31that shouldn't be difficult), that it's dialog support is minimal and
32that it's control/toolbar support is non-existent.
33\end{quotation}
34
Fred Drakeb4efb6c1998-02-18 17:19:11 +000035
Fred Drake41788db1998-04-04 06:23:02 +000036The \module{FrameWork} module defines the following functions:
Fred Drakeb4efb6c1998-02-18 17:19:11 +000037
Fred Drakeb4efb6c1998-02-18 17:19:11 +000038
39\begin{funcdesc}{Application}{}
40An object representing the complete application. See below for a
Fred Drake41788db1998-04-04 06:23:02 +000041description of the methods. The default \method{__init__()} routine
Fred Drakeb4efb6c1998-02-18 17:19:11 +000042creates an empty window dictionary and a menu bar with an apple menu.
43\end{funcdesc}
44
45\begin{funcdesc}{MenuBar}{}
46An object representing the menubar. This object is usually not created
47by the user.
48\end{funcdesc}
49
Fred Drakecce10901998-03-17 06:33:25 +000050\begin{funcdesc}{Menu}{bar, title\optional{, after}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +000051An object representing a menu. Upon creation you pass the
52\code{MenuBar} the menu appears in, the \var{title} string and a
53position (1-based) \var{after} where the menu should appear (default:
54at the end).
55\end{funcdesc}
56
Fred Drakecce10901998-03-17 06:33:25 +000057\begin{funcdesc}{MenuItem}{menu, title\optional{, shortcut, callback}}
Fred Drake658865c2000-10-14 04:53:31 +000058Create a menu item object. The arguments are the menu to create, the
59item item title string and optionally the keyboard shortcut
Fred Drakeb4efb6c1998-02-18 17:19:11 +000060and a callback routine. The callback is called with the arguments
61menu-id, item number within menu (1-based), current front window and
62the event record.
63
Fred Drake658865c2000-10-14 04:53:31 +000064Instead of a callable object the callback can also be a string. In
Fred Drakeb4efb6c1998-02-18 17:19:11 +000065this case menu selection causes the lookup of a method in the topmost
66window and the application. The method name is the callback string
67with \code{'domenu_'} prepended.
68
Fred Drakef6863c11999-03-02 16:37:17 +000069Calling the \code{MenuBar} \method{fixmenudimstate()} method sets the
Fred Drakeb4efb6c1998-02-18 17:19:11 +000070correct dimming for all menu items based on the current front window.
71\end{funcdesc}
72
73\begin{funcdesc}{Separator}{menu}
74Add a separator to the end of a menu.
75\end{funcdesc}
76
Fred Drakecce10901998-03-17 06:33:25 +000077\begin{funcdesc}{SubMenu}{menu, label}
Fred Drakeb4efb6c1998-02-18 17:19:11 +000078Create a submenu named \var{label} under menu \var{menu}. The menu
79object is returned.
80\end{funcdesc}
81
82\begin{funcdesc}{Window}{parent}
83Creates a (modeless) window. \var{Parent} is the application object to
84which the window belongs. The window is not displayed until later.
85\end{funcdesc}
86
87\begin{funcdesc}{DialogWindow}{parent}
88Creates a modeless dialog window.
89\end{funcdesc}
90
Fred Drakecce10901998-03-17 06:33:25 +000091\begin{funcdesc}{windowbounds}{width, height}
Fred Drakef6863c11999-03-02 16:37:17 +000092Return a \code{(\var{left}, \var{top}, \var{right}, \var{bottom})}
93tuple suitable for creation of a window of given width and height. The
94window will be staggered with respect to previous windows, and an
Fred Drake658865c2000-10-14 04:53:31 +000095attempt is made to keep the whole window on-screen. However, the window will
96however always be the exact size given, so parts may be offscreen.
Fred Drakeb4efb6c1998-02-18 17:19:11 +000097\end{funcdesc}
98
99\begin{funcdesc}{setwatchcursor}{}
100Set the mouse cursor to a watch.
101\end{funcdesc}
102
103\begin{funcdesc}{setarrowcursor}{}
104Set the mouse cursor to an arrow.
105\end{funcdesc}
106
Fred Drakef6863c11999-03-02 16:37:17 +0000107
108\subsection{Application Objects \label{application-objects}}
Fred Drake41788db1998-04-04 06:23:02 +0000109
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000110Application objects have the following methods, among others:
111
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000112
Fred Drakef6863c11999-03-02 16:37:17 +0000113\begin{methoddesc}[Application]{makeusermenus}{}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000114Override this method if you need menus in your application. Append the
Fred Drake41788db1998-04-04 06:23:02 +0000115menus to the attribute \member{menubar}.
Fred Drakef6863c11999-03-02 16:37:17 +0000116\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000117
Fred Drakef6863c11999-03-02 16:37:17 +0000118\begin{methoddesc}[Application]{getabouttext}{}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000119Override this method to return a text string describing your
Fred Drake41788db1998-04-04 06:23:02 +0000120application. Alternatively, override the \method{do_about()} method
121for more elaborate ``about'' messages.
Fred Drakef6863c11999-03-02 16:37:17 +0000122\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000123
Fred Drakef6863c11999-03-02 16:37:17 +0000124\begin{methoddesc}[Application]{mainloop}{\optional{mask\optional{, wait}}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000125This routine is the main event loop, call it to set your application
126rolling. \var{Mask} is the mask of events you want to handle,
127\var{wait} is the number of ticks you want to leave to other
128concurrent application (default 0, which is probably not a good
Fred Drakef6863c11999-03-02 16:37:17 +0000129idea). While raising \var{self} to exit the mainloop is still
130supported it is not recommended: call \code{self._quit()} instead.
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000131
132The event loop is split into many small parts, each of which can be
133overridden. The default methods take care of dispatching events to
134windows and dialogs, handling drags and resizes, Apple Events, events
135for non-FrameWork windows, etc.
136
Fred Drake41788db1998-04-04 06:23:02 +0000137In general, all event handlers should return \code{1} if the event is fully
138handled and \code{0} otherwise (because the front window was not a FrameWork
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000139window, for instance). This is needed so that update events and such
140can be passed on to other windows like the Sioux console window.
Fred Drake41788db1998-04-04 06:23:02 +0000141Calling \function{MacOS.HandleEvent()} is not allowed within
142\var{our_dispatch} or its callees, since this may result in an
143infinite loop if the code is called through the Python inner-loop
144event handler.
Fred Drakef6863c11999-03-02 16:37:17 +0000145\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000146
Fred Drakef6863c11999-03-02 16:37:17 +0000147\begin{methoddesc}[Application]{asyncevents}{onoff}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000148Call this method with a nonzero parameter to enable
149asynchronous event handling. This will tell the inner interpreter loop
150to call the application event handler \var{async_dispatch} whenever events
151are available. This will cause FrameWork window updates and the user
152interface to remain working during long computations, but will slow the
153interpreter down and may cause surprising results in non-reentrant code
154(such as FrameWork itself). By default \var{async_dispatch} will immedeately
155call \var{our_dispatch} but you may override this to handle only certain
156events asynchronously. Events you do not handle will be passed to Sioux
157and such.
158
159The old on/off value is returned.
Fred Drakef6863c11999-03-02 16:37:17 +0000160\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000161
Fred Drakef6863c11999-03-02 16:37:17 +0000162\begin{methoddesc}[Application]{_quit}{}
Fred Drake41788db1998-04-04 06:23:02 +0000163Terminate the running \method{mainloop()} call at the next convenient
164moment.
Fred Drakef6863c11999-03-02 16:37:17 +0000165\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000166
Fred Drakef6863c11999-03-02 16:37:17 +0000167\begin{methoddesc}[Application]{do_char}{c, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000168The user typed character \var{c}. The complete details of the event
169can be found in the \var{event} structure. This method can also be
170provided in a \code{Window} object, which overrides the
171application-wide handler if the window is frontmost.
Fred Drakef6863c11999-03-02 16:37:17 +0000172\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000173
Fred Drakef6863c11999-03-02 16:37:17 +0000174\begin{methoddesc}[Application]{do_dialogevent}{event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000175Called early in the event loop to handle modeless dialog events. The
176default method simply dispatches the event to the relevant dialog (not
177through the the \code{DialogWindow} object involved). Override if you
178need special handling of dialog events (keyboard shortcuts, etc).
Fred Drakef6863c11999-03-02 16:37:17 +0000179\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000180
Fred Drakef6863c11999-03-02 16:37:17 +0000181\begin{methoddesc}[Application]{idle}{event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000182Called by the main event loop when no events are available. The
183null-event is passed (so you can look at mouse position, etc).
Fred Drakef6863c11999-03-02 16:37:17 +0000184\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000185
Fred Drakef6863c11999-03-02 16:37:17 +0000186
187\subsection{Window Objects \label{window-objects}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000188
189Window objects have the following methods, among others:
190
191\setindexsubitem{(Window method)}
192
Fred Drakef6863c11999-03-02 16:37:17 +0000193\begin{methoddesc}[Window]{open}{}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000194Override this method to open a window. Store the MacOS window-id in
Fred Drakef6863c11999-03-02 16:37:17 +0000195\member{self.wid} and call the \method{do_postopen()} method to
196register the window with the parent application.
197\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000198
Fred Drakef6863c11999-03-02 16:37:17 +0000199\begin{methoddesc}[Window]{close}{}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000200Override this method to do any special processing on window
Fred Drakef6863c11999-03-02 16:37:17 +0000201close. Call the \method{do_postclose()} method to cleanup the parent
202state.
203\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000204
Fred Drakef6863c11999-03-02 16:37:17 +0000205\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000206Called after the window is resized. Override if more needs to be done
207than calling \code{InvalRect}.
Fred Drakef6863c11999-03-02 16:37:17 +0000208\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000209
Fred Drakef6863c11999-03-02 16:37:17 +0000210\begin{methoddesc}[Window]{do_contentclick}{local, modifiers, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000211The user clicked in the content part of a window. The arguments are
212the coordinates (window-relative), the key modifiers and the raw
213event.
Fred Drakef6863c11999-03-02 16:37:17 +0000214\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000215
Fred Drakef6863c11999-03-02 16:37:17 +0000216\begin{methoddesc}[Window]{do_update}{macoswindowid, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000217An update event for the window was received. Redraw the window.
Fred Drakef6863c11999-03-02 16:37:17 +0000218\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000219
Fred Drakef6863c11999-03-02 16:37:17 +0000220\begin{methoddesc}{do_activate}{activate, event}
221The window was activated (\code{\var{activate} == 1}) or deactivated
222(\code{\var{activate} == 0}). Handle things like focus highlighting,
223etc.
224\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000225
Fred Drakef6863c11999-03-02 16:37:17 +0000226
227\subsection{ControlsWindow Object \label{controlswindow-object}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000228
229ControlsWindow objects have the following methods besides those of
230\code{Window} objects:
231
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000232
Fred Drakef6863c11999-03-02 16:37:17 +0000233\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control,
234 pcode, event}
235Part \var{pcode} of control \var{control} was hit by the
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000236user. Tracking and such has already been taken care of.
Fred Drakef6863c11999-03-02 16:37:17 +0000237\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000238
Fred Drakef6863c11999-03-02 16:37:17 +0000239
240\subsection{ScrolledWindow Object \label{scrolledwindow-object}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000241
242ScrolledWindow objects are ControlsWindow objects with the following
243extra methods:
244
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000245
Fred Drakef6863c11999-03-02 16:37:17 +0000246\begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{,
247 wanty}}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000248Create (or destroy) horizontal and vertical scrollbars. The arguments
249specify which you want (default: both). The scrollbars always have
250minimum \code{0} and maximum \code{32767}.
Fred Drakef6863c11999-03-02 16:37:17 +0000251\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000252
Fred Drakef6863c11999-03-02 16:37:17 +0000253\begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{}
Fred Drake41788db1998-04-04 06:23:02 +0000254You must supply this method. It should return a tuple \code{(\var{x},
255\var{y})} giving the current position of the scrollbars (between
256\code{0} and \code{32767}). You can return \code{None} for either to
257indicate the whole document is visible in that direction.
Fred Drakef6863c11999-03-02 16:37:17 +0000258\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000259
Fred Drakef6863c11999-03-02 16:37:17 +0000260\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000261Call this method when the document has changed. It will call
Fred Drake41788db1998-04-04 06:23:02 +0000262\method{getscrollbarvalues()} and update the scrollbars.
Fred Drakef6863c11999-03-02 16:37:17 +0000263\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000264
Fred Drakef6863c11999-03-02 16:37:17 +0000265\begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value}
Fred Drake41788db1998-04-04 06:23:02 +0000266Supplied by you and called after user interaction. \var{which} will
267be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000268\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
Fred Drake41788db1998-04-04 06:23:02 +0000269\code{'set'}, \var{value} will contain the new scrollbar position.
Fred Drakef6863c11999-03-02 16:37:17 +0000270\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000271
Fred Drakef6863c11999-03-02 16:37:17 +0000272\begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax,
273 curmin, curmax}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000274Auxiliary method to help you calculate values to return from
Fred Drake41788db1998-04-04 06:23:02 +0000275\method{getscrollbarvalues()}. You pass document minimum and maximum value
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000276and topmost (leftmost) and bottommost (rightmost) visible values and
277it returns the correct number or \code{None}.
Fred Drakef6863c11999-03-02 16:37:17 +0000278\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000279
Fred Drakef6863c11999-03-02 16:37:17 +0000280\begin{methoddesc}[ScrolledWindow]{do_activate}{onoff, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000281Takes care of dimming/highlighting scrollbars when a window becomes
Fred Drake658865c2000-10-14 04:53:31 +0000282frontmost. If you override this method, call this one at the end of
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000283your method.
Fred Drakef6863c11999-03-02 16:37:17 +0000284\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000285
Fred Drakef6863c11999-03-02 16:37:17 +0000286\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000287Moves scrollbars to the correct position. Call this method initially
288if you override it.
Fred Drakef6863c11999-03-02 16:37:17 +0000289\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000290
Fred Drakef6863c11999-03-02 16:37:17 +0000291\begin{methoddesc}[ScrolledWindow]{do_controlhit}{window, control,
292 pcode, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000293Handles scrollbar interaction. If you override it call this method
294first, a nonzero return value indicates the hit was in the scrollbars
295and has been handled.
Fred Drakef6863c11999-03-02 16:37:17 +0000296\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000297
Fred Drakef6863c11999-03-02 16:37:17 +0000298
299\subsection{DialogWindow Objects \label{dialogwindow-objects}}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000300
301DialogWindow objects have the following methods besides those of
302\code{Window} objects:
303
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000304
Fred Drakef6863c11999-03-02 16:37:17 +0000305\begin{methoddesc}[DialogWindow]{open}{resid}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000306Create the dialog window, from the DLOG resource with id
Fred Drakef6863c11999-03-02 16:37:17 +0000307\var{resid}. The dialog object is stored in \member{self.wid}.
308\end{methoddesc}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000309
Fred Drakef6863c11999-03-02 16:37:17 +0000310\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event}
Fred Drakeb4efb6c1998-02-18 17:19:11 +0000311Item number \var{item} was hit. You are responsible for redrawing
312toggle buttons, etc.
Fred Drakef6863c11999-03-02 16:37:17 +0000313\end{methoddesc}