# 2.10 `EasyDialogs` -- Basic Macintosh dialogs

Availability: Macintosh.

The `EasyDialogs` module contains some simple dialogs for the Macintosh. 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.

The `EasyDialogs` module defines the following functions:

`Message`(str[, id[, ok=None]])
  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.

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

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

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

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

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

Subsections

- 2.10.1 ProgressBar Objects