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