Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b4efb6c

Browse files
freddrakefreddrake
committed
Separate Mac user interface modules into separate files, to better support
bookmarkable module sections in the HTML.
1 parent 2e7a320 commit b4efb6c

10 files changed

Lines changed: 1048 additions & 702 deletions

File tree

‎Doc/lib.tex‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,8 @@
201201
\input{libmactcp}
202202
\input{libmacspeech}
203203
\input{libmacui}
204+
\input{libframework}
205+
\input{libminiae}
204206

205207
%\input{libstdwin} % STDWIN ONLY
206208

‎Doc/lib/lib.tex‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,8 @@
201201
\input{libmactcp}
202202
\input{libmacspeech}
203203
\input{libmacui}
204+
\input{libframework}
205+
\input{libminiae}
204206

205207
%\input{libstdwin} % STDWIN ONLY
206208

‎Doc/lib/libframework.tex‎

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

‎Doc/lib/libminiae.tex‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
\section{Standard Module \sectcode{MiniAEFrame}}
2+
\stmodindex{MiniAEFrame}
3+
\label{module-MiniAEFrame}
4+
5+
The module \var{MiniAEFrame} provides a framework for an application
6+
that can function as an OSA server, i.e. receive and process
7+
AppleEvents. It can be used in conjunction with \var{FrameWork} or
8+
standalone.
9+
10+
This module is temporary, it will eventually be replaced by a module
11+
that handles argument names better and possibly automates making your
12+
application scriptable.
13+
14+
The \var{MiniAEFrame} module defines the following classes:
15+
16+
\setindexsubitem{(in module MiniAEFrame)}
17+
18+
\begin{funcdesc}{AEServer}{}
19+
A class that handles AppleEvent dispatch. Your application should
20+
subclass this class together with either
21+
\code{MiniAEFrame.MiniApplication} or
22+
\code{FrameWork.Application}. Your \code{__init__} method should call
23+
the \code{__init__} method for both classes.
24+
\end{funcdesc}
25+
26+
\begin{funcdesc}{MiniApplication}{}
27+
A class that is more or less compatible with
28+
\code{FrameWork.Application} but with less functionality. Its
29+
eventloop supports the apple menu, command-dot and AppleEvents, other
30+
events are passed on to the Python interpreter and/or Sioux.
31+
Useful if your application wants to use \code{AEServer} but does not
32+
provide its own windows, etc.
33+
\end{funcdesc}
34+
35+
\subsection{AEServer Objects}
36+
37+
\setindexsubitem{(AEServer method)}
38+
39+
\begin{funcdesc}{installaehandler}{classe\, type\, callback}
40+
Installs an AppleEvent handler. \code{Classe} and \code{type} are the
41+
four-char OSA Class and Type designators, \code{'****'} wildcards are
42+
allowed. When a matching AppleEvent is received the parameters are
43+
decoded and your callback is invoked.
44+
\end{funcdesc}
45+
46+
\begin{funcdesc}{callback}{_object\, **kwargs}
47+
Your callback is called with the OSA Direct Object as first positional
48+
parameter. The other parameters are passed as keyword arguments, with
49+
the 4-char designator as name. Three extra keyword parameters are
50+
passed: \code{_class} and \code{_type} are the Class and Type
51+
designators and \code{_attributes} is a dictionary with the AppleEvent
52+
attributes.
53+
54+
The return value of your method is packed with
55+
\code{aetools.packevent} and sent as reply.
56+
\end{funcdesc}
57+
58+
Note that there are some serious problems with the current
59+
design. AppleEvents which have non-identifier 4-char designators for
60+
arguments are not implementable, and it is not possible to return an
61+
error to the originator. This will be addressed in a future release.

0 commit comments

Comments
 (0)