Doc/mac/libframework.tex

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