- Added a file dialog example

- Added pointers to library documentation
author: Jack Jansen <jack.jansen@cwi.nl> 1996-07-18 16:07:05 (GMT)
committer: Jack Jansen <jack.jansen@cwi.nl> 1996-07-18 16:07:05 (GMT)
commit: 024a387f89cd4c08b67ffca0d8df311a34cc8a49 (patch)
tree: c1ec0a777e2c6b02596ddeb54cdb0e3fa7e02653
parent: a547dcaff09fa530871a0405b146c6bf958b48b4 (diff)
download: cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.zip
cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.tar.gz
cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.tar.bz2
4 files changed, 132 insertions, 2 deletions
diff --git a/Mac/Demo/example0.html b/Mac/Demo/example0.html
new file mode 100644
index 0000000..c0336a5
--- /dev/null
+++ b/Mac/Demo/example0.html
@@ -0,0 +1,75 @@
+<HTML><HEAD><TITLE>Using python to create Macintosh applications, part zero</TITLE></HEAD>
+<BODY>
+<H1>Using python to create Macintosh applications, part zero</H1>
+<HR>
+
+This document will show you how to create a simple mac-style
+application using Python. We will glance at how to use file dialogs and
+messages. <p>
+
+Our example program <a href="example0/checktext.py">checktext.py</a> asks
+the user for a text file and checks what style end-of-lines the file has.
+This may need a little explanation: ASCII text files are almost identical
+on different machines, with one exception: 
+<ul>
+<li> Unix systems terminate lines with the "linefeed" character, <code>0x0a</code>,
+<li> Macintoshes terminate lines with the "carriage return" character,
+<code>0x0d</code> and
+<li> MSDOS systems terminate lines with first a carriage return and then a linefeed.
+</ul>
+
+Let us have a look at the program. The first interesting statement in the main
+program is the call to <code>macfs.PromptGetFile</code>. This is one of the routines
+that allow you to ask the user to specify a file. You pass it one required
+argument, the prompt string. There are up to four optional MacOS <em>file type</em> arguments
+you can pass, as 4-byte strings. Specifying no file
+type will allow the user to select any file, specifying one or more types restricts
+the user to files of this type. File types are explained in most books on the Mac. <p>
+
+<code>PromptGetFile</code> returns two values: an <em>FSSpec</em> object and a
+success indicator. The FSSpec object is the "official" MacOS way of specifying a
+file, more on it later. The success indicator tells you whether the user clicked OK
+or Cancel. In the event of Cancel we simply exit back to the finder. <p>
+
+<code>PromptGetFile</code> has a number of friends that do similar things:
+<ul>
+<li> <code>StandardGetFile</code> is identical to <code>PromptGetFile</code> but
+without the prompt. It has up to four optional filetype arguments.
+<li> <code>StandardPutFile</code> asks the user for an output file. It will
+warn the user when she tries to overwrite an existing file. The routine has one
+mandatory argument: a prompt string. Pass the empty string if you do not want a prompt.
+<li> <code>GetDirectory</code> asks the user for a folder (or directory, in unix terms).
+It has one optional argument: a prompt string.
+</ul>
+All routines return an FSSpec and a success indicator. <p>
+
+There are many things you can do with FSSpec objects (see the 
+<a href="http://www.python.org/doc/lib/macfs.html">macfs</a> section in the
+<a href="http://www.python.org/doc/lib/Top.html">Python Library Reference</a>
+for details), but passing them to <code>open</code> is not
+one of them. For this, we first have to convert the FSSpec object to a pathname, with
+the <code>as_pathname</code> method. This returns a standard MacOS-style pathname with
+colon-separated components. This can then be passed to <code>open</code>. Note that
+we call open with mode parameter <code>'rb'</code>: we want to read the file in binary
+mode. Python, like C and C++, uses unix-style line endings internally and opening a
+file in text mode (<code>'r'</code>) would result in conversion of carriage-returns to
+linefeeds upon reading. This is something that Mac and DOS programmers are usually aware
+of but that never ceases to amaze unix buffs. <p>
+
+After we open the file we attempt to read all data into memory. If this fails we use
+<code>EasyDialogs.Message</code> to display a message in a standard dialog box and exit.
+The EasyDialogs module has a few more useful simple dialog routines, more on that in 
+<a href="example1.html">example 1</a>. <p>
+
+The rest of the code is pretty straightforward: we check that the file actually contains
+data, count the number of linefeeds and returns and display a message with our guess of the
+end-of-line convention used in the file. <p>
+
+The <a href="example0">example0</a> folder has three text files in Mac, Unix and DOS style
+for you to try the program on. After that, you can continue with <a href="example1.html">example 1</a>
+or go back to the <a href="index.html">index</a> to find another interesting topic. <p>
+
+<HR>
+<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
+<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 18-July-1996.
+</BODY></HTML>
diff --git a/Mac/Demo/example0/checktext.py b/Mac/Demo/example0/checktext.py
new file mode 100644
index 0000000..93a814d
--- /dev/null
+++ b/Mac/Demo/example0/checktext.py
@@ -0,0 +1,39 @@
+"""checktext - Check that a text file has macintosh-style newlines"""
+
+import macfs
+import sys
+import EasyDialogs
+import string
+
+def main():
+	fsspec, ok = macfs.PromptGetFile('File to check end-of-lines in:', 'TEXT')
+	if not ok:
+		sys.exit(0)
+	pathname = fsspec.as_pathname()
+	fp = open(pathname, 'rb')
+	try:
+		data = fp.read()
+	except MemoryError:
+		EasyDialogs.Message('Sorry, file is too big.')
+		sys.exit(0)
+	if len(data) == 0:
+		EasyDialogs.Message('File is empty.')
+		sys.exit(0)
+	number_cr = string.count(data, '\r')
+	number_lf = string.count(data, '\n')
+	if number_cr == number_lf == 0:
+		EasyDialogs.Message('File contains no lines.')
+	if number_cr == 0:
+		EasyDialogs.Message('File has unix-style line endings')
+	elif number_lf == 0:
+		EasyDialogs.Message('File has mac-style line endings')
+	elif number_cr == number_lf:
+		EasyDialogs.Message('File probably has MSDOS-style line endings')
+	else:
+		EasyDialogs.Message('File has no recognizable line endings (binary file?)')
+	sys.exit(0)
+	
+if __name__ == '__main__':
+	main()
+	
+	
diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html
index 8d691f4..57b28fd 100644
--- a/Mac/Demo/index.html
+++ b/Mac/Demo/index.html
@@ -19,6 +19,12 @@ HREF="http://www-acs.ucsd.edu/~jstrout/python/">
 http://www-acs.ucsd.edu/~jstrout/python/</A>.
 <P>
 
