Relocating file to mac.
This commit is contained in:
Fred Drake
parent
0a52bdfd4f
commit
4775d0a353
|
|
@ -1,294 +0,0 @@
|
|||
\section{Standard Module \module{FrameWork}}
|
||||
\stmodindex{FrameWork}
|
||||
\label{module-FrameWork}
|
||||
|
||||
The \module{FrameWork} module contains classes that together provide a
|
||||
framework for an interactive Macintosh application. The programmer
|
||||
builds an application by creating subclasses that override various
|
||||
methods of the bases classes, thereby implementing the functionality
|
||||
wanted. Overriding functionality can often be done on various
|
||||
different levels, i.e. to handle clicks in a single dialog window in a
|
||||
non-standard way it is not necessary to override the complete event
|
||||
handling.
|
||||
|
||||
The \module{FrameWork} is still very much work-in-progress, and the
|
||||
documentation describes only the most important functionality, and not
|
||||
in the most logical manner at that. Examine the source or the examples
|
||||
for more details.
|
||||
|
||||
The \module{FrameWork} module defines the following functions:
|
||||
|
||||
|
||||
\begin{funcdesc}{Application}{}
|
||||
An object representing the complete application. See below for a
|
||||
description of the methods. The default \method{__init__()} routine
|
||||
creates an empty window dictionary and a menu bar with an apple menu.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{MenuBar}{}
|
||||
An object representing the menubar. This object is usually not created
|
||||
by the user.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{Menu}{bar, title\optional{, after}}
|
||||
An object representing a menu. Upon creation you pass the
|
||||
\code{MenuBar} the menu appears in, the \var{title} string and a
|
||||
position (1-based) \var{after} where the menu should appear (default:
|
||||
at the end).
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{MenuItem}{menu, title\optional{, shortcut, callback}}
|
||||
Create a menu item object. The arguments are the menu to crate the
|
||||
item it, the item title string and optionally the keyboard shortcut
|
||||
and a callback routine. The callback is called with the arguments
|
||||
menu-id, item number within menu (1-based), current front window and
|
||||
the event record.
|
||||
|
||||
In stead of a callable object the callback can also be a string. In
|
||||
this case menu selection causes the lookup of a method in the topmost
|
||||
window and the application. The method name is the callback string
|
||||
with \code{'domenu_'} prepended.
|
||||
|
||||
Calling the \code{MenuBar} \code{fixmenudimstate} method sets the
|
||||
correct dimming for all menu items based on the current front window.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{Separator}{menu}
|
||||
Add a separator to the end of a menu.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{SubMenu}{menu, label}
|
||||
Create a submenu named \var{label} under menu \var{menu}. The menu
|
||||
object is returned.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{Window}{parent}
|
||||
Creates a (modeless) window. \var{Parent} is the application object to
|
||||
which the window belongs. The window is not displayed until later.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{DialogWindow}{parent}
|
||||
Creates a modeless dialog window.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{windowbounds}{width, height}
|
||||
Return a \code{(left, top, right, bottom)} tuple suitable for creation
|
||||
of a window of given width and height. The window will be staggered
|
||||
with respect to previous windows, and an attempt is made to keep the
|
||||
whole window on-screen. The window will however always be exact the
|
||||
size given, so parts may be offscreen.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{setwatchcursor}{}
|
||||
Set the mouse cursor to a watch.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{setarrowcursor}{}
|
||||
Set the mouse cursor to an arrow.
|
||||
\end{funcdesc}
|
||||
|
||||
\subsection{Application Objects}
|
||||
\label{application-objects}
|
||||
|
||||
Application objects have the following methods, among others:
|
||||
|
||||
\setindexsubitem{(Application method)}
|
||||
|
||||
\begin{funcdesc}{makeusermenus}{}
|
||||
Override this method if you need menus in your application. Append the
|
||||
menus to the attribute \member{menubar}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{getabouttext}{}
|
||||
Override this method to return a text string describing your
|
||||
application. Alternatively, override the \method{do_about()} method
|
||||
for more elaborate ``about'' messages.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{mainloop}{\optional{mask\optional{, wait}}}
|
||||
This routine is the main event loop, call it to set your application
|
||||
rolling. \var{Mask} is the mask of events you want to handle,
|
||||
\var{wait} is the number of ticks you want to leave to other
|
||||
concurrent application (default 0, which is probably not a good
|
||||
idea). While raising \code{self} to exit the mainloop is still
|
||||
supported it is not recommended, call \code{self._quit} instead.
|
||||
|
||||
The event loop is split into many small parts, each of which can be
|
||||
overridden. The default methods take care of dispatching events to
|
||||
windows and dialogs, handling drags and resizes, Apple Events, events
|
||||
for non-FrameWork windows, etc.
|
||||
|
||||
In general, all event handlers should return \code{1} if the event is fully
|
||||
handled and \code{0} otherwise (because the front window was not a FrameWork
|
||||
window, for instance). This is needed so that update events and such
|
||||
can be passed on to other windows like the Sioux console window.
|
||||
Calling \function{MacOS.HandleEvent()} is not allowed within
|
||||
\var{our_dispatch} or its callees, since this may result in an
|
||||
infinite loop if the code is called through the Python inner-loop
|
||||
event handler.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{asyncevents}{onoff}
|
||||
Call this method with a nonzero parameter to enable
|
||||
asynchronous event handling. This will tell the inner interpreter loop
|
||||
to call the application event handler \var{async_dispatch} whenever events
|
||||
are available. This will cause FrameWork window updates and the user
|
||||
interface to remain working during long computations, but will slow the
|
||||
interpreter down and may cause surprising results in non-reentrant code
|
||||
(such as FrameWork itself). By default \var{async_dispatch} will immedeately
|
||||
call \var{our_dispatch} but you may override this to handle only certain
|
||||
events asynchronously. Events you do not handle will be passed to Sioux
|
||||
and such.
|
||||
|
||||
The old on/off value is returned.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{_quit}{}
|
||||
Terminate the running \method{mainloop()} call at the next convenient
|
||||
moment.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_char}{c, event}
|
||||
The user typed character \var{c}. The complete details of the event
|
||||
can be found in the \var{event} structure. This method can also be
|
||||
provided in a \code{Window} object, which overrides the
|
||||
application-wide handler if the window is frontmost.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_dialogevent}{event}
|
||||
Called early in the event loop to handle modeless dialog events. The
|
||||
default method simply dispatches the event to the relevant dialog (not
|
||||
through the the \code{DialogWindow} object involved). Override if you
|
||||
need special handling of dialog events (keyboard shortcuts, etc).
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{idle}{event}
|
||||
Called by the main event loop when no events are available. The
|
||||
null-event is passed (so you can look at mouse position, etc).
|
||||
\end{funcdesc}
|
||||
|
||||
\subsection{Window Objects}
|
||||
\label{window-objects}
|
||||
|
||||
Window objects have the following methods, among others:
|
||||
|
||||
\setindexsubitem{(Window method)}
|
||||
|
||||
\begin{funcdesc}{open}{}
|
||||
Override this method to open a window. Store the MacOS window-id in
|
||||
\code{self.wid} and call \code{self.do_postopen} to register the
|
||||
window with the parent application.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{close}{}
|
||||
Override this method to do any special processing on window
|
||||
close. Call \code{self.do_postclose} to cleanup the parent state.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_postresize}{width, height, macoswindowid}
|
||||
Called after the window is resized. Override if more needs to be done
|
||||
than calling \code{InvalRect}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_contentclick}{local, modifiers, event}
|
||||
The user clicked in the content part of a window. The arguments are
|
||||
the coordinates (window-relative), the key modifiers and the raw
|
||||
event.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_update}{macoswindowid, event}
|
||||
An update event for the window was received. Redraw the window.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_activate}{activate, event}
|
||||
The window was activated (\code{activate==1}) or deactivated
|
||||
(\code{activate==0}). Handle things like focus highlighting, etc.
|
||||
\end{funcdesc}
|
||||
|
||||
\subsection{ControlsWindow Object}
|
||||
\label{controlswindow-object}
|
||||
|
||||
ControlsWindow objects have the following methods besides those of
|
||||
\code{Window} objects:
|
||||
|
||||
\setindexsubitem{(ControlsWindow method)}
|
||||
|
||||
\begin{funcdesc}{do_controlhit}{window, control, pcode, event}
|
||||
Part \code{pcode} of control \code{control} was hit by the
|
||||
user. Tracking and such has already been taken care of.
|
||||
\end{funcdesc}
|
||||
|
||||
\subsection{ScrolledWindow Object}
|
||||
\label{scrolledwindow-object}
|
||||
|
||||
ScrolledWindow objects are ControlsWindow objects with the following
|
||||
extra methods:
|
||||
|
||||
\setindexsubitem{(ScrolledWindow method)}
|
||||
|
||||
\begin{funcdesc}{scrollbars}{\optional{wantx\optional{, wanty}}}
|
||||
Create (or destroy) horizontal and vertical scrollbars. The arguments
|
||||
specify which you want (default: both). The scrollbars always have
|
||||
minimum \code{0} and maximum \code{32767}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{getscrollbarvalues}{}
|
||||
You must supply this method. It should return a tuple \code{(\var{x},
|
||||
\var{y})} giving the current position of the scrollbars (between
|
||||
\code{0} and \code{32767}). You can return \code{None} for either to
|
||||
indicate the whole document is visible in that direction.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{updatescrollbars}{}
|
||||
Call this method when the document has changed. It will call
|
||||
\method{getscrollbarvalues()} and update the scrollbars.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{scrollbar_callback}{which, what, value}
|
||||
Supplied by you and called after user interaction. \var{which} will
|
||||
be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
|
||||
\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
|
||||
\code{'set'}, \var{value} will contain the new scrollbar position.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{scalebarvalues}{absmin, absmax, curmin, curmax}
|
||||
Auxiliary method to help you calculate values to return from
|
||||
\method{getscrollbarvalues()}. You pass document minimum and maximum value
|
||||
and topmost (leftmost) and bottommost (rightmost) visible values and
|
||||
it returns the correct number or \code{None}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_activate}{onoff, event}
|
||||
Takes care of dimming/highlighting scrollbars when a window becomes
|
||||
frontmost vv. If you override this method call this one at the end of
|
||||
your method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_postresize}{width, height, window}
|
||||
Moves scrollbars to the correct position. Call this method initially
|
||||
if you override it.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_controlhit}{window, control, pcode, event}
|
||||
Handles scrollbar interaction. If you override it call this method
|
||||
first, a nonzero return value indicates the hit was in the scrollbars
|
||||
and has been handled.
|
||||
\end{funcdesc}
|
||||
|
||||
\subsection{DialogWindow Objects}
|
||||
\label{dialogwindow-objects}
|
||||
|
||||
DialogWindow objects have the following methods besides those of
|
||||
\code{Window} objects:
|
||||
|
||||
\setindexsubitem{(DialogWindow method)}
|
||||
|
||||
\begin{funcdesc}{open}{resid}
|
||||
Create the dialog window, from the DLOG resource with id
|
||||
\var{resid}. The dialog object is stored in \code{self.wid}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{do_itemhit}{item, event}
|
||||
Item number \var{item} was hit. You are responsible for redrawing
|
||||
toggle buttons, etc.
|
||||
\end{funcdesc}
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
\section{Standard Module \module{MiniAEFrame}}
|
||||
\stmodindex{MiniAEFrame}
|
||||
\label{module-MiniAEFrame}
|
||||
|
||||
The module \module{MiniAEFrame} provides a framework for an application
|
||||
that can function as an Open Scripting Architecture
|
||||
\index{Open Scripting Architecture}
|
||||
(OSA) server, i.e. receive and process
|
||||
AppleEvents\index{AppleEvents}. It can be used in conjunction with
|
||||
\module{FrameWork}\refstmodindex{FrameWork} or standalone.
|
||||
|
||||
This module is temporary, it will eventually be replaced by a module
|
||||
that handles argument names better and possibly automates making your
|
||||
application scriptable.
|
||||
|
||||
The \module{MiniAEFrame} module defines the following classes:
|
||||
|
||||
|
||||
\begin{classdesc}{AEServer}{}
|
||||
A class that handles AppleEvent dispatch. Your application should
|
||||
subclass this class together with either
|
||||
\class{MiniApplication} or
|
||||
\class{FrameWork.Application}. Your \method{__init__()} method should
|
||||
call the \method{__init__()} method for both classes.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{MiniApplication}{}
|
||||
A class that is more or less compatible with
|
||||
\class{FrameWork.Application} but with less functionality. Its
|
||||
event loop supports the apple menu, command-dot and AppleEvents; other
|
||||
events are passed on to the Python interpreter and/or Sioux.
|
||||
Useful if your application wants to use \class{AEServer} but does not
|
||||
provide its own windows, etc.
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
\subsection{AEServer Objects}
|
||||
\label{aeserver-objects}
|
||||
|
||||
\begin{methoddesc}[AEServer]{installaehandler}{classe, type, callback}
|
||||
Installs an AppleEvent handler. \var{classe} and \var{type} are the
|
||||
four-character OSA Class and Type designators, \code{'****'} wildcards
|
||||
are allowed. When a matching AppleEvent is received the parameters are
|
||||
decoded and your callback is invoked.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}[AEServer]{callback}{_object, **kwargs}
|
||||
Your callback is called with the OSA Direct Object as first positional
|
||||
parameter. The other parameters are passed as keyword arguments, with
|
||||
the 4-character designator as name. Three extra keyword parameters are
|
||||
passed: \code{_class} and \code{_type} are the Class and Type
|
||||
designators and \code{_attributes} is a dictionary with the AppleEvent
|
||||
attributes.
|
||||
|
||||
The return value of your method is packed with
|
||||
\function{aetools.packevent()} and sent as reply.
|
||||
\end{methoddesc}
|
||||
|
||||
Note that there are some serious problems with the current
|
||||
design. AppleEvents which have non-identifier 4-character designators
|
||||
for arguments are not implementable, and it is not possible to return
|
||||
an error to the originator. This will be addressed in a future
|
||||
release.
|
||||
Loading…
Reference in New Issue