| \section{Standard module \sectcode{EasyDialogs}} |
| \stmodindex{EasyDialogs} |
| |
| The \code{EasyDialogs} module contains some simple dialogs for |
| the Macintosh, modelled after the \code{stdwin} dialogs with similar |
| names. |
| |
| The \code{EasyDialogs} module defines the following functions: |
| |
| \renewcommand{\indexsubitem}{(in module EasyDialogs)} |
| |
| \begin{funcdesc}{Message}{str} |
| A modal dialog with the message text \var{str}, which should be at |
| most 255 characters long, is displayed. Control is returned when the |
| user clicks ``OK''. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{AskString}{prompt\optional{\, default}} |
| Ask the user to input a string value, in a modal dialog. \var{Prompt} |
| is the promt message, the optional \var{default} arg is the initial |
| value for the string. All strings can be at most 255 bytes |
| long. \var{AskString} returns the string entered or \code{None} in |
| case the user cancelled. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}} |
| Present a dialog with text \var{question} and three buttons labelled |
| ``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for |
| no and \code{-1} for cancel. The default return value chosen by |
| hitting return is \code{0}. This can be changed with the optional |
| \var{default} argument. |
| \end{funcdesc} |
| |
| Note that \code{EasyDialogs} does not currently use the notification |
| manager. This means that displaying dialogs while the program is in |
| the background will need to unexpected results and possibly crashes. |
| |
| |
| \section{Standard module \sectcode{FrameWork}} |
| \stmodindex{FrameWork} |
| |
| The \code{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 \code{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 for more |
| esoteric needs. |
| |
| The \code{EasyDialogs} module defines the following functions: |
| |
| \renewcommand{\indexsubitem}{(in module FrameWork)} |
| |
| \begin{funcdesc}{Application}{} |
| An object representing the complete application. See below for a |
| description of the methods. The default \code{__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. |
| \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} |
| |
| |
| \subsection{Application objects} |
| Application objects have the following methods, among others: |
| |
| \renewcommand{\indexsubitem}{(Application method)} |
| |
| \begin{funcdesc}{makeusermenus}{} |
| Override this method if you need menus in your application. Append the |
| menus to \code{self.menubar}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getabouttext}{} |
| Override this method to return a text string describing your |
| application. Alternatively, override the \code{do_about} method for |
| more elaborate about messages. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mainloop}{\optional{mask\, 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). This method does not return until \code{self} is raised. |
| |
| 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. |
| \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} |
| |
| \subsection{Window Objects} |
| |
| Window objects have the following methods, among others: |
| |
| \renewcommand{\indexsubitem}{(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{DialogWindow Objects} |
| |
| DialogWindow objects have the following methods besides those of |
| \code{Window} objects: |
| |
| \renewcommand{\indexsubitem}{(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} |
| |