315 lines
12 KiB
TeX
315 lines
12 KiB
TeX
\section{\module{FrameWork} ---
|
|
Interactive application framework}
|
|
|
|
\declaremodule{standard}{FrameWork}
|
|
\platform{Mac}
|
|
\modulesynopsis{Interactive application 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.
|
|
|
|
Work on the \module{FrameWork} has pretty much stopped, now that
|
|
\module{PyObjC} is available for full Cocoa access from Python, 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 following are some comments posted on the
|
|
MacPython newsgroup about the strengths and limitations of
|
|
\module{FrameWork}:
|
|
|
|
\begin{quotation}
|
|
The strong point of \module{FrameWork} is that it allows you to break
|
|
into the control-flow at many different places. \refmodule{W}, for
|
|
instance, uses a different way to enable/disable menus and that plugs
|
|
right in leaving the rest intact. The weak points of
|
|
\module{FrameWork} are that it has no abstract command interface (but
|
|
that shouldn't be difficult), that its dialog support is minimal and
|
|
that its control/toolbar support is non-existent.
|
|
\end{quotation}
|
|
|
|
|
|
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 create, 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.
|
|
|
|
Instead 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} \method{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{(\var{left}, \var{top}, \var{right}, \var{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. However, the window will
|
|
however always be the exact 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:
|
|
|
|
|
|
\begin{methoddesc}[Application]{makeusermenus}{}
|
|
Override this method if you need menus in your application. Append the
|
|
menus to the attribute \member{menubar}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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 \var{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{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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 immediately
|
|
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{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{_quit}{}
|
|
Terminate the running \method{mainloop()} call at the next convenient
|
|
moment.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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 \code{DialogWindow} object involved). Override if you
|
|
need special handling of dialog events (keyboard shortcuts, etc).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Application]{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{methoddesc}
|
|
|
|
|
|
\subsection{Window Objects \label{window-objects}}
|
|
|
|
Window objects have the following methods, among others:
|
|
|
|
\setindexsubitem{(Window method)}
|
|
|
|
\begin{methoddesc}[Window]{open}{}
|
|
Override this method to open a window. Store the MacOS window-id in
|
|
\member{self.wid} and call the \method{do_postopen()} method to
|
|
register the window with the parent application.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Window]{close}{}
|
|
Override this method to do any special processing on window
|
|
close. Call the \method{do_postclose()} method to cleanup the parent
|
|
state.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid}
|
|
Called after the window is resized. Override if more needs to be done
|
|
than calling \code{InvalRect}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Window]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[Window]{do_update}{macoswindowid, event}
|
|
An update event for the window was received. Redraw the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{do_activate}{activate, event}
|
|
The window was activated (\code{\var{activate} == 1}) or deactivated
|
|
(\code{\var{activate} == 0}). Handle things like focus highlighting,
|
|
etc.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{ControlsWindow Object \label{controlswindow-object}}
|
|
|
|
ControlsWindow objects have the following methods besides those of
|
|
\code{Window} objects:
|
|
|
|
|
|
\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control,
|
|
pcode, event}
|
|
Part \var{pcode} of control \var{control} was hit by the
|
|
user. Tracking and such has already been taken care of.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{ScrolledWindow Object \label{scrolledwindow-object}}
|
|
|
|
ScrolledWindow objects are ControlsWindow objects with the following
|
|
extra methods:
|
|
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{}
|
|
Call this method when the document has changed. It will call
|
|
\method{getscrollbarvalues()} and update the scrollbars.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{do_activate}{onoff, event}
|
|
Takes care of dimming/highlighting scrollbars when a window becomes
|
|
frontmost. If you override this method, call this one at the end of
|
|
your method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window}
|
|
Moves scrollbars to the correct position. Call this method initially
|
|
if you override it.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
|
|
|
|
|
|
\subsection{DialogWindow Objects \label{dialogwindow-objects}}
|
|
|
|
DialogWindow objects have the following methods besides those of
|
|
\code{Window} objects:
|
|
|
|
|
|
\begin{methoddesc}[DialogWindow]{open}{resid}
|
|
Create the dialog window, from the DLOG resource with id
|
|
\var{resid}. The dialog object is stored in \member{self.wid}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event}
|
|
Item number \var{item} was hit. You are responsible for redrawing
|
|
toggle buttons, etc.
|
|
\end{methoddesc}
|