Doc/library/easydialogs.rst

   1
   2 :mod:`EasyDialogs` --- Basic Macintosh dialogs
   3 ==============================================
   4
   5 .. module:: EasyDialogs
   6    :platform: Mac
   7    :synopsis: Basic Macintosh dialogs.
   8    :deprecated:
   9
  10
  11 The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
  12 The dialogs get launched in a separate application which appears in the dock and
  13 must be clicked on for the dialogs be displayed.  All routines take an optional
  14 resource ID parameter *id* with which one can override the :const:`DLOG`
  15 resource used for the dialog, provided that the dialog items correspond (both
  16 type and item number) to those in the default :const:`DLOG` resource. See source
  17 code for details.
  18
  19 .. warning::
  20
  21    This module is removed in 3.0.
  22
  23
  24 The :mod:`EasyDialogs` module defines the following functions:
  25
  26
  27 .. function:: Message(str[, id[, ok]])
  28
  29    Displays a modal dialog with the message text *str*, which should be at most 255
  30    characters long. The button text defaults to "OK", but is set to the string
  31    argument *ok* if the latter is supplied. Control is returned when the user
  32    clicks the "OK" button.
  33
  34
  35 .. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
  36
  37    Asks the user to input a string value via a modal dialog. *prompt* is the prompt
  38    message, and the optional *default* supplies the initial value for the string
  39    (otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
  40    changed with the *ok* and *cancel* arguments. All strings can be at most 255
  41    bytes long. :func:`AskString` returns the string entered or :const:`None` in
  42    case the user cancelled.
  43
  44
  45 .. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
  46
  47    Asks the user to input a string value via a modal dialog. Like
  48    :func:`AskString`, but with the text shown as bullets. The arguments have the
  49    same meaning as for :func:`AskString`.
  50
  51
  52 .. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
  53
  54    Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
  55    and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
  56    The value of *default* (or ``0`` if *default* is not supplied) is returned when
  57    the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
  58    the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
  59    supply ``""`` for the corresponding argument.
  60
  61
  62 .. function:: ProgressBar([title[, maxval[, label[, id]]]])
  63
  64    Displays a modeless progress-bar dialog. This is the constructor for the
  65    :class:`ProgressBar` class described below. *title* is the text string displayed
  66    (default "Working..."), *maxval* is the value at which progress is complete
  67    (default ``0``, indicating that an indeterminate amount of work remains to be
  68    done), and *label* is the text that is displayed above the progress bar itself.
  69
  70
  71 .. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
  72
  73    Displays a dialog which aids the user in constructing a command-line argument
  74    list.  Returns the list in ``sys.argv`` format, suitable for passing as an
  75    argument to :func:`getopt.getopt`.  *addoldfile*, *addnewfile*, and *addfolder*
  76    are boolean arguments.  When nonzero, they enable the user to insert into the
  77    command line paths to an existing file, a (possibly) not-yet-existent file, and
  78    a folder, respectively.  (Note: Option arguments must appear in the command line
  79    before file and folder arguments in order to be recognized by
  80    :func:`getopt.getopt`.)  Arguments containing spaces can be specified by
  81    enclosing them within single or double quotes.  A :exc:`SystemExit` exception is
  82    raised if the user presses the "Cancel" button.
  83
  84    *optionlist* is a list that determines a popup menu from which the allowed
  85    options are selected.  Its items can take one of two forms: *optstr* or
  86    ``(optstr, descr)``.  When present, *descr* is a short descriptive string that
  87    is displayed in the dialog while this option is selected in the popup menu.  The
  88    correspondence between *optstr*\s and command-line arguments is:
  89
  90    +----------------------+------------------------------------------+
  91    | *optstr* format      | Command-line format                      |
  92    +======================+==========================================+
  93    | ``x``                | :option:`-x` (short option)              |
  94    +----------------------+------------------------------------------+
  95    | ``x:`` or ``x=``     | :option:`-x` (short option with value)   |
  96    +----------------------+------------------------------------------+
  97    | ``xyz``              | :option:`--xyz` (long option)            |
  98    +----------------------+------------------------------------------+
  99    | ``xyz:`` or ``xyz=`` | :option:`--xyz` (long option with value) |
 100    +----------------------+------------------------------------------+
 101
 102    *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
 103    where *descr* is as above.  The *cmdstr*s will appear in a popup menu.  When
 104    chosen, the text of *cmdstr* will be appended to the command line as is, except
 105    that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
 106
 107    .. versionadded:: 2.0
 108
 109
 110 .. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
 111
 112    Post a dialog asking the user for a file to open, and return the file selected
 113    or :const:`None` if the user cancelled. *message* is a text message to display,
 114    *typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
 115    pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
 116    *location* is the ``(x, y)`` position on the screen where the dialog is shown,
 117    *actionButtonLabel* is a string to show instead of "Open" in the OK button,
 118    *cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
 119    button, *wanted* is the type of value wanted as a return: :class:`str`,
 120    :class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
 121    acceptable.
 122
 123    .. index:: single: Navigation Services
 124
 125    For a description of the other arguments please see the Apple Navigation
 126    Services documentation and the :mod:`EasyDialogs` source code.
 127
 128
 129 .. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
 130
 131    Post a dialog asking the user for a file to save to, and return the file
 132    selected or :const:`None` if the user cancelled. *savedFileName* is the default
 133    for the file name to save to (the return value). See :func:`AskFileForOpen` for
 134    a description of the other arguments.
 135
 136
 137 .. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
 138
 139    Post a dialog asking the user to select a folder, and return the folder selected
 140    or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
 141    description of the arguments.
 142
 143
 144 .. seealso::
 145
 146    `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_
 147       Programmer's reference documentation for the Navigation Services, a part of the
 148       Carbon framework.
 149
 150
 151 .. _progressbar-objects:
 152
 153 ProgressBar Objects
 154 -------------------
 155
 156 :class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
 157 Both determinate (thermometer style) and indeterminate (barber-pole style)
 158 progress bars are supported.  The bar will be determinate if its maximum value
 159 is greater than zero; otherwise it will be indeterminate.
 160
 161 .. versionchanged:: 2.2
 162    Support for indeterminate-style progress bars was added.
 163
 164 The dialog is displayed immediately after creation. If the dialog's "Cancel"
 165 button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
 166 is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
 167 does not occur until the progress bar is next updated, typically via a call to
 168 :meth:`inc` or :meth:`set`).  Otherwise, the bar remains visible until the
 169 :class:`ProgressBar` object is discarded.
 170
 171 :class:`ProgressBar` objects possess the following attributes and methods:
 172
 173
 174 .. attribute:: ProgressBar.curval
 175
 176    The current value (of type integer or long integer) of the progress bar.  The
 177    normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
 178    This attribute should not be altered directly.
 179
 180
 181 .. attribute:: ProgressBar.maxval
 182
 183    The maximum value (of type integer or long integer) of the progress bar; the
 184    progress bar (thermometer style) is full when :attr:`curval` equals
 185    :attr:`maxval`.  If :attr:`maxval` is ``0``, the bar will be indeterminate
 186    (barber-pole).  This attribute should not be altered directly.
 187
 188
 189 .. method:: ProgressBar.title([newstr])
 190
 191    Sets the text in the title bar of the progress dialog to *newstr*.
 192
 193
 194 .. method:: ProgressBar.label([newstr])
 195
 196    Sets the text in the progress box of the progress dialog to *newstr*.
 197
 198
 199 .. method:: ProgressBar.set(value[, max])
 200
 201    Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
 202    *max* if the latter is provided.  *value* is first coerced between 0 and
 203    :attr:`maxval`.  The thermometer bar is updated to reflect the changes,
 204    including a change from indeterminate to determinate or vice versa.
 205
 206
 207 .. method:: ProgressBar.inc([n])
 208
 209    Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
 210    provided.  (Note that *n* may be negative, in which case the effect is a
 211    decrement.)  The progress bar is updated to reflect the change.  If the bar is
 212    indeterminate, this causes one "spin" of the barber pole.  The resulting
 213    :attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
 214    to fall outside this range.
 215