Doc/mac/libmacui.tex

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