1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
<meta name="author" content="Dan Shafer" />
<link rel="stylesheet" href="PythonCard.css" type="text/css" />
<title>PythonCard Walk-through No. 1</title>
</head>
<body>
<div id="banner">
<h1>PythonCard Documentation</h1>
</div>
<?php include "sidebar.php" ?>
<div id="content">
<h1>Getting Started in PythonCard</h1>
<p>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.</p>
<h2>Before You Read This Document</h2>
<p>It will be helpful if, before you attempt to follow along with this
document, you are sure you've done the following:</p>
<ol>
<li>Downloaded and <a href="installation.html">installed the latest
version of PythonCard </a> for your system </li>
<li>Confirmed that your installation works by successfully launching and
running the application called minimal in the PythonCard samples directory</li>
</ol>
<p>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.</p>
<h2>Some Basic Preparation</h2>
<p>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.</p>
<p>You will also have to have access to a <a href="http://www.python.org/editors/">Python-aware editor</a>.
The good news is that PythonCard comes with a robust editor called <a href="tools/codeEditor.html">codeEditor</a>.
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:</p>
<ol>
<li>Open the Explorer and choose "Folder Options...quot; under the
"Tools" menu</li>
<li>Click on the "File Types" tab</li>
<li>Scroll down in the "Registered file types" list and select
extension "PY Python File"</li>
<li>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.</li>
<li>Click on the "New..." button. You should be looking at a
"New Action" dialog</li>
<li>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</li>
<li>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:</li>
</ol>
<p class="code">C:\Python23\python.exe C:\Python23\Lib\site-packages\PythonCard\tools\codeEditor\codeEditor.py "%1"</p>
<p>(Note that the text above is entered on one line; it may appear as two
lines in your browser because of wrapping of text.)</p>
<p>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</p>
<ol start="8">
<li>Click "OK." You should now have an "Edit with
PythonCard" item in your "Edit File Type" dialog</li>
<li>Click "OK"</li>
<li>Click "Close" in the "Folder Options" dialog</li>
<li>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.)</li>
<li>Repeat the process for .pyw files, using the same name and path.</li>
</ol>
<p>As you learn Python, you'll want a good tutorial. We've gathered together
<a href="learning_python.html">list of some of the best resources</a>
on the Net and in your favorite real or digital bookstore.</p>
<p>If you're not quite sure what PythonCard is or what kinds of problems it's
designed to solve, read <a href="http://pythoncard.sourceforge.net/">
this document</a>.</p>
<h2>A User's Eye View of PythonCard</h2>
<p>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.</p>
<p>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.)</p>
<h3>Exploring Some Sample Applications</h3>
<p>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.)</p>
<p>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).</p>
<p>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.)</p>
<p class="imageCaption"><img alt="Screen shot of PythonCard Samples Launcher" src="images/wt1fig1.png" /><br />
Figure 1. Screen Shot of PythonCard's Samples Launcher</p>
<p>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.</p>
<p>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.</p>
<p class="imageCaption"><img alt="Screen shot of minimal PythonCard application open window" src="images/wt1fig2.png" /><br />
Figure 2. Screen shot of minimal PythonCard application window</p>
<p>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.</p>
<p class="imageCaption"><img alt="Screen shot of Dialogs launcher application in PythonCard" src="images/wt1fig3.png" /><br />
Figure 3. Screen Shot of Dialogs Launcher Application in PythonCard</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h3>Changing a PythonCard Application</h3>
<p>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.</p>
<p>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:</p>
<pre>
def on_menuFileAbout_select(self, event):
pass
</pre>
<p>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).</p>
<p>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.</p>
<p>First, select the word "pass". Type in its place the following
line:</p>
<pre>
result = dialog.alertDialog(self, 'It works!', 'Showing Off')
</pre>
<p>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!"</p>
<p>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:</p>
<pre>
from PythonCard import model
</pre>
<p>Change that so it says:</p>
<pre>
from PythonCard import dialog, model
</pre>
<p>Save the code.</p>
<p><strong>IT IS IMPORTANT</strong>, 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.</p>
<p>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.</p>
<p>Close the application by selecting its window's close box.</p>
<h3>Making A Slightly More Interesting Change</h3>
<p>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:</p>
<pre>
result = dialog.alertDialog(self, self.components.field1.text, 'Showing Off')
</pre>
<p>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.</p>
<p>Save the code. Then double-click the "starter1" application to
try out the change.</p>
<p>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.</p>
<h2>What We've Learned</h2>
<p>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.</p>
<h2>What's Next?</h2>
<p>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.</p>
<p>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 <a href="http://lists.sourceforge.net/lists/listinfo/pythoncard-users">subscribe to the user mailing list</a>.</p>
<p><a href="walkthrough2.html">Continue on to Walk-Through 2</a></p>
<?php include "footer.php" ?>
<p>$Revision: 1.23 $ : $Author: kasplat $ : Last updated $Date: 2006/01/03 18:28:32 $</p>
</div> <!-- end of content -->
</body>
</html>
|
