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