diff options
| -rw-r--r-- | Doc/mac/libmacui.tex | 197 |
1 files changed, 157 insertions, 40 deletions
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex index 053176e..a3018ec 100644 --- a/Doc/mac/libmacui.tex +++ b/Doc/mac/libmacui.tex @@ -5,56 +5,173 @@ \platform{Mac} \modulesynopsis{Basic Macintosh dialogs.} - -The \module{EasyDialogs} module contains some simple dialogs for -the Macintosh. All routines have an optional parameter \var{id} with -which you can override the DLOG resource used for the dialog, as long -as the item numbers correspond. See the source for details. +The \module{EasyDialogs} module contains some simple dialogs for the +Macintosh. All routines take an optional resource ID parameter \var{id} +with which one can override the \constant{DLOG} resource used for the +dialog, provided that the dialog items correspond (both type and item +number) to those in the default \constant{DLOG} resource. See source +code for details. The \module{EasyDialogs} module defines the following functions: -\begin{funcdesc}{Message}{str} -A modal dialog with the message text \var{str}, which should be at -most 255 characters long, is displayed. Control is returned when the -user clicks ``OK''. +\begin{funcdesc}{Message}{str\optional{, id\optional{, ok=None}}} +Displays a modal dialog with the message text \var{str}, which should be +at most 255 characters long. The button text defaults to ``OK'', but is +set to the string argument \var{ok} if the latter is supplied. Control +is returned when the user clicks the ``OK'' button. +\end{funcdesc} + + +\begin{funcdesc}{AskString}{prompt\optional{, default\optional{, + id\optional{, ok\optional{, cancel}}}}} +Asks the user to input a string value via a modal dialog. \var{prompt} +is the prompt message, and the optional \var{default} supplies the +initial value for the string (otherwise \code{""} is used). The text of +the ``OK'' and ``Cancel'' buttons can be changed with the \var{ok} and +\var{cancel} arguments. All strings can be at most 255 bytes long. +\function{AskString()} returns the string entered or \code{None} in case +the user cancelled. \end{funcdesc} -\begin{funcdesc}{AskString}{prompt\optional{, default}} -Ask the user to input a string value, in a modal dialog. \var{prompt} -is the prompt message, the optional \var{default} arg is the initial -value for the string. All strings can be at most 255 bytes -long. \function{AskString()} returns the string entered or \code{None} -in case the user cancelled. + +\begin{funcdesc}{AskPassword}{prompt\optional{, default\optional{, + id\optional{, ok\optional{, cancel}}}}} +Asks the user to input a string value via a modal dialog. Like +\function{AskString()}, but with the text shown as bullets. The +arguments have the same meaning as for \function{AskString()}. \end{funcdesc} -\begin{funcdesc}{AskPassword}{prompt\optional{, default}} -Ask the user to input a string value, in a modal dialog. Like -\method{AskString}, but with the text shown as bullets. \var{prompt} -is the prompt message, the optional \var{default} arg is the initial -value for the string. All strings can be at most 255 bytes -long. \function{AskString()} returns the string entered or \code{None} -in case the user cancelled. + +\begin{funcdesc}{AskYesNoCancel}{question\optional{, default\optional{, + yes\optional{, no\optional{, cancel\optional{, id}}}}}} +Presents a dialog with prompt \var{question} and three buttons labelled +``Yes'', ``No'', and ``Cancel''. Returns \code{1} for ``Yes'', \code{0} +for ``No'' and \code{-1} for ``Cancel''. The value of \var{default} (or +\code{0} if \var{default} is not supplied) is returned when the +\kbd{RETURN} key is pressed. The text of the buttons can be changed with +the \var{yes}, \var{no}, and \var{cancel} arguments; to prevent a button +from appearing, supply \code{""} for the corresponding argument. \end{funcdesc} -\begin{funcdesc}{AskYesNoCancel}{question\optional{, default}} -Present a dialog with text \var{question} and three buttons labelled -``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for -no and \code{-1} for cancel. The default return value chosen by -hitting return is \code{0}. This can be changed with the optional -\var{default} argument. + +\begin{funcdesc}{ProgressBar}{\optional{title\optional{, maxval\optional{, + label\optional{, id}}}}} +Displays a modeless progress-bar dialog. This is the constructor for the +\class{ProgressBar} class described below. \var{title} is the text +string displayed (default ``Working...''), \var{maxval} is the value at +which progress is complete (default \code{0}, indicating that an +indeterminate amount of work remains to be done), and \var{label} is +the text that is displayed above the progress bar itself. \end{funcdesc} -\begin{funcdesc}{ProgressBar}{\optional{title \optional{, maxval\optional{,label}}}} -Display a modeless progress dialog with a thermometer bar. \var{title} -is the text string displayed (default ``Working...''), \var{maxval} is -the value at which progress is complete (default -\code{100}). \var{label} is the text that is displayed over the progress -bar itself. The returned object has two methods, -\code{set(\var{value})}, which sets the value of the progress bar, and -\code{label(\var{text})}, which sets the text of the label. The bar -remains visible until the object returned is discarded. - -The progress bar has a ``cancel'' button. [NOTE: how does the cancel -button behave?] + +\begin{funcdesc}{GetArgv}{\optional{optionlist\optional{ + commandlist\optional{, addoldfile\optional{, addnewfile\optional{, + addfolder\optional{, id}}}}}}} +Displays a dialog which aids the user in constructing a command-line +argument list. Returns the list in \code{sys.argv} format, suitable for +passing as an argument to \function{getopt.getopt()}. \var{addoldfile}, +\var{addnewfile}, and \var{addfolder} are boolean arguments. When +nonzero, they enable the user to insert into the command line paths to +an existing file, a (possibly) not-yet-existent file, and a folder, +respectively. (Note: Option arguments must appear in the command line +before file and folder arguments in order to be recognized by +\function{getopt.getopt()}.) Arguments containing spaces can be +specified by enclosing them within single or double quotes. A +\exception{SystemExit} exception is raised if the user presses the +``Cancel'' button. + +\var{optionlist} is a list that determines a popup menu from which the +allowed options are selected. Its items can take one of two forms: +\var{optstr} or \code{(\var{optstr}, \var{descr})}. When present, +\var{descr} is a short descriptive string that is displayed in the +dialog while this option is selected in the popup menu. The +correspondence between \var{optstr}s and command-line arguments is: + +\begin{tableii}{l|l}{textrm}{\var{optstr} format}{Command-line format} +\lineii{\code{x}} + {\programopt{-x} (short option)} +\lineii{\code{x:} or \code{x=}} + {\programopt{-x} (short option with value)} +\lineii{\code{xyz}} + {\longprogramopt{xyz} (long option)} +\lineii{\code{xyz:} or \code{xyz=}} + {\longprogramopt{xyz} (long option with value)} +\end{tableii} + +\var{commandlist} is a list of items of the form \var{cmdstr} or +\code{(\var{cmdstr}, \var{descr})}, where \var{descr} is as above. The +\var{cmdstr}s will appear in a popup menu. When chosen, the text of +\var{cmdstr} will be appended to the command line as is, except that a +trailing \character{:} or \character{=} (if present) will be trimmed +off. + +\versionadded{2.0} \end{funcdesc} + + + +\subsection{ProgressBar Objects \label{progressbar-objects}} + +\class{ProgressBar} objects provide support for modeless progress-bar +dialogs. Both determinate (thermometer style) and indeterminate +(barber-pole style) progress bars are supported. The bar will be +determinate if its maximum value is greater than zero; otherwise it +will be indeterminate. +\versionchanged[Support for indeterminate-style progress bars was + added]{2.2} + +The dialog is displayed immediately after creation. If the dialog's +``Cancel'' button is pressed, or if \kbd{Cmd-.} or \kbd{ESC} is typed, +the dialog window is hidden and \exception{KeyboardInterrupt} is +raised (but note that this response does not occur until the progress +bar is next updated, typically via a call to \method{inc()} or +\method{set()}). Otherwise, the bar remains visible until the +\class{ProgressBar} object is discarded. + +\class{ProgressBar} objects possess the following attributes and +methods: + +\begin{memberdesc}[ProgressBar]{curval} +The current value (of type integer or long integer) of the progress +bar. The normal access methods coerce \member{curval} between +\code{0} and \member{maxval}. This attribute should not be altered +directly. +\end{memberdesc} + +\begin{memberdesc}[ProgressBar]{maxval} +The maximum value (of type integer or long integer) of the progress +bar; the progress bar (thermometer style) is full when \member{curval} +equals \member{maxval}. If \member{maxval} is \code{0}, the bar will +be indeterminate (barber-pole). This attribute should not be altered +directly. +\end{memberdesc} + +\begin{methoddesc}[ProgressBar]{title}{\optional{newstr}} +Sets the text in the title bar of the progress dialog to +\var{newstr}. +\end{methoddesc} + +\begin{methoddesc}[ProgressBar]{label}{\optional{newstr}} +Sets the text in the progress box of the progress dialog to +\var{newstr}. +\end{methoddesc} + +\begin{methoddesc}[ProgressBar]{set}{value\optional{, max}} +Sets the progress bar's \member{curval} to \var{value}, and also +\member{maxval} to \var{max} if the latter is provided. \var{value} +is first coerced between 0 and \member{maxval}. The thermometer bar +is updated to reflect the changes, including a change from +indeterminate to determinate or vice versa. +\end{methoddesc} + +\begin{methoddesc}[ProgressBar]{inc}{\optional{n}} +Increments the progress bar's \member{curval} by \var{n}, or by \code{1} +if \var{n} is not provided. (Note that \var{n} may be negative, in +which case the effect is a decrement.) The progress bar is updated to +reflect the change. If the bar is indeterminate, this causes one +``spin'' of the barber pole. The resulting \member{curval} is coerced +between 0 and \member{maxval} if incrementing causes it to fall +outside this range. +\end{methoddesc} |