Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame^] | 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 | |