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 Macintosh or Linux system, you'll have to adjust some of the instructions to match the directory structure and other differences on your machine.
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...quot; 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.3.5 installation using the default installer this will look like:
C:\Python23\python.exe C:\Python23\Lib\site-packages\PythonCard\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 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 Python23\Lib\site-packages\PythonCard\samples you'll find a file called samples.pyw. 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 the text lines 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" line. 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 three times, clicking "Yes " once, "No" 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 PythonCard\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 with just a few changes.
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_menuFileAbout_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 "About" option and we do nothing (in Python, the "pass" statement does nothing; it's simply used as a placeholder where the syntax requires a statement but no action is needed).
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 About menu item, 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 PythonCard import model
Change that so it says:
from PythonCard 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.py" application. When the window appears, select the About 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.py" application to try out the change.
Now when you change the text in the field and select File->About, 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 built-in PythonCard layout 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.
$Revision: 1.24 $ : $Author: kasplat $ : Last updated $Date: 2007/07/28 20:40:04 $