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
   9 The \module{EasyDialogs} module contains some simple dialogs for
  10 the Macintosh, modelled after the
  11 \module{stdwin}\refbimodindex{stdwin} dialogs with similar names. All
  12 routines have an optional parameter \var{id} with which you can
  13 override the DLOG resource used for the dialog, as long as the item
  14 numbers correspond. See the source for details.
  15
  16 The \module{EasyDialogs} module defines the following functions:
  17
  18
  19 \begin{funcdesc}{Message}{str}
  20 A modal dialog with the message text \var{str}, which should be at
  21 most 255 characters long, is displayed. Control is returned when the
  22 user clicks ``OK''.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{AskString}{prompt\optional{, default}}
  26 Ask the user to input a string value, in a modal dialog. \var{prompt}
  27 is the promt message, the optional \var{default} arg is the initial
  28 value for the string. All strings can be at most 255 bytes
  29 long. \function{AskString()} returns the string entered or \code{None}
  30 in case the user cancelled.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{AskYesNoCancel}{question\optional{, default}}
  34 Present a dialog with text \var{question} and three buttons labelled
  35 ``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for
  36 no and \code{-1} for cancel. The default return value chosen by
  37 hitting return is \code{0}. This can be changed with the optional
  38 \var{default} argument.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{ProgressBar}{\optional{label\optional{, maxval}}}
  42 Display a modeless progress dialog with a thermometer bar. \var{label}
  43 is the text string displayed (default ``Working...''), \var{maxval} is
  44 the value at which progress is complete (default \code{100}). The
  45 returned object has one method, \code{set(\var{value})}, which sets
  46 the value of the progress bar. The bar remains visible until the
  47 object returned is discarded.
  48
  49 The progress bar has a ``cancel'' button, but it is currently
  50 non-functional.
  51 \end{funcdesc}
  52
  53 Note that \module{EasyDialogs} does not currently use the notification
  54 manager. This means that displaying dialogs while the program is in
  55 the background will lead to unexpected results and possibly
  56 crashes. Also, all dialogs are modeless and hence expect to be at the
  57 top of the stacking order. This is true when the dialogs are created,
  58 but windows that pop-up later (like a console window) may also result
  59 in crashes.