+The <a href="http://www.python.org/doc/lib/Top.html">Python Library Reference</a> contains a section on
+<a href="http://www.python.org/doc/lib/Macintosh-Specific-Services.html">Macintosh-specific modules</a>
+that you should also read. Documentation is also available in PostScript and other
+forms, see the <a href="http://www.python.org/doc/">documentation</a> section
+on the webserver. <p>
+
 Some of these documents were actually written while I was working on a "real"
 project: creating a single-button application that will allow my
 girlfriend to read her mail (which actually pass thry <EM>my</EM>
@@ -37,6 +43,12 @@ with earlier versions of Python, some will definitely not.
 
 <UL>
 <LI>
+<A HREF="example0.html">Using python to create Macintosh applications,
+part zero</A> whets your appetite by showing you how to ask the user
+for a filename, and how to display a message. It explains about end-of-line
+confusion while doing so.
+
+<LI>
 <A HREF="example1.html">Using python to create Macintosh applications,
 part one</A> explains how to create a simple modal-dialog application
 in Python. It also takes a glance at using the toolbox modules Res and
@@ -111,4 +123,5 @@ documentation. <p>
 
 <HR>
 <A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
-<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 18-May-1996.
+<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 18-July-1996.
+</BODY></HTML>
diff --git a/Mac/Demo/using.html b/Mac/Demo/using.html
index e7aa0f4..d3b5e8b 100644
--- a/Mac/Demo/using.html
+++ b/Mac/Demo/using.html
@@ -4,7 +4,6 @@
 </HEAD>
 <BODY>
 <H1>Using Python on the Macintosh</H1>
-<EM>(preliminary)</EM>
 <HR>
 
 This document is an introduction to using Python on the Apple
@@ -369,6 +368,10 @@ will appear to be correct in the editor but cause strange errors when
 imported. BBEdit has a popup menu which allows you to inspect (and
 set) the end-of-line convention used in a file. <p>
 
+<h2>Where to go from here</h2>
+
+The next section to check out is the <a href="index.html">annotated sample programs</a>.<p>
+
 <HR>
 <A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
 <A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 19-Apr-1996.
author	Jack Jansen <jack.jansen@cwi.nl>	1996-07-18 16:07:05 (GMT)
committer	Jack Jansen <jack.jansen@cwi.nl>	1996-07-18 16:07:05 (GMT)
commit	024a387f89cd4c08b67ffca0d8df311a34cc8a49 (patch)
tree	c1ec0a777e2c6b02596ddeb54cdb0e3fa7e02653
parent	a547dcaff09fa530871a0405b146c6bf958b48b4 (diff)
download	cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.zip cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.tar.gz cpython-024a387f89cd4c08b67ffca0d8df311a34cc8a49.tar.bz2