[Pythoncard-users] sample descriptions - first draft

[Kevin A. <al...@se...>]

Another day, another opportunity to embarrass my junior high school English
teacher.

Below is the first draft of samples.txt which I'm including in the docs
directory and will eventually turn into HTML and link to the sample
screenshots already displayed in samples.html and samples2.html.

Please provide corrections and suggestions or indicate which descriptions
make no sense. Apologies if the wrapping from the mailer makes this
difficult to read.

ka
---

Descriptions of the samples included with the PythonCardPrototype

The main purpose of the samples is to "stress" the PythonCard framework and
make sure that the framework is robust and full-featured, yet still simple
for  the beginner to use. "We learn by doing". As users (programmers) write
more  samples, we are able to identify which portions of the framework are
missing,  too simplistic or too complex or just plain broken. The
PythonCardPrototype  API changes as we identify these issues and fix the
framework and the samples  always represent the latest version of the API.
We don't have a complete API  yet, that is why we refer to the code as a
PythonCard prototype.

The ongoing list of things that needs to be added to PythonCard is
represented  by the Feature Requests here:
http://sourceforge.net/tracker/?atid=369015&group_id=19015&func=browse
You can also view this list using the SourceForgeTracker sample.

It is essential that we create lots of samples to identify framework issues
in  order to avoid creating a framework only suitable for simplistic "toy"
programs that are only one step beyond "hello world". Equally bad would be a
framework that is too general and requires the user to do a lot of work just
to write a basic program; simple programs should be simple to write; That is
the reason we aren't forcing a model-view-controller (MVC) paradigm on the
user, MVC is not easy to grasp or use correctly.

The samples also serve as a learning tool. Since there is little
documentation  for PythonCard right now, the best way to learn to use
PythonCard is to copy  and modify the samples. Note that due to the current
limitations of the  framework, some samples use wxPython method calls
directly. The wxPython calls  can usually be identified via the method name
which will start with a capital  letter (e.g. GetSize instead of getSize).

Please help the PythonCard project, by submitting your own samples and
asking  questions about PythonCard on the mailing list:
http://lists.sourceforge.net/lists/listinfo/pythoncard-users



adddresses
addresses is the first test of converting the layout and data of an existing
HyperCard stack to the PythonCard format. All the code used to do the
conversion, limitations of the conversion, and the steps of the conversion
are  documented. addresses can import Outlook contacts. Comma separated
values  (CSV) import will be added in the future. addresses also implements
transparent loading and saving of the contact data to a separate text file.
The textIndexer sample and addresses thus provide the start of a generic
transparent data storage model for PythonCard that will eventually be
available to all PythonCard apps that want to use it.


conversions
conversions provides conversion between english <-> morse code and celsius
<->  fahrenheit. The conversion framework is implemented so that it should
be  relatively easy to add other conversions. The base class handles
renaming the  widgets for a particular conversion.


dbBrowser
dbBrowser lets you browse mySQL databases. It dynamically creates and
destroys  widgets to display the fields from a database rather than just
using static  widget definitions in a resource (.rsrc.py) file. See the
readme.txt for more  information.


resourceEditor
resourceEditor is the start of a full-featured GUI resource editor for
PythonCard. The current version doesn't allow the user to save files, but
the  widget descriptions can be viewed with the View Attributes menu
command. See  the readme.txt for more information.


dialogs
dialogs shows off all the native dialogs currently supported by PythonCard.
If  you need to use a FileDialog, MessageDialog, etc. you should refer to
this  sample and copy the code for the dialog you want to use.


findfiles
findfiles is currently an incomplete sample, though it does work. It borrows
code from the sgrepmdi.py module included with PythonWin. It can read the
.grep files created by PythonWin. It can do a grep search just like
PythonWin  and display the results. Given the mechanism used for searching,
do not search  your entire hard drive or a network drive or you will wait a
LONG TIME for  results.


minimal
minimal is almost the smallest PythonCard program possible. Refer to
tutorial.txt for an example of copying and modifying minimal.py as your
first  PythonCard program.


proof
proof grew out of the original proof of concept for PythonCard. It shows off
all the widgets, but the widgets sample does a much better job of showing
all  the widgets and allowing the user to experiment with changing the
widget  attributes (properties). proof shows the use of a tiled background
image and  handles some events not used in any of the other samples. proof
will probably  be replaced in the future by a sample dedicated to testing
all possible  events.


resourceEditor
resourceEditor represents the beginnings of a GUI resource editor for
PythonCard. See the readme.txt for more information. resourceEditor makes
extensive use of 'command' handlers.


searchExplorer
searchExplorer was the first "useful" PythonCard app. It presents a list of
search sites and when the user clicks the "Search" button, it launches a web
browser to display the search results at the given site. It automatically
keeps tracks of the searches made and saves them to disk. searchExplorer has
an Edit menu that you might want to copy for your own code. The textIndexer
and resourceEditor samples uses a similar Edit menu that use 'command'
handlers rather than menu handlers which you might want to use instead.

I use searchExplorer, SourceForgeTracker, and worldclock every day, so I
keep  a shortcut to each app on my desktop; I renamed the copies with a .pyw
extension so a console doesn't appear when I double-click the shortcuts.


sounds
sounds is a simple test of the sound.py module that can play .wav files.


SourceForgeTracker
SourceForgeTracker downloads XML from SourceForge in order to display Bug
Reports and Feature Requests for a variety of Python SF projects. The XML
processing of the Unicode is a bit buggy, so not all items are displayed.
SourceForgeTracker provides an example of two alternative layouts, one that
has the standard "gray" dialog look and one that uses an alternative
backgroundColor and empty Image widgets behind the other widgets to give it
a  Yahoo-style look.


textIndexer
textIndexer is a conversion of Dan Winkler's original PythonCard demo. It
uses  ZODB as its storage mechanism, so you will need ZODB standalone or
Zope  installed in order to use it. See the readme.txt in the textIndexer
directory  for more information. textIndexer uses command attributes.


tictactoe
tictactoe shows off using a background image, the ImageButton widget and
background handlers.


turtle
turtle provides a fairly complete turtle library, numerous sample turtle
scripts (in the scripts directory) and an application to view them with. The
shell can be used to move the turtle(s) around interactively. See the docs
directory for more information.


widgets
widgets shows off all the PythonCard widgets. You can set many of the
attributes to see how it impacts each widget type.


worldclock
worldclock runs an external JavaScript (ECMAScript) program and then
downloads  an image off the www.time.gov server. Worldclock doesn't use a
menubar. It  also shows the use of a TextField with no border where the text
can't be  edited, but can still be copied to the clipboard; this is a good
alternative  to using a StaticText widget, if you don't need center or right
text  alignment. See the readme.txt for more information on running
worldclock,  setting the timezone, etc.