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