Getting Started in PythonCard
This document is designed to help people who are interested in learning
and using PythonCard but who are not professional programmers and who do
not have deep Python scripting skills to learn their way around the environment
and to understand how PythonCard applications get built.
Before You Read This Document
It will be helpful if, before you attempt to follow along with this
document, you are sure you've done the following:
- Downloaded and installed the latest
version of PythonCard
for your system
- Confirmed that your installation works by successfully launching and
running the application called minimal in the PythonCard samples directory
While it is not necessary for the purposes of this document that you
understand how to program in Python, you should know that all of the real
heavy lifting in PythonCard is done using Python programming. So if you
haven't yet learned Python, you can still follow the basics of this walk-through.
But you won't be able to do much in the way of PythonCard development
without at least a basic understanding of and comfort level with Python
programming.
Some Basic Preparation
This document assumes you are running PythonCard on a Windows machine.
If you're on a Linux system, you'll have to adjust some of the instructions
to match the directory structure and other differences on your machine.
At this writing, PythonCard does not yet run on a Macintosh because it relies
on the wxWindows cross-platform GUI library, which is in the process of
being ported to the Mac. When that port is complete and we've moved PythonCard
to the Mac, we'll undoubtedly add appropriate instructions to this and
other tutorial documents.
You will also have to have access to a
Python-aware editor
. The good news is that PythonCard comes with a robust editor called
codeEditor. When you install PythonCard, codeEditor appears in the tools
sub-directory. We recommend that you make it easy to open your Python source
files (all of them, not just the PythonCard source) with this codeEditor.
You can set up your Windows system so that it allows you to choose PythonCard's
codeEditor as one (or the only) editor with which Python source files can
be opened and edited by following these steps:
- Open the Explorer and choose "Folder Options..." under the "Tools"
menu
- Click on the "File Types" tab
- Scroll down in the "Registered file types" list and select extension
"PY Python File"
- Click on the "Advanced" button. You should be looking at an "Edit
File Type" dialog with a list of
- Actions such as Edit and Open. Open is probably in bold since it is
the default action usually associated with .py files.
- Click on the "New..." button. You should be looking at a "New Action"
dialog
- In the "Action:" field type in a label such as "Edit with PythonCard".
This is the label that will show up in the context menu when you right-click
on a .py file in the Explorer
- In the "Application used to perform action:" field you need to specify
the path to the Python executable as well as the location of the codeEditor.py
file. On a Python 2.2.1 installation using the default installer this will
look like:
C:\Python22\python.exe C:\Python22\PythonCardPrototype\tools\codeEditor\codeEditor.py
"%1"
(Note that the text above is entered on one line; it may appear as two
lines in your browser because of wrapping of text.)
Substitute your own paths for the ones above and put quotes (") around
the paths with spaces in them, if any. If you don't want a console when codeEditor.py
runs, then use pythonw.exe instead of python.exe
- Click "OK." You should now have an "Edit with PythonCard" item in
your "Edit File Type" dialog
- Click "OK"
- Click "Close" in the "Folder Options" dialog
- Open a directory in the explorer that contains a .py file, then right-click
on the file and choose "Edit with PythonCard" and the file should be opened
with codeEditor.py. (If it doesn't work, double-check the steps above.)
- Repeat the process for .pyw files, using the same name and path.
As you learn Python, you'll want a good tutorial. We've gathered together
a list of some of the best resources
on the Net and in your favorite real or digital bookstore.
If you're not quite sure what PythonCard is or what kinds of problems
it's designed to solve, read
this document
.
A User's Eye View of PythonCard
Now that you've taken all the necessary preparation steps, let's dig
into the PythonCard universe and see what's going on just under the hood.
PythonCard is a development environment. It needs an application as
a starting point, so you generally start by finding an application that
has a lot of what you're looking for and cloning it, renaming some files,
and then launching the copied application. We've done that for you for
this walk-through; the details of how to start your own application come
in a subsequent document in this series. (There is another way to begin
your PythonCard project development that involves choosing from a pre-defined
template. We won't cover that approach here but it is discussed in the next
walkthrough in this series.)
Exploring Some Sample Applications
We'll begin our walk-through of PythonCard by looking at the kinds
of things it is designed to do. (Understand, however, that these are pretty
skeletal applications designed as samples and starting points, not as commercial
applications. You can do far more robust things with PythonCard than might
be evident from these simple demonstrations.)
In the directory Python22\Lib\site-packages\PythonCardPrototype\samples
you'll find a file called samples.py. Double-click this application
icon (or launch it in whatever way you're accustomed to on your system).
In a few moments, you'll see a window open called "PythonCard Samples
Launcher." (See Figure 1) This PythonCard application lets you browse through
the sample applications included with PythonCard, examine them and run
them. It's a sort of nerve center for the sample applications. (On some
systems, you may also see an operating system console window when the application
launches. You can just minimize this window.)
Figure 1. Screen Shot of PythonCard's Samples Launcher
In the scrolling list of applications, select "minimal." Read the description.
Click on the buttons labeled "Show Source" and "Show Resource." None of
this means anything to you yet, but you need to know that you can always
examine the Python source code for the scripts that run your PythonCard
applications as well as the resource file that contains descriptions of the
elements that make up its interface. You should also know that every PythonCard
application has at least two Python source files. One of them ends in ".rsrc.py."
This is where PythonCard stores information about the layout of your application's
window, while the logic of the program is stored in the other Python file
which does not have the ".rsrc" extension before the ".py" extension. Note
that you cannot edit in the Samples Launcher.
OK, click the "Launch" button. In a few moments, you'll see a small
window like the one in Figure 2. Now you see why this sample is called
"minimal." It's about as small a PythonCard application as you can think
of! You can change the text in the editing field and you can drag the window
around. Eventually, you'll get tired of all this dazzling functionality
and want to close the application. You can either click the close box or
choose Exit from the File Menu.
Figure 2. Screen shot of minimal PythonCard application window
Back in the Samples Launcher, select the sample called "dialogs." Again,
you can examine source and the resource file if you're so inclined. When
you're ready, click the "Launch" button. A window like the one in Figure
3 will appear.
Figure 3. Screen Shot of Dialogs Launcher Application in PythonCard
All of the dialog boxes you can see by clicking on buttons to the left
of this window are built into PythonCard. Causing them to appear, and
determining what the user selected or did with them, is, as you'll learn
in a later walk-through, pretty straight-forward. Click on the "Alert"
button. A small dialog appears. Click the "OK" button. Notice that in the
Sample Dialogs window, you can see the name of the dialog (AlertDialog),
and whether the user accepted or canceled the dialog. You can also see
what information the program returned to PythonCard as a result of the user's
action. In this case, the user accepted the dialog (i.e., clicked "OK")
and the dialog returned "Ok." Unless you have some programming or scripting
background, that may not be meaningful, but trust us, it's useful data.
Now try the "Message" dialog. Run it twice, clicking "OK" once and
"Cancel" the other time. Notice the differences in the information displayed
in the Samples Launcher as a result.
One more and then we'll go have some fun with this stuff. Click on
the "File" dialog button. You'll see a standard file-open dialog for your
system. You can navigate around, choose from the list at the bottom of
the window the file type(s) you want to see listed, and select a file
(or cancel). Notice what appears in the Sample Dialogs window when you
do these various things.
Changing a PythonCard Application
OK, let's go see what's going on under the hood here. In your PythonCardPrototype\docs
directory, locate the folder called "GettingStarted". In that directory
is a file called starter1.py. Launch it in the usual way. It is a bare-bones
PythonCard application. In fact, it's a copy of the minimal application
you ran in the last section.
Open the file starter1.py in your Python-aware editor of choice. The
Python script is, as you'd expect, brief and to the point. Here's the
important part to focus on:
def on_menuFileExit_select(self, event):
pass
Even without understanding Python you can probably tell what this
code snippet does. (That's one of the beauties of Python. It is eminently
readable.) It's what we call an "event handler." It gets activated, or
triggered, by the user causing some event. In this case, the user
selects the File Menu's exit option and we do nothing (we "pass" the action).
We're going to change what this menu choice does. You'd never handle
an assignment the way we're going to show you here, but our purpose is
just to show you how easy it is to fiddle with PythonCard's Python scripts
to make things happen the way you want them to happen.
First, select the word "pass". Type in its place the following line:
result = dialog.alertDialog(self,
'It works!', 'Showing Off')
Again, this new line of Python code is readable even if you're
not a Python guru yet. Now when the user selects the Exit menu, rather
than doing nothing, we'll display an alert dialog titled "Showing Off" that
says "It works!"
One more change. We have to make sure our Python script knows how to
work with dialogs. Near the top of the file above the comments that explain
what's going on is a line that says:
from PythonCardPrototype import model
Change that so it says:
from PythonCardPrototype import dialog, model
Save the code.
IT IS IMPORTANT, if you choose to use a Python editor other than PythonCard's
codeEditor, that you not try to run the program from within those editors.
Doing so in programs like the IDLE editor that ships with the Python distribution
or PythonWin, for example, will have nasty consequences because these editors
use a different graphics library from what PythonCard uses.
Double-click the "starter1" application. When the window appears, select
the Exit option from the File menu. You'll see a small dialog appear as
described above.
Close the application by selecting its window's close box.
Making A Slightly More Interesting Change
Go back to codeEditor. If you didn't close it, starter1.py should still be
open for editing. Replace the string 'It works!' in the line we edited
earlier so that the line reads:
result = dialog.alertDialog(self,
self.components.field1.text, 'Showing Off')
This line is almost identical to the one we just had here, but this
one takes its text from the text in a component called "field1." That happens,
of course, to be the only field in our little application.
Save the code. Then double-click the "starter1" application to try out
the change.
Now when you change the text in the field and select File->Exit,
you'll see a dialog box that contains the text you put into the field.
What We've Learned
Not a bad start, right? We've learned how to launch a PythonCard application,
something about the kinds of dialog support PythonCard has built in, looked
at a couple of sample applications, and then edited some source code not
once but twice. In the process we also learned that PythonCard has components
(user interface elements) that have programs (or scripts) associated with
them. We've learned that there are events in PythonCard and that you can
write Python code that tells your application what to do when those events
are triggered.
What's Next?
In the next installment of this PythonCard walk-through, we'll dig
a little more deeply into development. We'll see how we can set up our
development environment to provide helpful supporting windows that tell
us what's going on in our application. We'll also see how to start and
build our own application, using the PythonCard built-in graphic editor,
the Resource Editor.
We'll be producing more of these walk-through documents on other aspects
of PythonCard's use. If you want to stay current with PythonCard and the
documentation, you should
subscribe to the user mailing list
.
Continue on to Walk-Through 2
$Revision: 1.13 $, documentation updated on
$Date: 2002/06/29 21:46:19 $