/Doc/library/framework.rst

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