
``EasyDialogs`` --- Basic Macintosh dialogs
*******************************************

Platform: Mac

*Platforms: *Mac

The ``EasyDialogs`` module contains some simple dialogs for the
Macintosh. The dialogs get launched in a separate application which
appears in the dock and must be clicked on for the dialogs be
displayed.  All routines take an optional resource ID parameter *id*
with which one can override the ``DLOG`` resource used for the dialog,
provided that the dialog items correspond (both type and item number)
to those in the default ``DLOG`` resource. See source code for
details.

Warning: This module is removed in 3.0.

The ``EasyDialogs`` module defines the following functions:

EasyDialogs.Message(str[, id[, ok]])

   Displays a modal dialog with the message text *str*, which should
   be at most 255 characters long. The button text defaults to "OK",
   but is set to the string argument *ok* if the latter is supplied.
   Control is returned when the user clicks the "OK" button.

EasyDialogs.AskString(prompt[, default[, id[, ok[, cancel]]]])

   Asks the user to input a string value via a modal dialog. *prompt*
   is the prompt message, and the optional *default* supplies the
   initial value for the string (otherwise ``""`` is used). The text
   of the "OK" and "Cancel" buttons can be changed with the *ok* and
   *cancel* arguments. All strings can be at most 255 bytes long.
   ``AskString()`` returns the string entered or ``None`` in case the
   user cancelled.

EasyDialogs.AskPassword(prompt[, default[, id[, ok[, cancel]]]])

   Asks the user to input a string value via a modal dialog. Like
   ``AskString()``, but with the text shown as bullets. The arguments
   have the same meaning as for ``AskString()``.

EasyDialogs.AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])

   Presents a dialog with prompt *question* and three buttons labelled
   "Yes", "No", and "Cancel". Returns ``1`` for "Yes", ``0`` for "No"
   and ``-1`` for "Cancel". The value of *default* (or ``0`` if
   *default* is not supplied) is returned when the ``RETURN`` key is
   pressed. The text of the buttons can be changed with the *yes*,
   *no*, and *cancel* arguments; to prevent a button from appearing,
   supply ``""`` for the corresponding argument.

EasyDialogs.ProgressBar([title[, maxval[, label[, id]]]])

   Displays a modeless progress-bar dialog. This is the constructor
   for the ``ProgressBar`` class described below. *title* is the text
   string displayed (default "Working..."), *maxval* is the value at
   which progress is complete (default ``0``, indicating that an
   indeterminate amount of work remains to be done), and *label* is
   the text that is displayed above the progress bar itself.

EasyDialogs.GetArgv([optionlist[, commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])

   Displays a dialog which aids the user in constructing a command-
   line argument list.  Returns the list in ``sys.argv`` format,
   suitable for passing as an argument to ``getopt.getopt()``.
   *addoldfile*, *addnewfile*, and *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 ``getopt.getopt()``.)  Arguments containing spaces
   can be specified by enclosing them within single or double quotes.
   A ``SystemExit`` exception is raised if the user presses the
   "Cancel" button.

   *optionlist* is a list that determines a popup menu from which the
   allowed options are selected.  Its items can take one of two forms:
   *optstr* or ``(optstr, descr)``.  When present, *descr* is a short
   descriptive string that is displayed in the dialog while this
   option is selected in the popup menu.  The correspondence between
   *optstr*s and command-line arguments is:

   +------------------------+--------------------------------------------+
   | *optstr* format        | Command-line format                        |
   +========================+============================================+
   | ``x``                  | *-x* (short option)                        |
   +------------------------+--------------------------------------------+
   | ``x:`` or ``x=``       | *-x* (short option with value)             |
   +------------------------+--------------------------------------------+
   | ``xyz``                | *--xyz* (long option)                      |
   +------------------------+--------------------------------------------+
   | ``xyz:`` or ``xyz=``   | *--xyz* (long option with value)           |
   +------------------------+--------------------------------------------+

   *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr,
   descr)``, where *descr* is as above.  The *cmdstr*s will appear in
   a popup menu.  When chosen, the text of *cmdstr* will be appended
   to the command line as is, except that a trailing ``':'`` or
   ``'='`` (if present) will be trimmed off.

   New in version 2.0.

