\section{\module{EasyDialogs} ---         Basic Macintosh dialogs} \declaremodule{standard}{EasyDialogs}  \platform{Mac}\modulesynopsis{Basic Macintosh dialogs.} The \module{EasyDialogs} module contains some simple dialogs for theMacintosh. All routines take an optional resource ID parameter \var{id}with which one can override the \constant{DLOG} resource used for thedialog, provided that the dialog items correspond (both type and itemnumber) to those in the default \constant{DLOG} resource. See sourcecode for details. The \module{EasyDialogs} module defines the following functions:  \begin{funcdesc}{Message}{str\optional{, id\optional{, ok}}}Displays a modal dialog with the message text \var{str}, which should beat most 255 characters long. The button text defaults to ``OK'', but isset to the string argument \var{ok} if the latter is supplied. Controlis 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 theinitial value for the string (otherwise \code{""} is used). The text ofthe ``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 \constant{None}in case the user cancelled.\end{funcdesc}  \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. Thearguments have the same meaning as for \function{AskString()}.\end{funcdesc}  \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 withthe \var{yes}, \var{no}, and \var{cancel} arguments; to prevent a buttonfrom appearing, supply \code{""} for the corresponding argument.\end{funcdesc}  \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 textstring displayed (default ``Working...''), \var{maxval} is the value atwhich progress is complete (default \code{0}, indicating that anindeterminate amount of work remains to be done), and \var{label} isthe text that is displayed above the progress bar itself.\end{funcdesc}  \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-lineargument list.  Returns the list in \code{sys.argv} format, suitable forpassing as an argument to \function{getopt.getopt()}.  \var{addoldfile},\var{addnewfile}, and \var{addfolder} are boolean arguments.  Whennonzero, they enable the user to insert into the command line paths toan existing file, a (possibly) not-yet-existent file, and a folder,respectively.  (Note: Option arguments must appear in the command linebefore file and folder arguments in order to be recognized by\function{getopt.getopt()}.)  Arguments containing spaces can bespecified 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 theallowed 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 thedialog while this option is selected in the popup menu.  Thecorrespondence 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 atrailing \character{:} or \character{=} (if present) will be trimmedoff. \versionadded{2.0}\end{funcdesc} \begin{funcdesc}{AskFileForOpen}{	\optional{message}	\optional{, typeList}	\optional{, defaultLocation}	\optional{, defaultOptionFlags}	\optional{, location}	\optional{, clientName}	\optional{, windowTitle}	\optional{, actionButtonLabel}	\optional{, cancelButtonLabel}	\optional{, preferenceKey}	\optional{, popupExtension}	\optional{, eventProc}	\optional{, previewProc}	\optional{, filterProc}	\optional{, wanted}	}Post a dialog asking the user for a file to open, and return the fileselected or \constant{None} if the user cancelled.\var{message} is a text message to display,\var{typeList} is a list of 4-char filetypes allowable,\var{defaultLocation} is the pathname, \class{FSSpec} or \class{FSRef}of the folder to show initially,\var{location} is the \code{(x, y)} position on the screen where thedialog is shown,\var{actionButtonLabel} is a string to show instead of ``Open'' in theOK button,\var{cancelButtonLabel} is a string to show instead of ``Cancel'' in thecancel button,\var{wanted} is the type of value wanted as a return: \class{str},\class{unicode}, \class{FSSpec}, \class{FSRef} and subtypes thereof areacceptable. \index{Navigation Services}For a description of the other arguments please see the Apple NavigationServices documentation and the \module{EasyDialogs} source code.\end{funcdesc} \begin{funcdesc}{AskFileForSave}{	\optional{message}	\optional{, savedFileName}	\optional{, defaultLocation}	\optional{, defaultOptionFlags}	\optional{, location}	\optional{, clientName}	\optional{, windowTitle}	\optional{, actionButtonLabel}	\optional{, cancelButtonLabel}	\optional{, preferenceKey}	\optional{, popupExtension}	\optional{, fileType}	\optional{, fileCreator}	\optional{, eventProc}	\optional{, wanted}	}Post a dialog asking the user for a file to save to, and return thefile selected or \constant{None} if the user cancelled.\var{savedFileName} is the default for the file name to save to (thereturn value). See \function{AskFileForOpen()} for a description ofthe other arguments.\end{funcdesc} \begin{funcdesc}{AskFolder}{	\optional{message}	\optional{, defaultLocation}	\optional{, defaultOptionFlags}	\optional{, location}	\optional{, clientName}	\optional{, windowTitle}	\optional{, actionButtonLabel}	\optional{, cancelButtonLabel}	\optional{, preferenceKey}	\optional{, popupExtension}	\optional{, eventProc}	\optional{, filterProc}	\optional{, wanted}	}Post a dialog asking the user to select a folder, and return thefolder selected or \constant{None} if the user cancelled. See\function{AskFileForOpen()} for a description of the arguments.\end{funcdesc}  \begin{seealso}  \seetitle  [http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/]  {Navigation Services Reference}{Programmer's reference documentation  for the Navigation Services, a part of the Carbon framework.}\end{seealso}  \subsection{ProgressBar Objects \label{progressbar-objects}} \class{ProgressBar} objects provide support for modeless progress-bardialogs.  Both determinate (thermometer style) and indeterminate(barber-pole style) progress bars are supported.  The bar will bedeterminate if its maximum value is greater than zero; otherwise itwill 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} israised (but note that this response does not occur until the progressbar 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 andmethods: \begin{memberdesc}[ProgressBar]{curval}The current value (of type integer or long integer) of the progressbar.  The normal access methods coerce \member{curval} between\code{0} and \member{maxval}.  This attribute should not be altereddirectly.\end{memberdesc} \begin{memberdesc}[ProgressBar]{maxval}The maximum value (of type integer or long integer) of the progressbar; the progress bar (thermometer style) is full when \member{curval}equals \member{maxval}.  If \member{maxval} is \code{0}, the bar willbe indeterminate (barber-pole).  This attribute should not be altereddirectly.\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 baris updated to reflect the changes, including a change fromindeterminate 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, inwhich case the effect is a decrement.)  The progress bar is updated toreflect the change.  If the bar is indeterminate, this causes one``spin'' of the barber pole.  The resulting \member{curval} is coercedbetween 0 and \member{maxval} if incrementing causes it to falloutside this range.\end{methoddesc}