PageRenderTime 42ms CodeModel.GetById 27ms app.highlight 10ms RepoModel.GetById 2ms app.codeStats 0ms

/Doc/library/easydialogs.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 215 lines | 145 code | 70 blank | 0 comment | 0 complexity | 1c4447552ea903ba84fc3d3ee8dd902e MD5 | raw file
  1
  2:mod:`EasyDialogs` --- Basic Macintosh dialogs
  3==============================================
  4
  5.. module:: EasyDialogs
  6   :platform: Mac
  7   :synopsis: Basic Macintosh dialogs.
  8   :deprecated:
  9
 10
 11The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
 12The dialogs get launched in a separate application which appears in the dock and
 13must be clicked on for the dialogs be displayed.  All routines take an optional
 14resource ID parameter *id* with which one can override the :const:`DLOG`
 15resource used for the dialog, provided that the dialog items correspond (both
 16type and item number) to those in the default :const:`DLOG` resource. See source
 17code for details.
 18
 19.. note::
 20
 21   This module has been removed in Python 3.x.
 22
 23
 24The :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
153ProgressBar Objects
154-------------------
155
156:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
157Both determinate (thermometer style) and indeterminate (barber-pole style)
158progress bars are supported.  The bar will be determinate if its maximum value
159is greater than zero; otherwise it will be indeterminate.
160
161.. versionchanged:: 2.2
162   Support for indeterminate-style progress bars was added.
163
164The dialog is displayed immediately after creation. If the dialog's "Cancel"
165button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
166is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
167does 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