Fred Drake | c817e27 | 1998-08-10 18:40:22 +0000 | [diff] [blame] | 1 | \section{\module{EasyDialogs} --- |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 2 | Basic Macintosh dialogs} |
Fred Drake | fe7f3bc | 1998-07-23 17:55:31 +0000 | [diff] [blame] | 3 | |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{EasyDialogs} |
| 5 | \platform{Mac} |
Fred Drake | fe7f3bc | 1998-07-23 17:55:31 +0000 | [diff] [blame] | 6 | \modulesynopsis{Basic Macintosh dialogs.} |
| 7 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 8 | The \module{EasyDialogs} module contains some simple dialogs for the |
| 9 | Macintosh. All routines take an optional resource ID parameter \var{id} |
| 10 | with which one can override the \constant{DLOG} resource used for the |
| 11 | dialog, provided that the dialog items correspond (both type and item |
| 12 | number) to those in the default \constant{DLOG} resource. See source |
| 13 | code for details. |
Fred Drake | 4973b35 | 2000-08-30 14:33:02 +0000 | [diff] [blame] | 14 | |
Fred Drake | 41788db | 1998-04-04 06:23:02 +0000 | [diff] [blame] | 15 | The \module{EasyDialogs} module defines the following functions: |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame] | 16 | |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame] | 17 | |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 18 | \begin{funcdesc}{Message}{str\optional{, id\optional{, ok}}} |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 19 | Displays a modal dialog with the message text \var{str}, which should be |
| 20 | at most 255 characters long. The button text defaults to ``OK'', but is |
| 21 | set to the string argument \var{ok} if the latter is supplied. Control |
| 22 | is returned when the user clicks the ``OK'' button. |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame] | 23 | \end{funcdesc} |
| 24 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 25 | |
| 26 | \begin{funcdesc}{AskString}{prompt\optional{, default\optional{, |
| 27 | id\optional{, ok\optional{, cancel}}}}} |
| 28 | Asks the user to input a string value via a modal dialog. \var{prompt} |
| 29 | is the prompt message, and the optional \var{default} supplies the |
| 30 | initial value for the string (otherwise \code{""} is used). The text of |
| 31 | the ``OK'' and ``Cancel'' buttons can be changed with the \var{ok} and |
| 32 | \var{cancel} arguments. All strings can be at most 255 bytes long. |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 33 | \function{AskString()} returns the string entered or \constant{None} |
| 34 | in case the user cancelled. |
Fred Drake | eab58af | 2000-10-14 04:56:52 +0000 | [diff] [blame] | 35 | \end{funcdesc} |
| 36 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 37 | |
| 38 | \begin{funcdesc}{AskPassword}{prompt\optional{, default\optional{, |
| 39 | id\optional{, ok\optional{, cancel}}}}} |
| 40 | Asks the user to input a string value via a modal dialog. Like |
| 41 | \function{AskString()}, but with the text shown as bullets. The |
| 42 | arguments have the same meaning as for \function{AskString()}. |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame] | 43 | \end{funcdesc} |
| 44 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 45 | |
| 46 | \begin{funcdesc}{AskYesNoCancel}{question\optional{, default\optional{, |
| 47 | yes\optional{, no\optional{, cancel\optional{, id}}}}}} |
| 48 | Presents a dialog with prompt \var{question} and three buttons labelled |
| 49 | ``Yes'', ``No'', and ``Cancel''. Returns \code{1} for ``Yes'', \code{0} |
| 50 | for ``No'' and \code{-1} for ``Cancel''. The value of \var{default} (or |
| 51 | \code{0} if \var{default} is not supplied) is returned when the |
| 52 | \kbd{RETURN} key is pressed. The text of the buttons can be changed with |
| 53 | the \var{yes}, \var{no}, and \var{cancel} arguments; to prevent a button |
| 54 | from appearing, supply \code{""} for the corresponding argument. |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame] | 55 | \end{funcdesc} |
| 56 | |
Jack Jansen | 350b2b9 | 1995-11-14 10:30:27 +0000 | [diff] [blame] | 57 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 58 | \begin{funcdesc}{ProgressBar}{\optional{title\optional{, maxval\optional{, |
| 59 | label\optional{, id}}}}} |
| 60 | Displays a modeless progress-bar dialog. This is the constructor for the |
| 61 | \class{ProgressBar} class described below. \var{title} is the text |
| 62 | string displayed (default ``Working...''), \var{maxval} is the value at |
| 63 | which progress is complete (default \code{0}, indicating that an |
| 64 | indeterminate amount of work remains to be done), and \var{label} is |
| 65 | the text that is displayed above the progress bar itself. |
Jack Jansen | 350b2b9 | 1995-11-14 10:30:27 +0000 | [diff] [blame] | 66 | \end{funcdesc} |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 67 | |
| 68 | |
| 69 | \begin{funcdesc}{GetArgv}{\optional{optionlist\optional{ |
| 70 | commandlist\optional{, addoldfile\optional{, addnewfile\optional{, |
| 71 | addfolder\optional{, id}}}}}}} |
| 72 | Displays a dialog which aids the user in constructing a command-line |
| 73 | argument list. Returns the list in \code{sys.argv} format, suitable for |
| 74 | passing as an argument to \function{getopt.getopt()}. \var{addoldfile}, |
| 75 | \var{addnewfile}, and \var{addfolder} are boolean arguments. When |
| 76 | nonzero, they enable the user to insert into the command line paths to |
| 77 | an existing file, a (possibly) not-yet-existent file, and a folder, |
| 78 | respectively. (Note: Option arguments must appear in the command line |
| 79 | before file and folder arguments in order to be recognized by |
| 80 | \function{getopt.getopt()}.) Arguments containing spaces can be |
| 81 | specified by enclosing them within single or double quotes. A |
| 82 | \exception{SystemExit} exception is raised if the user presses the |
| 83 | ``Cancel'' button. |
| 84 | |
| 85 | \var{optionlist} is a list that determines a popup menu from which the |
| 86 | allowed options are selected. Its items can take one of two forms: |
| 87 | \var{optstr} or \code{(\var{optstr}, \var{descr})}. When present, |
| 88 | \var{descr} is a short descriptive string that is displayed in the |
| 89 | dialog while this option is selected in the popup menu. The |
| 90 | correspondence between \var{optstr}s and command-line arguments is: |
| 91 | |
| 92 | \begin{tableii}{l|l}{textrm}{\var{optstr} format}{Command-line format} |
| 93 | \lineii{\code{x}} |
| 94 | {\programopt{-x} (short option)} |
| 95 | \lineii{\code{x:} or \code{x=}} |
| 96 | {\programopt{-x} (short option with value)} |
| 97 | \lineii{\code{xyz}} |
| 98 | {\longprogramopt{xyz} (long option)} |
| 99 | \lineii{\code{xyz:} or \code{xyz=}} |
| 100 | {\longprogramopt{xyz} (long option with value)} |
| 101 | \end{tableii} |
| 102 | |
| 103 | \var{commandlist} is a list of items of the form \var{cmdstr} or |
| 104 | \code{(\var{cmdstr}, \var{descr})}, where \var{descr} is as above. The |
| 105 | \var{cmdstr}s will appear in a popup menu. When chosen, the text of |
| 106 | \var{cmdstr} will be appended to the command line as is, except that a |
| 107 | trailing \character{:} or \character{=} (if present) will be trimmed |
| 108 | off. |
| 109 | |
| 110 | \versionadded{2.0} |
| 111 | \end{funcdesc} |
| 112 | |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 113 | \begin{funcdesc}{AskFileForOpen}{ |
| 114 | \optional{message} |
| 115 | \optional{, typeList} |
| 116 | \optional{, defaultLocation} |
| 117 | \optional{, defaultOptionFlags} |
| 118 | \optional{, location} |
| 119 | \optional{, clientName} |
| 120 | \optional{, windowTitle} |
| 121 | \optional{, actionButtonLabel} |
| 122 | \optional{, cancelButtonLabel} |
| 123 | \optional{, preferenceKey} |
| 124 | \optional{, popupExtension} |
| 125 | \optional{, eventProc} |
| 126 | \optional{, previewProc} |
| 127 | \optional{, filterProc} |
| 128 | \optional{, wanted} |
| 129 | } |
| 130 | Post a dialog asking the user for a file to open, and return the file |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 131 | selected or \constant{None} if the user cancelled. |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 132 | \var{message} is a text message to display, |
| 133 | \var{typeList} is a list of 4-char filetypes allowable, |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 134 | \var{defaultLocation} is the pathname, \class{FSSpec} or \class{FSRef} |
| 135 | of the folder to show initially, |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 136 | \var{location} is the \code{(x, y)} position on the screen where the |
| 137 | dialog is shown, |
Neal Norwitz | 1ecbd67 | 2003-12-14 15:02:54 +0000 | [diff] [blame] | 138 | \var{actionButtonLabel} is a string to show instead of ``Open'' in the |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 139 | OK button, |
Neal Norwitz | 1ecbd67 | 2003-12-14 15:02:54 +0000 | [diff] [blame] | 140 | \var{cancelButtonLabel} is a string to show instead of ``Cancel'' in the |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 141 | cancel button, |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 142 | \var{wanted} is the type of value wanted as a return: \class{str}, |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 143 | \class{unicode}, \class{FSSpec}, \class{FSRef} and subtypes thereof are |
| 144 | acceptable. |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 145 | |
Fred Drake | a1a1dba | 2003-09-05 14:06:35 +0000 | [diff] [blame] | 146 | \index{Navigation Services} |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 147 | For a description of the other arguments please see the Apple Navigation |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 148 | Services documentation and the \module{EasyDialogs} source code. |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 149 | \end{funcdesc} |
| 150 | |
| 151 | \begin{funcdesc}{AskFileForSave}{ |
| 152 | \optional{message} |
| 153 | \optional{, savedFileName} |
| 154 | \optional{, defaultLocation} |
| 155 | \optional{, defaultOptionFlags} |
| 156 | \optional{, location} |
| 157 | \optional{, clientName} |
| 158 | \optional{, windowTitle} |
| 159 | \optional{, actionButtonLabel} |
| 160 | \optional{, cancelButtonLabel} |
| 161 | \optional{, preferenceKey} |
| 162 | \optional{, popupExtension} |
| 163 | \optional{, fileType} |
| 164 | \optional{, fileCreator} |
| 165 | \optional{, eventProc} |
| 166 | \optional{, wanted} |
| 167 | } |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 168 | Post a dialog asking the user for a file to save to, and return the |
| 169 | file selected or \constant{None} if the user cancelled. |
| 170 | \var{savedFileName} is the default for the file name to save to (the |
| 171 | return value). See \function{AskFileForOpen()} for a description of |
| 172 | the other arguments. |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 173 | \end{funcdesc} |
| 174 | |
| 175 | \begin{funcdesc}{AskFolder}{ |
| 176 | \optional{message} |
| 177 | \optional{, defaultLocation} |
| 178 | \optional{, defaultOptionFlags} |
| 179 | \optional{, location} |
| 180 | \optional{, clientName} |
| 181 | \optional{, windowTitle} |
| 182 | \optional{, actionButtonLabel} |
| 183 | \optional{, cancelButtonLabel} |
| 184 | \optional{, preferenceKey} |
| 185 | \optional{, popupExtension} |
| 186 | \optional{, eventProc} |
| 187 | \optional{, filterProc} |
| 188 | \optional{, wanted} |
| 189 | } |
Fred Drake | b24e84c | 2003-09-05 13:48:02 +0000 | [diff] [blame] | 190 | Post a dialog asking the user to select a folder, and return the |
| 191 | folder selected or \constant{None} if the user cancelled. See |
| 192 | \function{AskFileForOpen()} for a description of the arguments. |
Jack Jansen | 7aeba45 | 2003-02-12 09:58:33 +0000 | [diff] [blame] | 193 | \end{funcdesc} |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 194 | |
Fred Drake | 911e571 | 2003-09-05 13:59:10 +0000 | [diff] [blame] | 195 | |
| 196 | \begin{seealso} |
| 197 | \seetitle |
| 198 | [http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/] |
| 199 | {Navigation Services Reference}{Programmer's reference documentation |
| 200 | for the Navigation Services, a part of the Carbon framework.} |
| 201 | \end{seealso} |
| 202 | |
| 203 | |
Fred Drake | 8a5a270 | 2002-04-15 19:53:35 +0000 | [diff] [blame] | 204 | \subsection{ProgressBar Objects \label{progressbar-objects}} |
| 205 | |
| 206 | \class{ProgressBar} objects provide support for modeless progress-bar |
| 207 | dialogs. Both determinate (thermometer style) and indeterminate |
| 208 | (barber-pole style) progress bars are supported. The bar will be |
| 209 | determinate if its maximum value is greater than zero; otherwise it |
| 210 | will be indeterminate. |
| 211 | \versionchanged[Support for indeterminate-style progress bars was |
| 212 | added]{2.2} |
| 213 | |
| 214 | The dialog is displayed immediately after creation. If the dialog's |
| 215 | ``Cancel'' button is pressed, or if \kbd{Cmd-.} or \kbd{ESC} is typed, |
| 216 | the dialog window is hidden and \exception{KeyboardInterrupt} is |
| 217 | raised (but note that this response does not occur until the progress |
| 218 | bar is next updated, typically via a call to \method{inc()} or |
| 219 | \method{set()}). Otherwise, the bar remains visible until the |
| 220 | \class{ProgressBar} object is discarded. |
| 221 | |
| 222 | \class{ProgressBar} objects possess the following attributes and |
| 223 | methods: |
| 224 | |
| 225 | \begin{memberdesc}[ProgressBar]{curval} |
| 226 | The current value (of type integer or long integer) of the progress |
| 227 | bar. The normal access methods coerce \member{curval} between |
| 228 | \code{0} and \member{maxval}. This attribute should not be altered |
| 229 | directly. |
| 230 | \end{memberdesc} |
| 231 | |
| 232 | \begin{memberdesc}[ProgressBar]{maxval} |
| 233 | The maximum value (of type integer or long integer) of the progress |
| 234 | bar; the progress bar (thermometer style) is full when \member{curval} |
| 235 | equals \member{maxval}. If \member{maxval} is \code{0}, the bar will |
| 236 | be indeterminate (barber-pole). This attribute should not be altered |
| 237 | directly. |
| 238 | \end{memberdesc} |
| 239 | |
| 240 | \begin{methoddesc}[ProgressBar]{title}{\optional{newstr}} |
| 241 | Sets the text in the title bar of the progress dialog to |
| 242 | \var{newstr}. |
| 243 | \end{methoddesc} |
| 244 | |
| 245 | \begin{methoddesc}[ProgressBar]{label}{\optional{newstr}} |
| 246 | Sets the text in the progress box of the progress dialog to |
| 247 | \var{newstr}. |
| 248 | \end{methoddesc} |
| 249 | |
| 250 | \begin{methoddesc}[ProgressBar]{set}{value\optional{, max}} |
| 251 | Sets the progress bar's \member{curval} to \var{value}, and also |
| 252 | \member{maxval} to \var{max} if the latter is provided. \var{value} |
| 253 | is first coerced between 0 and \member{maxval}. The thermometer bar |
| 254 | is updated to reflect the changes, including a change from |
| 255 | indeterminate to determinate or vice versa. |
| 256 | \end{methoddesc} |
| 257 | |
| 258 | \begin{methoddesc}[ProgressBar]{inc}{\optional{n}} |
| 259 | Increments the progress bar's \member{curval} by \var{n}, or by \code{1} |
| 260 | if \var{n} is not provided. (Note that \var{n} may be negative, in |
| 261 | which case the effect is a decrement.) The progress bar is updated to |
| 262 | reflect the change. If the bar is indeterminate, this causes one |
| 263 | ``spin'' of the barber pole. The resulting \member{curval} is coerced |
| 264 | between 0 and \member{maxval} if incrementing causes it to fall |
| 265 | outside this range. |
| 266 | \end{methoddesc} |