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