Mercurial > cpython-lru_cache-weakref
annotate Doc/mac/libframework.tex @ 38664:7619216bbc19 2.4
Bug #1502728: Correctly link against librt library on HP-UX.
(backport from rev. 46743)
| author | Georg Brandl <georg@python.org> |
|---|---|
| date | Thu, 08 Jun 2006 12:54:16 +0000 |
| parents | 7e7e86f45255 |
| children | 2e9e642a58ce |
| 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 |
|
34586
7e7e86f45255
Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents:
34296
diff
changeset
|
18 Work on the \module{FrameWork} has pretty much stopped, now that |
|
7e7e86f45255
Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents:
34296
diff
changeset
|
19 \module{PyObjC} is available for full Cocoa access from Python, and the |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
20 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
|
21 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
|
22 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
|
23 MacPython newsgroup about the strengths and limitations of |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
24 \module{FrameWork}: |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
25 |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
26 \begin{quotation} |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
27 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
|
28 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
|
29 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
|
30 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
|
31 \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
|
32 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
|
33 that it's control/toolbar support is non-existent. |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
34 \end{quotation} |
|
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
35 |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
36 |
| 7866 | 37 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
|
38 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
39 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
40 \begin{funcdesc}{Application}{} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
41 An object representing the complete application. See below for a |
| 7866 | 42 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
|
43 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
|
44 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
45 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
46 \begin{funcdesc}{MenuBar}{} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
47 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
|
48 by the user. |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
49 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
50 |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7372
diff
changeset
|
51 \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
|
52 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
|
53 \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
|
54 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
|
55 at the end). |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
56 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
57 |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7372
diff
changeset
|
58 \begin{funcdesc}{MenuItem}{menu, title\optional{, shortcut, callback}} |
|
15223
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
59 Create a menu item object. The arguments are the menu to create, the |
|
30504
0ed1eace2a60
Fix doubled word errors.
Raymond Hettinger <python@rcn.com>
parents:
30136
diff
changeset
|
60 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
|
61 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
|
62 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
|
63 the event record. |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
64 |
|
15223
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
65 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
|
66 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
|
67 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
|
68 with \code{'domenu_'} prepended. |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
69 |
| 10334 | 70 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
|
71 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
|
72 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
73 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
74 \begin{funcdesc}{Separator}{menu} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
75 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
|
76 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
77 |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7372
diff
changeset
|
78 \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
|
79 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
|
80 object is returned. |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
81 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
82 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
83 \begin{funcdesc}{Window}{parent} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
84 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
|
85 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
|
86 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
87 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
88 \begin{funcdesc}{DialogWindow}{parent} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
89 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
|
90 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
91 |
|
7712
0cbc9df882b6
Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents:
7372
diff
changeset
|
92 \begin{funcdesc}{windowbounds}{width, height} |
| 10334 | 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 | |
|
15223
e470a9618ca7
Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents:
10334
diff
changeset
|
96 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
|
97 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
|
98 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
99 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
100 \begin{funcdesc}{setwatchcursor}{} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
101 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
|
102 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
103 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
104 \begin{funcdesc}{setarrowcursor}{} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
105 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
|
106 \end{funcdesc} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
107 |
| 10334 | 108 |
| 109 \subsection{Application Objects \label{application-objects}} | |
| 7866 | 110 |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
111 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
|
112 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
113 |
| 10334 | 114 \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
|
115 Override this method if you need menus in your application. Append the |
| 7866 | 116 menus to the attribute \member{menubar}. |
| 10334 | 117 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
118 |
| 10334 | 119 \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
|
120 Override this method to return a text string describing your |
| 7866 | 121 application. Alternatively, override the \method{do_about()} method |
| 122 for more elaborate ``about'' messages. | |
| 10334 | 123 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
124 |
| 10334 | 125 \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
|
126 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
|
127 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
|
128 \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
|
129 concurrent application (default 0, which is probably not a good |
| 10334 | 130 idea). While raising \var{self} to exit the mainloop is still |
| 131 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
|
132 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
133 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
|
134 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
|
135 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
|
136 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
|
137 |
| 7866 | 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 | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
140 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
|
141 can be passed on to other windows like the Sioux console window. |
| 7866 | 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. | |
| 10334 | 146 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
147 |
| 10334 | 148 \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
|
149 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
|
150 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
|
151 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
|
152 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
|
153 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
|
154 interpreter down and may cause surprising results in non-reentrant code |
|
34296
67f2190e1f6d
SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents:
30504
diff
changeset
|
155 (such as FrameWork itself). By default \var{async_dispatch} will immediately |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
156 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
|
157 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
|
158 and such. |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
159 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
160 The old on/off value is returned. |
| 10334 | 161 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
162 |
| 10334 | 163 \begin{methoddesc}[Application]{_quit}{} |
| 7866 | 164 Terminate the running \method{mainloop()} call at the next convenient |
| 165 moment. | |
| 10334 | 166 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
167 |
| 10334 | 168 \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
|
169 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
|
170 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
|
171 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
|
172 application-wide handler if the window is frontmost. |
| 10334 | 173 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
174 |
| 10334 | 175 \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
|
176 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
|
177 default method simply dispatches the event to the relevant dialog (not |
|
30136
18b67ae9cf45
SF patch#786531 'the the' typo. Contributed by George Yoshida
Raymond Hettinger <python@rcn.com>
parents:
15223
diff
changeset
|
178 through the \code{DialogWindow} object involved). Override if you |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
179 need special handling of dialog events (keyboard shortcuts, etc). |
| 10334 | 180 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
181 |
| 10334 | 182 \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
|
183 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
|
184 null-event is passed (so you can look at mouse position, etc). |
| 10334 | 185 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
186 |
| 10334 | 187 |
| 188 \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
|
189 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
190 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
|
191 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
192 \setindexsubitem{(Window method)} |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
193 |
| 10334 | 194 \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
|
195 Override this method to open a window. Store the MacOS window-id in |
| 10334 | 196 \member{self.wid} and call the \method{do_postopen()} method to |
| 197 register the window with the parent application. | |
| 198 \end{methoddesc} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
199 |
| 10334 | 200 \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
|
201 Override this method to do any special processing on window |
| 10334 | 202 close. Call the \method{do_postclose()} method to cleanup the parent |
| 203 state. | |
| 204 \end{methoddesc} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
205 |
| 10334 | 206 \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
|
207 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
|
208 than calling \code{InvalRect}. |
| 10334 | 209 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
210 |
| 10334 | 211 \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
|
212 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
|
213 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
|
214 event. |
| 10334 | 215 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
216 |
| 10334 | 217 \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
|
218 An update event for the window was received. Redraw the window. |
| 10334 | 219 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
220 |
| 10334 | 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} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
226 |
| 10334 | 227 |
| 228 \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
|
229 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
230 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
|
231 \code{Window} objects: |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
232 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
233 |
| 10334 | 234 \begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control, |
| 235 pcode, event} | |
| 236 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
|
237 user. Tracking and such has already been taken care of. |
| 10334 | 238 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
239 |
| 10334 | 240 |
| 241 \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
|
242 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
243 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
|
244 extra methods: |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
245 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
246 |
| 10334 | 247 \begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{, |
| 248 wanty}}} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
249 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
|
250 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
|
251 minimum \code{0} and maximum \code{32767}. |
| 10334 | 252 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
253 |
| 10334 | 254 \begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{} |
| 7866 | 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. | |
| 10334 | 259 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
260 |
| 10334 | 261 \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
|
262 Call this method when the document has changed. It will call |
| 7866 | 263 \method{getscrollbarvalues()} and update the scrollbars. |
| 10334 | 264 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
265 |
| 10334 | 266 \begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value} |
| 7866 | 267 Supplied by you and called after user interaction. \var{which} will |
| 268 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
|
269 \code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For |
| 7866 | 270 \code{'set'}, \var{value} will contain the new scrollbar position. |
| 10334 | 271 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
272 |
| 10334 | 273 \begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax, |
| 274 curmin, curmax} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
275 Auxiliary method to help you calculate values to return from |
| 7866 | 276 \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
|
277 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
|
278 it returns the correct number or \code{None}. |
| 10334 | 279 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
280 |
| 10334 | 281 \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
|
282 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
|
283 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
|
284 your method. |
| 10334 | 285 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
286 |
| 10334 | 287 \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
|
288 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
|
289 if you override it. |
| 10334 | 290 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
291 |
| 10334 | 292 \begin{methoddesc}[ScrolledWindow]{do_controlhit}{window, control, |
| 293 pcode, event} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
294 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
|
295 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
|
296 and has been handled. |
| 10334 | 297 \end{methoddesc} |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
298 |
| 10334 | 299 |
| 300 \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
|
301 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
302 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
|
303 \code{Window} objects: |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
304 |
|
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
305 |
| 10334 | 306 \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
|
307 Create the dialog window, from the DLOG resource with id |
| 10334 | 308 \var{resid}. The dialog object is stored in \member{self.wid}. |
| 309 \end{methoddesc} | |
|
7372
1e66c4e31d15
Separate Mac user interface modules into separate files, to better support
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
310 |
| 10334 | 311 \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
|
312 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
|
313 toggle buttons, etc. |
| 10334 | 314 \end{methoddesc} |