<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"mac.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"mac.html" title='Macintosh Library Modules'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-FrameWork.html" />
<link rel=
"prev" href=
"module-findertools.html" />
<link rel=
"parent" href=
"macpython-modules.html" />
<link rel=
"next" href=
"progressbar-objects.html" />
<meta name='aesop' content='information'
/>
<title>2.7 EasyDialogs -- Basic Macintosh dialogs
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.6 findertools "
href=
"module-findertools.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"2. MacPython Modules"
href=
"macpython-modules.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"2.7.1 ProgressBar Objects"
href=
"progressbar-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Macintosh Library Modules
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-findertools.html">2.6 findertools
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"macpython-modules.html">2. MacPython Modules
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"progressbar-objects.html">2.7.1 ProgressBar Objects
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION004700000000000000000">
2.7 <tt class=
"module">EasyDialogs
</tt> --
Basic Macintosh dialogs
</A>
<A NAME=
"module-EasyDialogs"></A>
<p class=
"availability">Availability:
<span
class=
"platform">Macintosh
</span>.
</p>
The
<tt class=
"module">EasyDialogs
</tt> module contains some simple dialogs for the
Macintosh. All routines take an optional resource ID parameter
<var>id
</var>
with which one can override the
<tt class=
"constant">DLOG
</tt> resource used for the
dialog, provided that the dialog items correspond (both type and item
number) to those in the default
<tt class=
"constant">DLOG
</tt> resource. See source
The
<tt class=
"module">EasyDialogs
</tt> module defines the following functions:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
81' xml:id='l2h-
81'
class=
"function">Message
</tt></b>(
</nobr></td>
<td><var>str
</var><big>[
</big><var>, id
</var><big>[
</big><var>, ok
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Displays a modal dialog with the message text
<var>str
</var>, which should be
at most
255 characters long. The button text defaults to ``OK'', but is
set to the string argument
<var>ok
</var> if the latter is supplied. Control
is returned when the user clicks the ``OK'' button.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
82' xml:id='l2h-
82'
class=
"function">AskString
</tt></b>(
</nobr></td>
<td><var>prompt
</var><big>[
</big><var>, default
</var><big>[
</big><var>,
id
</var><big>[
</big><var>, ok
</var><big>[
</big><var>, cancel
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Asks the user to input a string value via a modal dialog.
<var>prompt
</var>
is the prompt message, and the optional
<var>default
</var> supplies the
initial value for the string (otherwise
<code>""</code> is used). The text of
the ``OK'' and ``Cancel'' buttons can be changed with the
<var>ok
</var> and
<var>cancel
</var> arguments. All strings can be at most
255 bytes long.
<tt class=
"function">AskString()
</tt> returns the string entered or
<tt class=
"constant">None
</tt>
in case the user cancelled.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
83' xml:id='l2h-
83'
class=
"function">AskPassword
</tt></b>(
</nobr></td>
<td><var>prompt
</var><big>[
</big><var>, default
</var><big>[
</big><var>,
id
</var><big>[
</big><var>, ok
</var><big>[
</big><var>, cancel
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Asks the user to input a string value via a modal dialog. Like
<tt class=
"function">AskString()
</tt>, but with the text shown as bullets. The
arguments have the same meaning as for
<tt class=
"function">AskString()
</tt>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
84' xml:id='l2h-
84'
class=
"function">AskYesNoCancel
</tt></b>(
</nobr></td>
<td><var>question
</var><big>[
</big><var>, default
</var><big>[
</big><var>,
yes
</var><big>[
</big><var>, no
</var><big>[
</big><var>, cancel
</var><big>[
</big><var>, id
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Presents a dialog with prompt
<var>question
</var> and three buttons labelled
``Yes'', ``No'', and ``Cancel''. Returns
<code>1</code> for ``Yes'',
<code>0</code>
for ``No'' and
<code>-
1</code> for ``Cancel''. The value of
<var>default
</var> (or
<code>0</code> if
<var>default
</var> is not supplied) is returned when the
<kbd>RETURN
</kbd> key is pressed. The text of the buttons can be changed with
the
<var>yes
</var>,
<var>no
</var>, and
<var>cancel
</var> arguments; to prevent a button
from appearing, supply
<code>""</code> for the corresponding argument.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
85' xml:id='l2h-
85'
class=
"function">ProgressBar
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>title
</var><big>[
</big><var>, maxval
</var><big>[
</big><var>,
label
</var><big>[
</big><var>, id
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Displays a modeless progress-bar dialog. This is the constructor for the
<tt class=
"class">ProgressBar
</tt> class described below.
<var>title
</var> is the text
string displayed (default ``Working...''),
<var>maxval
</var> is the value at
which progress is complete (default
<code>0</code>, indicating that an
indeterminate amount of work remains to be done), and
<var>label
</var> is
the text that is displayed above the progress bar itself.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
86' xml:id='l2h-
86'
class=
"function">GetArgv
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>optionlist
</var><big>[
</big><var>
commandlist
</var><big>[
</big><var>, addoldfile
</var><big>[
</big><var>, addnewfile
</var><big>[
</big><var>,
addfolder
</var><big>[
</big><var>, id
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Displays a dialog which aids the user in constructing a command-line
argument list. Returns the list in
<code>sys.argv
</code> format, suitable for
passing as an argument to
<tt class=
"function">getopt.getopt()
</tt>.
<var>addoldfile
</var>,
<var>addnewfile
</var>, and
<var>addfolder
</var> 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
<tt class=
"function">getopt.getopt()
</tt>.) Arguments containing spaces can be
specified by enclosing them within single or double quotes. A
<tt class=
"exception">SystemExit
</tt> exception is raised if the user presses the
<var>optionlist
</var> 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
</var> or
<code>(
<var>optstr
</var>,
<var>descr
</var>)
</code>. When present,
<var>descr
</var> 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
</var>s and command-line arguments is:
<div class=
"center"><table class=
"realtable">
<th class=
"left" ><var>optstr
</var> format
</th>
<th class=
"left" >Command-line format
</th>
<tr><td class=
"left" valign=
"baseline"><code>x
</code></td>
<td class=
"left" ><b class=
"programopt">-x
</b> (short option)
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>x:
</code> or
<code>x=
</code></td>
<td class=
"left" ><b class=
"programopt">-x
</b> (short option with value)
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>xyz
</code></td>
<td class=
"left" ><b class=
"programopt">--xyz
</b> (long option)
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>xyz:
</code> or
<code>xyz=
</code></td>
<td class=
"left" ><b class=
"programopt">--xyz
</b> (long option with value)
</td></tr></tbody>
<var>commandlist
</var> is a list of items of the form
<var>cmdstr
</var> or
<code>(
<var>cmdstr
</var>,
<var>descr
</var>)
</code>, where
<var>descr
</var> is as above. The
<var>cmdstr
</var>s will appear in a popup menu. When chosen, the text of
<var>cmdstr
</var> will be appended to the command line as is, except that a
trailing
"<tt class="character
">:</tt>" or
"<tt class="character
">=</tt>" (if present) will be trimmed
<span class=
"versionnote">New in version
2.0.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
87' xml:id='l2h-
87'
class=
"function">AskFileForOpen
</tt></b>(
</nobr></td>
</var><big>[
</big><var>message
</var><big>]
</big><var>
</var><big>[
</big><var>, typeList
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultLocation
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultOptionFlags
</var><big>]
</big><var>
</var><big>[
</big><var>, location
</var><big>]
</big><var>
</var><big>[
</big><var>, clientName
</var><big>]
</big><var>
</var><big>[
</big><var>, windowTitle
</var><big>]
</big><var>
</var><big>[
</big><var>, actionButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, cancelButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, preferenceKey
</var><big>]
</big><var>
</var><big>[
</big><var>, popupExtension
</var><big>]
</big><var>
</var><big>[
</big><var>, eventProc
</var><big>]
</big><var>
</var><big>[
</big><var>, previewProc
</var><big>]
</big><var>
</var><big>[
</big><var>, filterProc
</var><big>]
</big><var>
</var><big>[
</big><var>, wanted
</var><big>]
</big><var>
</var>)
</td></tr></table></dt>
Post a dialog asking the user for a file to open, and return the file
selected or
<tt class=
"constant">None
</tt> if the user cancelled.
<var>message
</var> is a text message to display,
<var>typeList
</var> is a list of
4-char filetypes allowable,
<var>defaultLocation
</var> is the pathname,
<tt class=
"class">FSSpec
</tt> or
<tt class=
"class">FSRef
</tt>
of the folder to show initially,
<var>location
</var> is the
<code>(x, y)
</code> position on the screen where the
<var>actionButtonLabel
</var> is a string to show instead of ``Open'' in the
<var>cancelButtonLabel
</var> is a string to show instead of ``Cancel'' in the
<var>wanted
</var> is the type of value wanted as a return:
<tt class=
"class">str
</tt>,
<tt class=
"class">unicode
</tt>,
<tt class=
"class">FSSpec
</tt>,
<tt class=
"class">FSRef
</tt> and subtypes thereof are
<a id='l2h-
90' xml:id='l2h-
90'
></a>
For a description of the other arguments please see the Apple Navigation
Services documentation and the
<tt class=
"module">EasyDialogs
</tt> source code.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
88' xml:id='l2h-
88'
class=
"function">AskFileForSave
</tt></b>(
</nobr></td>
</var><big>[
</big><var>message
</var><big>]
</big><var>
</var><big>[
</big><var>, savedFileName
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultLocation
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultOptionFlags
</var><big>]
</big><var>
</var><big>[
</big><var>, location
</var><big>]
</big><var>
</var><big>[
</big><var>, clientName
</var><big>]
</big><var>
</var><big>[
</big><var>, windowTitle
</var><big>]
</big><var>
</var><big>[
</big><var>, actionButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, cancelButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, preferenceKey
</var><big>]
</big><var>
</var><big>[
</big><var>, popupExtension
</var><big>]
</big><var>
</var><big>[
</big><var>, fileType
</var><big>]
</big><var>
</var><big>[
</big><var>, fileCreator
</var><big>]
</big><var>
</var><big>[
</big><var>, eventProc
</var><big>]
</big><var>
</var><big>[
</big><var>, wanted
</var><big>]
</big><var>
</var>)
</td></tr></table></dt>
Post a dialog asking the user for a file to save to, and return the
file selected or
<tt class=
"constant">None
</tt> if the user cancelled.
<var>savedFileName
</var> is the default for the file name to save to (the
return value). See
<tt class=
"function">AskFileForOpen()
</tt> for a description of
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
89' xml:id='l2h-
89'
class=
"function">AskFolder
</tt></b>(
</nobr></td>
</var><big>[
</big><var>message
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultLocation
</var><big>]
</big><var>
</var><big>[
</big><var>, defaultOptionFlags
</var><big>]
</big><var>
</var><big>[
</big><var>, location
</var><big>]
</big><var>
</var><big>[
</big><var>, clientName
</var><big>]
</big><var>
</var><big>[
</big><var>, windowTitle
</var><big>]
</big><var>
</var><big>[
</big><var>, actionButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, cancelButtonLabel
</var><big>]
</big><var>
</var><big>[
</big><var>, preferenceKey
</var><big>]
</big><var>
</var><big>[
</big><var>, popupExtension
</var><big>]
</big><var>
</var><big>[
</big><var>, eventProc
</var><big>]
</big><var>
</var><big>[
</big><var>, filterProc
</var><big>]
</big><var>
</var><big>[
</big><var>, wanted
</var><big>]
</big><var>
</var>)
</td></tr></table></dt>
Post a dialog asking the user to select a folder, and return the
folder selected or
<tt class=
"constant">None
</tt> if the user cancelled. See
<tt class=
"function">AskFileForOpen()
</tt> for a description of the arguments.
<p class=
"heading">See Also:
</p>
<dl compact=
"compact" class=
"seetitle">
<dt><em class=
"citetitle"><a href=
"http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/"
>Navigation Services Reference
</a></em></dt>
<dd>Programmer's reference documentation
for the Navigation Services, a part of the Carbon framework.
</dd>
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"progressbar-objects.html">2.7.1 ProgressBar Objects
</a>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.6 findertools "
href=
"module-findertools.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"2. MacPython Modules"
href=
"macpython-modules.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"2.7.1 ProgressBar Objects"
href=
"progressbar-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Macintosh Library Modules
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-findertools.html">2.6 findertools
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"macpython-modules.html">2. MacPython Modules
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"progressbar-objects.html">2.7.1 ProgressBar Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.