Doc/mac/libmacui.tex

   1 \section{\module{EasyDialogs} ---
   2          Basic Macintosh dialogs}
   3
   4 \declaremodule{standard}{EasyDialogs}
   5   \platform{Mac}
   6 \modulesynopsis{Basic Macintosh dialogs.}
   7
   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.
  14
  15 The \module{EasyDialogs} module defines the following functions:
  16
  17
  18 \begin{funcdesc}{Message}{str\optional{, id\optional{, ok}}}
  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.
  23 \end{funcdesc}
  24
  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.
  33 \function{AskString()} returns the string entered or \constant{None}
  34 in case the user cancelled.
  35 \end{funcdesc}
  36
  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()}.
  43 \end{funcdesc}
  44
  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.
  55 \end{funcdesc}
  56
  57
  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.
  66 \end{funcdesc}
  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
 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
 131 selected or \constant{None} if the user cancelled.
 132 \var{message} is a text message to display,
 133 \var{typeList} is a list of 4-char filetypes allowable,
 134 \var{defaultLocation} is the pathname, \class{FSSpec} or \class{FSRef}
 135 of the folder to show initially,
 136 \var{location} is the \code{(x, y)} position on the screen where the
 137 dialog is shown,
 138 \var{actionButtonLabel} is a string to show instead of ``Open'' in the
 139 OK button,
 140 \var{cancelButtonLabel} is a string to show instead of ``Cancel'' in the
 141 cancel button,
 142 \var{wanted} is the type of value wanted as a return: \class{str},
 143 \class{unicode}, \class{FSSpec}, \class{FSRef} and subtypes thereof are
 144 acceptable.
 145
 146 \index{Navigation Services}
 147 For a description of the other arguments please see the Apple Navigation
 148 Services documentation and the \module{EasyDialogs} source code.
 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         }
 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.
 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         }
 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.
 193 \end{funcdesc}
 194
 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
 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}