EasyDialogs.AskFileForOpen([message][, typeList][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, eventProc][, previewProc][, filterProc][, wanted])

   Post a dialog asking the user for a file to open, and return the
   file selected or ``None`` if the user cancelled. *message* is a
   text message to display, *typeList* is a list of 4-char filetypes
   allowable, *defaultLocation* is the pathname, ``FSSpec`` or
   ``FSRef`` of the folder to show initially, *location* is the ``(x,
   y)`` position on the screen where the dialog is shown,
   *actionButtonLabel* is a string to show instead of "Open" in the OK
   button, *cancelButtonLabel* is a string to show instead of "Cancel"
   in the cancel button, *wanted* is the type of value wanted as a
   return: ``str``, ``unicode``, ``FSSpec``, ``FSRef`` and subtypes
   thereof are acceptable.

   For a description of the other arguments please see the Apple
   Navigation Services documentation and the ``EasyDialogs`` source
   code.

EasyDialogs.AskFileForSave([message][, savedFileName][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, fileType][, fileCreator][, eventProc][, wanted])

   Post a dialog asking the user for a file to save to, and return the
   file selected or ``None`` if the user cancelled. *savedFileName* is
   the default for the file name to save to (the return value). See
   ``AskFileForOpen()`` for a description of the other arguments.

EasyDialogs.AskFolder([message][, defaultLocation][, defaultOptionFlags][, location][, clientName][, windowTitle][, actionButtonLabel][, cancelButtonLabel][, preferenceKey][, popupExtension][, eventProc][, filterProc][, wanted])

   Post a dialog asking the user to select a folder, and return the
   folder selected or ``None`` if the user cancelled. See
   ``AskFileForOpen()`` for a description of the arguments.

See also:

   Navigation Services Reference
      Programmer's reference documentation for the Navigation
      Services, a part of the Carbon framework.


ProgressBar Objects
===================

``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.

Changed in version 2.2: Support for indeterminate-style progress bars
was added.

The dialog is displayed immediately after creation. If the dialog's
"Cancel" button is pressed, or if ``Cmd-.`` or ``ESC`` is typed, the
dialog window is hidden and ``KeyboardInterrupt`` is raised (but note
that this response does not occur until the progress bar is next
updated, typically via a call to ``inc()`` or ``set()``).  Otherwise,
the bar remains visible until the ``ProgressBar`` object is discarded.

``ProgressBar`` objects possess the following attributes and methods:

ProgressBar.curval

   The current value (of type integer or long integer) of the progress
   bar.  The normal access methods coerce ``curval`` between ``0`` and
   ``maxval``. This attribute should not be altered directly.

ProgressBar.maxval

   The maximum value (of type integer or long integer) of the progress
   bar; the progress bar (thermometer style) is full when ``curval``
   equals ``maxval``.  If ``maxval`` is ``0``, the bar will be
   indeterminate (barber-pole).  This attribute should not be altered
   directly.

ProgressBar.title([newstr])

   Sets the text in the title bar of the progress dialog to *newstr*.

ProgressBar.label([newstr])

   Sets the text in the progress box of the progress dialog to
   *newstr*.

ProgressBar.set(value[, max])

   Sets the progress bar's ``curval`` to *value*, and also ``maxval``
   to *max* if the latter is provided.  *value* is first coerced
   between 0 and ``maxval``.  The thermometer bar is updated to
   reflect the changes, including a change from indeterminate to
   determinate or vice versa.

ProgressBar.inc([n])

   Increments the progress bar's ``curval`` by *n*, or by ``1`` if *n*
   is not provided.  (Note that *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 ``curval`` is coerced between 0 and
   ``maxval`` if incrementing causes it to fall outside this range.
