Doc/mac/libframework.tex

   1 \section{\module{FrameWork} ---
   2          Interactive application framework}
   3
   4 \declaremodule{standard}{FrameWork}
   5   \platform{Mac}
   6 \modulesynopsis{Interactive application framework.}
   7
   8
   9 The \module{FrameWork} module contains classes that together provide a
  10 framework for an interactive Macintosh application. The programmer
  11 builds an application by creating subclasses that override various
  12 methods of the bases classes, thereby implementing the functionality
  13 wanted. Overriding functionality can often be done on various
  14 different levels, i.e. to handle clicks in a single dialog window in a
  15 non-standard way it is not necessary to override the complete event
  16 handling.
  17
  18 The \module{FrameWork} is still very much work-in-progress, and the
  19 documentation describes only the most important functionality, and not
  20 in the most logical manner at that. Examine the source or the examples
  21 for more details.  The following are some comments posted on the
  22 MacPython newsgroup about the strengths and limitations of
  23 \module{FrameWork}:
  24
  25 \begin{quotation}
  26 The strong point of \module{FrameWork} is that it allows you to break
  27 into the control-flow at many different places. \refmodule{W}, for
  28 instance, uses a different way to enable/disable menus and that plugs
  29 right in leaving the rest intact.  The weak points of
  30 \module{FrameWork} are that it has no abstract command interface (but
  31 that shouldn't be difficult), that it's dialog support is minimal and
  32 that it's control/toolbar support is non-existent.
  33 \end{quotation}
  34
  35
  36 The \module{FrameWork} module defines the following functions:
  37
  38
  39 \begin{funcdesc}{Application}{}
  40 An object representing the complete application. See below for a
  41 description of the methods. The default \method{__init__()} routine
  42 creates an empty window dictionary and a menu bar with an apple menu.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{MenuBar}{}
  46 An object representing the menubar. This object is usually not created
  47 by the user.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{Menu}{bar, title\optional{, after}}
  51 An object representing a menu. Upon creation you pass the
  52 \code{MenuBar} the menu appears in, the \var{title} string and a
  53 position (1-based) \var{after} where the menu should appear (default:
  54 at the end).
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{MenuItem}{menu, title\optional{, shortcut, callback}}
  58 Create a menu item object. The arguments are the menu to create, the
  59 item title string and optionally the keyboard shortcut
  60 and a callback routine. The callback is called with the arguments
  61 menu-id, item number within menu (1-based), current front window and
  62 the event record.
  63
  64 Instead of a callable object the callback can also be a string. In
  65 this case menu selection causes the lookup of a method in the topmost
  66 window and the application. The method name is the callback string
  67 with \code{'domenu_'} prepended.
  68
  69 Calling the \code{MenuBar} \method{fixmenudimstate()} method sets the
  70 correct dimming for all menu items based on the current front window.
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{Separator}{menu}
  74 Add a separator to the end of a menu.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{SubMenu}{menu, label}
  78 Create a submenu named \var{label} under menu \var{menu}. The menu
  79 object is returned.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{Window}{parent}
  83 Creates a (modeless) window. \var{Parent} is the application object to
  84 which the window belongs. The window is not displayed until later.
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{DialogWindow}{parent}
  88 Creates a modeless dialog window.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{windowbounds}{width, height}
  92 Return a \code{(\var{left}, \var{top}, \var{right}, \var{bottom})}
  93 tuple suitable for creation of a window of given width and height. The
  94 window will be staggered with respect to previous windows, and an
  95 attempt is made to keep the whole window on-screen. However, the window will
  96 however always be the exact size given, so parts may be offscreen.
  97 \end{funcdesc}
  98
  99 \begin{funcdesc}{setwatchcursor}{}
 100 Set the mouse cursor to a watch.
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{setarrowcursor}{}
 104 Set the mouse cursor to an arrow.
 105 \end{funcdesc}
 106
 107
 108 \subsection{Application Objects \label{application-objects}}
 109
 110 Application objects have the following methods, among others:
 111
 112
 113 \begin{methoddesc}[Application]{makeusermenus}{}
 114 Override this method if you need menus in your application. Append the
 115 menus to the attribute \member{menubar}.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}[Application]{getabouttext}{}
 119 Override this method to return a text string describing your
 120 application.  Alternatively, override the \method{do_about()} method
 121 for more elaborate ``about'' messages.
 122 \end{methoddesc}
 123
 124 \begin{methoddesc}[Application]{mainloop}{\optional{mask\optional{, wait}}}
 125 This routine is the main event loop, call it to set your application
 126 rolling. \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
 128 concurrent application (default 0, which is probably not a good
 129 idea). While raising \var{self} to exit the mainloop is still
 130 supported it is not recommended: call \code{self._quit()} instead.
 131
 132 The event loop is split into many small parts, each of which can be
 133 overridden. The default methods take care of dispatching events to
 134 windows and dialogs, handling drags and resizes, Apple Events, events
 135 for non-FrameWork windows, etc.
 136
 137 In general, all event handlers should return \code{1} if the event is fully
 138 handled and \code{0} otherwise (because the front window was not a FrameWork
 139 window, for instance). This is needed so that update events and such
 140 can be passed on to other windows like the Sioux console window.
 141 Calling \function{MacOS.HandleEvent()} is not allowed within
 142 \var{our_dispatch} or its callees, since this may result in an
 143 infinite loop if the code is called through the Python inner-loop
 144 event handler.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[Application]{asyncevents}{onoff}
 148 Call this method with a nonzero parameter to enable
 149 asynchronous event handling. This will tell the inner interpreter loop
 150 to call the application event handler \var{async_dispatch} whenever events
 151 are available. This will cause FrameWork window updates and the user
 152 interface to remain working during long computations, but will slow the
 153 interpreter down and may cause surprising results in non-reentrant code
 154 (such as FrameWork itself). By default \var{async_dispatch} will immedeately
 155 call \var{our_dispatch} but you may override this to handle only certain
 156 events asynchronously. Events you do not handle will be passed to Sioux
 157 and such.
 158
 159 The old on/off value is returned.
 160 \end{methoddesc}
 161
 162 \begin{methoddesc}[Application]{_quit}{}
 163 Terminate the running \method{mainloop()} call at the next convenient
 164 moment.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}[Application]{do_char}{c, event}
 168 The user typed character \var{c}. The complete details of the event
 169 can be found in the \var{event} structure. This method can also be
 170 provided in a \code{Window} object, which overrides the
 171 application-wide handler if the window is frontmost.
 172 \end{methoddesc}
 173
 174 \begin{methoddesc}[Application]{do_dialogevent}{event}
 175 Called early in the event loop to handle modeless dialog events. The
 176 default method simply dispatches the event to the relevant dialog (not
 177 through the \code{DialogWindow} object involved). Override if you
 178 need special handling of dialog events (keyboard shortcuts, etc).
 179 \end{methoddesc}
 180
 181 \begin{methoddesc}[Application]{idle}{event}
 182 Called by the main event loop when no events are available. The
 183 null-event is passed (so you can look at mouse position, etc).
 184 \end{methoddesc}
 185
 186
 187 \subsection{Window Objects \label{window-objects}}
 188
 189 Window objects have the following methods, among others:
 190
 191 \setindexsubitem{(Window method)}
 192
 193 \begin{methoddesc}[Window]{open}{}
 194 Override this method to open a window. Store the MacOS window-id in
 195 \member{self.wid} and call the \method{do_postopen()} method to
 196 register the window with the parent application.
 197 \end{methoddesc}
 198
 199 \begin{methoddesc}[Window]{close}{}
 200 Override this method to do any special processing on window
 201 close. Call the \method{do_postclose()} method to cleanup the parent
 202 state.
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid}
 206 Called after the window is resized. Override if more needs to be done
 207 than calling \code{InvalRect}.
 208 \end{methoddesc}
 209
 210 \begin{methoddesc}[Window]{do_contentclick}{local, modifiers, event}
 211 The user clicked in the content part of a window. The arguments are
 212 the coordinates (window-relative), the key modifiers and the raw
 213 event.
 214 \end{methoddesc}
 215
 216 \begin{methoddesc}[Window]{do_update}{macoswindowid, event}
 217 An update event for the window was received. Redraw the window.
 218 \end{methoddesc}
 219
 220 \begin{methoddesc}{do_activate}{activate, event}
 221 The window was activated (\code{\var{activate} == 1}) or deactivated
 222 (\code{\var{activate} == 0}). Handle things like focus highlighting,
 223 etc.
 224 \end{methoddesc}
 225
 226
 227 \subsection{ControlsWindow Object \label{controlswindow-object}}
 228
 229 ControlsWindow objects have the following methods besides those of
 230 \code{Window} objects:
 231
 232
 233 \begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control,
 234                                                   pcode, event}
 235 Part \var{pcode} of control \var{control} was hit by the
 236 user. Tracking and such has already been taken care of.
 237 \end{methoddesc}
 238
 239
 240 \subsection{ScrolledWindow Object \label{scrolledwindow-object}}
 241
 242 ScrolledWindow objects are ControlsWindow objects with the following
 243 extra methods:
 244
 245
 246 \begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{,
 247                                                wanty}}}
 248 Create (or destroy) horizontal and vertical scrollbars. The arguments
 249 specify which you want (default: both). The scrollbars always have
 250 minimum \code{0} and maximum \code{32767}.
 251 \end{methoddesc}
 252
 253 \begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{}
 254 You 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
 257 indicate the whole document is visible in that direction.
 258 \end{methoddesc}
 259
 260 \begin{methoddesc}[ScrolledWindow]{updatescrollbars}{}
 261 Call this method when the document has changed. It will call
 262 \method{getscrollbarvalues()} and update the scrollbars.
 263 \end{methoddesc}
 264
 265 \begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value}
 266 Supplied by you and called after user interaction. \var{which} will
 267 be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
 268 \code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
 269 \code{'set'}, \var{value} will contain the new scrollbar position.
 270 \end{methoddesc}
 271
 272 \begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax,
 273                                                    curmin, curmax}
 274 Auxiliary method to help you calculate values to return from
 275 \method{getscrollbarvalues()}. You pass document minimum and maximum value
 276 and topmost (leftmost) and bottommost (rightmost) visible values and
 277 it returns the correct number or \code{None}.
 278 \end{methoddesc}
 279
 280 \begin{methoddesc}[ScrolledWindow]{do_activate}{onoff, event}
 281 Takes care of dimming/highlighting scrollbars when a window becomes
 282 frontmost. If you override this method, call this one at the end of
 283 your method.
 284 \end{methoddesc}
 285
 286 \begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window}
 287 Moves scrollbars to the correct position. Call this method initially
 288 if you override it.
 289 \end{methoddesc}
 290
 291 \begin{methoddesc}[ScrolledWindow]{do_controlhit}{window, control,
 292                                                   pcode, event}
 293 Handles scrollbar interaction. If you override it call this method
 294 first, a nonzero return value indicates the hit was in the scrollbars
 295 and has been handled.
 296 \end{methoddesc}
 297
 298
 299 \subsection{DialogWindow Objects \label{dialogwindow-objects}}
 300
 301 DialogWindow objects have the following methods besides those of
 302 \code{Window} objects:
 303
 304
 305 \begin{methoddesc}[DialogWindow]{open}{resid}
 306 Create the dialog window, from the DLOG resource with id
 307 \var{resid}. The dialog object is stored in \member{self.wid}.
 308 \end{methoddesc}
 309
 310 \begin{methoddesc}[DialogWindow]{do_itemhit}{item, event}
 311 Item number \var{item} was hit. You are responsible for redrawing
 312 toggle buttons, etc.
 313 \end{methoddesc}