|
| 1 | +\section{Standard module \sectcode{EasyDialogs}} |
| 2 | +\stmodindex{EasyDialogs} |
| 3 | + |
| 4 | +The \code{EasyDialogs} module contains some simple dialogs for |
| 5 | +the Macintosh, modelled after the \code{stdwin} dialogs with similar |
| 6 | +names. |
| 7 | + |
| 8 | +The \code{EasyDialogs} module defines the following functions: |
| 9 | + |
| 10 | +\renewcommand{\indexsubitem}{(in module EasyDialogs)} |
| 11 | + |
| 12 | +\begin{funcdesc}{Message}{str} |
| 13 | +A modal dialog with the message text \var{str}, which should be at |
| 14 | +most 255 characters long, is displayed. Control is returned when the |
| 15 | +user clicks ``OK''. |
| 16 | +\end{funcdesc} |
| 17 | + |
| 18 | +\begin{funcdesc}{AskString}{prompt\optional{\, default}} |
| 19 | +Ask the user to input a string value, in a modal dialog. \var{Prompt} |
| 20 | +is the promt message, the optional \var{default} arg is the initial |
| 21 | +value for the string. All strings can be at most 255 bytes |
| 22 | +long. \var{AskString} returns the string entered or \code{None} in |
| 23 | +case the user cancelled. |
| 24 | +\end{funcdesc} |
| 25 | + |
| 26 | +\begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}} |
| 27 | +Present a dialog with text \var{question} and three buttons labelled |
| 28 | +``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for |
| 29 | +no and \code{-1} for cancel. The default return value chosen by |
| 30 | +hitting return is \code{0}. This can be changed with the optional |
| 31 | +\var{default} argument. |
| 32 | +\end{funcdesc} |
| 33 | + |
| 34 | +Note that \code{EasyDialogs} does not currently use the notification |
| 35 | +manager. This means that displaying dialogs while the program is in |
| 36 | +the background will need to unexpected results and possibly crashes. |
| 37 | + |
| 38 | + |
| 39 | +\section{Standard module \sectcode{FrameWork}} |
| 40 | +\stmodindex{FrameWork} |
| 41 | + |
| 42 | +The \code{FrameWork} module contains classes that together provide a |
| 43 | +framework for an interactive Macintosh application. The programmer |
| 44 | +builds an application by creating subclasses that override various |
| 45 | +methods of the bases classes, thereby implementing the functionality |
| 46 | +wanted. Overriding functionality can often be done on various |
| 47 | +different levels, i.e. to handle clicks in a single dialog window in a |
| 48 | +non-standard way it is not necessary to override the complete event |
| 49 | +handling. |
| 50 | + |
| 51 | +The \code{FrameWork} is still very much work-in-progress, and the |
| 52 | +documentation describes only the most important functionality, and not |
| 53 | +in the most logical manner at that. Examine the source for more |
| 54 | +esoteric needs. |
| 55 | + |
| 56 | +The \code{EasyDialogs} module defines the following functions: |
| 57 | + |
| 58 | +\renewcommand{\indexsubitem}{(in module FrameWork)} |
| 59 | + |
| 60 | +\begin{funcdesc}{Application}{} |
| 61 | +An object representing the complete application. See below for a |
| 62 | +description of the methods. The default \code{__init__} routine |
| 63 | +creates an empty window dictionary and a menu bar with an apple menu. |
| 64 | +\end{funcdesc} |
| 65 | + |
| 66 | +\begin{funcdesc}{MenuBar}{} |
| 67 | +An object representing the menubar. This object is usually not created |
| 68 | +by the user. |
| 69 | +\end{funcdesc} |
| 70 | + |
| 71 | +\begin{funcdesc}{Menu}{bar\, title\optional{\, after}} |
| 72 | +An object representing a menu. Upon creation you pass the |
| 73 | +\code{MenuBar} the menu appears in, the \var{title} string and a |
| 74 | +position (1-based) \var{after} where the menu should appear (default: |
| 75 | +at the end). |
| 76 | +\end{funcdesc} |
| 77 | + |
| 78 | +\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}} |
| 79 | +Create a menu item object. The arguments are the menu to crate the |
| 80 | +item it, the item title string and optionally the keyboard shortcut |
| 81 | +and a callback routine. The callback is called with the arguments |
| 82 | +menu-id, item number within menu (1-based), current front window and |
| 83 | +the event record. |
| 84 | +\end{funcdesc} |
| 85 | + |
| 86 | +\begin{funcdesc}{Separator}{menu} |
| 87 | +Add a separator to the end of a menu. |
| 88 | +\end{funcdesc} |
| 89 | + |
| 90 | +\begin{funcdesc}{SubMenu}{menu\, label} |
| 91 | +Create a submenu named \var{label} under menu \var{menu}. The menu |
| 92 | +object is returned. |
| 93 | +\end{funcdesc} |
| 94 | + |
| 95 | +\begin{funcdesc}{Window}{parent} |
| 96 | +Creates a (modeless) window. \var{Parent} is the application object to |
| 97 | +which the window belongs. The window is not displayed until later. |
| 98 | +\end{funcdesc} |
| 99 | + |
| 100 | +\begin{funcdesc}{DialogWindow}{parent} |
| 101 | +Creates a modeless dialog window. |
| 102 | +\end{funcdesc} |
| 103 | + |
| 104 | + |
| 105 | +\subsection{Application objects} |
| 106 | +Application objects have the following methods, among others: |
| 107 | + |
| 108 | +\renewcommand{\indexsubitem}{(Application method)} |
| 109 | + |
| 110 | +\begin{funcdesc}{makeusermenus}{} |
| 111 | +Override this method if you need menus in your application. Append the |
| 112 | +menus to \code{self.menubar}. |
| 113 | +\end{funcdesc} |
| 114 | + |
| 115 | +\begin{funcdesc}{getabouttext}{} |
| 116 | +Override this method to return a text string describing your |
| 117 | +application. Alternatively, override the \code{do_about} method for |
| 118 | +more elaborate about messages. |
| 119 | +\end{funcdesc} |
| 120 | + |
| 121 | +\begin{funcdesc}{mainloop}{\optional{mask\, wait}} |
| 122 | +This routine is the main event loop, call it to set your application |
| 123 | +rolling. \var{Mask} is the mask of events you want to handle, |
| 124 | +\var{wait} is the number of ticks you want to leave to other |
| 125 | +concurrent application (default 0, which is probably not a good |
| 126 | +idea). This method does not return until \code{self} is raised. |
| 127 | + |
| 128 | +The event loop is split into many small parts, each of which can be |
| 129 | +overridden. The default methods take care of dispatching events to |
| 130 | +windows and dialogs, handling drags and resizes, Apple Events, events |
| 131 | +for non-FrameWork windows, etc. |
| 132 | +\end{funcdesc} |
| 133 | + |
| 134 | +\begin{funcdesc}{do_char}{c\, event} |
| 135 | +The user typed character \var{c}. The complete details of the event |
| 136 | +can be found in the \var{event} structure. This method can also be |
| 137 | +provided in a \code{Window} object, which overrides the |
| 138 | +application-wide handler if the window is frontmost. |
| 139 | +\end{funcdesc} |
| 140 | + |
| 141 | +\begin{funcdesc}{do_dialogevent}{event} |
| 142 | +Called early in the event loop to handle modeless dialog events. The |
| 143 | +default method simply dispatches the event to the relevant dialog (not |
| 144 | +through the the \code{DialogWindow} object involved). Override if you |
| 145 | +need special handling of dialog events (keyboard shortcuts, etc). |
| 146 | +\end{funcdesc} |
| 147 | + |
| 148 | +\subsection{Window Objects} |
| 149 | + |
| 150 | +Window objects have the following methods, among others: |
| 151 | + |
| 152 | +\renewcommand{\indexsubitem}{(Window method)} |
| 153 | + |
| 154 | +\begin{funcdesc}{open}{} |
| 155 | +Override this method to open a window. Store the MacOS window-id in |
| 156 | +\code{self.wid} and call \code{self.do_postopen} to register the |
| 157 | +window with the parent application. |
| 158 | +\end{funcdesc} |
| 159 | + |
| 160 | +\begin{funcdesc}{close}{} |
| 161 | +Override this method to do any special processing on window |
| 162 | +close. Call \code{self.do_postclose} to cleanup the parent state. |
| 163 | +\end{funcdesc} |
| 164 | + |
| 165 | +\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid} |
| 166 | +Called after the window is resized. Override if more needs to be done |
| 167 | +than calling \code{InvalRect}. |
| 168 | +\end{funcdesc} |
| 169 | + |
| 170 | +\begin{funcdesc}{do_contentclick}{local\, modifiers\, event} |
| 171 | +The user clicked in the content part of a window. The arguments are |
| 172 | +the coordinates (window-relative), the key modifiers and the raw |
| 173 | +event. |
| 174 | +\end{funcdesc} |
| 175 | + |
| 176 | +\begin{funcdesc}{do_update}{macoswindowid\, event} |
| 177 | +An update event for the window was received. Redraw the window. |
| 178 | +\end{funcdesc} |
| 179 | + |
| 180 | +\begin{funcdesc}{do_activate}{activate\, event} |
| 181 | +The window was activated (\code{activate==1}) or deactivated |
| 182 | +(\code{activate==0}). Handle things like focus highlighting, etc. |
| 183 | +\end{funcdesc} |
| 184 | + |
| 185 | +\subsection{DialogWindow Objects} |
| 186 | + |
| 187 | +DialogWindow objects have the following methods besides those of |
| 188 | +\code{Window} objects: |
| 189 | + |
| 190 | +\renewcommand{\indexsubitem}{(DialogWindow method)} |
| 191 | + |
| 192 | +\begin{funcdesc}{open}{resid} |
| 193 | +Create the dialog window, from the DLOG resource with id |
| 194 | +\var{resid}. The dialog object is stored in \code{self.wid}. |
| 195 | +\end{funcdesc} |
| 196 | + |
| 197 | +\begin{funcdesc}{do_itemhit}{item\, event} |
| 198 | +Item number \var{item} was hit. You are responsible for redrawing |
| 199 | +toggle buttons, etc. |
| 200 | +\end{funcdesc} |
| 201 | + |
0 commit comments