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