4
<H1 ALIGN="RIGHT"><A NAME="basics">2 pyFLTK Basics</A></H1>
6
<P>This chapter teaches you the basics of writing Python scripts
9
<H2>Writing Your First pyFLTK Script</H2>
11
<P>All scripts must import fltk: <TT>from fltk import *</TT>.
12
Listing 1 shows a simple "Hello,
13
World!" program that uses pyFLTK to display the window.</P>
16
<P><I>Listing 1 - "hello.py"</I>
21
window = Fl_Window(300,180)
22
box = Fl_Box(20,40,260,100,"Hello, World!")
25
box.labelfont(FL_BOLD+FL_ITALIC)
26
box.labeltype(FL_SHADOW_LABEL)
34
<P>After running python hello.py, the program first creates a
38
window = Fl_Window(300,180)
41
<P>and a box with the "Hello, World!" string in it:</P>
44
box = Fl_Box(20,40,260,100,"Hello, World!")
47
<P>Next, we set the type of box and the size, font, and style of the label:</P>
52
box.labelfont(FL_BOLD+FL_ITALIC)
53
box.labeltype(FL_SHADOW_LABEL)
56
<P>Finally, we show the window and enter the FLTK event loop:</P>
64
<P>The resulting program will display the window in Figure 2-1.
65
You can quit the program by closing the window or pressing the
66
<KBD>ESC</KBD>ape key.</P>
68
<P ALIGN="CENTER"><IMG src="Hello.jpg" alt="Hello, World! Window"><BR>
69
<I>Figure 2-1: The Hello, World! Window</I></P>
71
<H3>Creating the Widgets</H3>
73
<P>The widgets are created using a normal Python constructor. For
74
most widgets the arguments to the constructor are:</P>
77
Fl_Widget(x, y, width, height, label)
80
<P>The <TT>x</TT> and <TT>y</TT> parameters determine where the
81
widget or window is placed on the screen. In pyFLTK the top left
82
corner of the window or screen is the origin (i.e. x = 0, y =
83
0) and the units are in pixels.</P>
85
<P>The <TT>width</TT> and <TT>height</TT> parameters determine
86
the size of the widget or window in pixels. The maximum widget
87
size is typically governed by the underlying window system or
90
<P><tt>label</tt> is a character string to label
91
the widget with or <tt>None</tt>. If not specified the label
92
defaults to <tt>None</tt>. The label string must keep an external reference, because pyFLTK does not increase its reference count.</P>
94
<H3>Get/Set Methods</H3>
96
<P><tt>box.box(FL_UP_BOX)</tt> sets the type of box the
97
Fl_Box draws, changing it from the default of
98
<tt>FL_NO_BOX</tt>, which means that no box is drawn. In our
99
"Hello, World!" example we use <TT>FL_UP_BOX</TT>,
100
which means that a raised button border will be drawn around
101
the widget. You can learn more about boxtypes in
102
<A href="CH3_Common.html#boxtypes">Chapter 3</A>.</P>
104
<P>You could examine the boxtype in by doing
105
<tt>box.box()</tt>. pyFLTK uses method name overloading to make
106
short names for get/set methods. </P>
108
<H3>Redrawing After Changing Attributes</H3>
110
<P>Almost all of the set/get pairs are very fast, short
111
functions and thus very efficient. However, <i>the "set" methods
112
do not call <TT>redraw()</TT></i> - you have to call it
113
yourself. This greatly reduces code size and execution time. The
114
only common exceptions are <tt>value()</tt> which calls
115
<TT>redraw()</TT> and <tt>label()</tt> which calls
116
<TT>redraw_label()</TT> if necessary.</P>
120
<P>All widgets support labels. In the case of window widgets,
121
the label is used for the label in the title bar. Our example
122
program calls the <A href=fltk.html#Fl_Widget-labelfont>
123
<TT>labelfont</TT></A>,
124
<A href=fltk.html#Fl_Widget-labelsize><TT> labelsize</TT></A>,
125
and <A href=fltk.html#Fl_Widget-labeltype><TT>labeltype</TT></A>
128
<P>The <TT>labelfont</TT> method sets the typeface and style
129
that is used for the label, which for this example we are using
130
<TT>FL_BOLD</TT> and <TT>FL_ITALIC</TT>. You can also specify
131
typefaces directly. </P> <P>The <TT>labelsize</TT> method sets
132
the height of the font in pixels. </P> <P>The <TT>labeltype</TT>
133
method sets the type of label. FLTK supports normal, embossed,
134
and shadowed labels internally, and more types can be added as
137
<P>A complete list of all label options can be found in
138
<A href="CH3_Common.html#labels">Chapter 3</A>.</P>
140
<H3>Showing the Window</H3>
142
<P>The <TT>show()</TT> method shows the widget or window. For windows
143
you can also provide the command-line arguments to allow users to
144
customize the appearance, size, and position of your windows.</P>
146
<H3>The Main Event Loop</H3>
148
<P>All pyFLTK applications (and most GUI applications in general)
149
are based on a simple event processing model. User actions such
150
as mouse movement, button clicks, and keyboard activity generate
151
events that are sent to an application. The application may then
152
ignore the events or respond to the user, typically by redrawing
153
a button in the "down" position, adding the text to an input
154
field, and so forth.</P>
156
<P>pyFLTK also supports idle, timer, and file pseudo-events that
157
cause a function to be called when they occur. Idle functions
158
are called when no user input is present and no timers or files
159
need to be handled - in short, when the application is not doing
160
anything. Idle callbacks are often used to update a 3D display
161
or do other background processing.</P>
163
<P>Timer functions are called after a specific amount of time
164
has expired. They can be used to pop up a progress dialog after
165
a certain amount of time or do other things that need to happen
166
at more-or-less regular intervals. FLTK timers are not 100%
167
accurate, so they should not be used to measure time intervals,
170
<!-- P>File functions are called when data is ready to read or
171
write, or when an error condition occurs on a file. They are
172
most often used to monitor network connections (sockets) for
173
data-driven displays.</P -->
175
<P>PYFLTK applications must periodically check
176
(<TT>Fl.check()</TT>) or wait (<TT>Fl.wait()</TT>) for events
177
or use the <A href="fltk.html#Fl-run"><TT>Fl.run()</TT></A>
178
method to enter a standard event processing loop. Calling
179
<TT>Fl.run()</TT> is equivalent to the following code:</P>
186
<P><TT>Fl.run()</TT> does not return until all of the windows
187
under FLTK control are closed by the user or your program.</P>
191
<P>All public symbols in FLTK start with the characters 'F' and 'L':</P>
195
<LI>Functions are either <TT>Fl.foo()</TT> or
196
<TT>fl_foo()</TT>.</LI>
198
<LI>Class and type names are capitalized:
199
<TT>Fl_Foo</TT>.</LI>
201
<LI><A href="fltk.html#enumerations">Constants and
202
enumerations</A> are uppercase: <TT>FL_FOO</TT>.</LI>
210
<P>The proper way to import pyFLTK is:</P>
221
<H2><A NAME="interactive">Interactive usage</A></H2>
224
(Courtesy of Michiel de Hoon)<br>
225
Interactive behavior is particularly useful for rapid development of
226
GUIs, for beginning users of pyFltk, as well as for scientific
229
As an example, the following will work:<br>
232
>>> from fltk import *
233
>>> window = Fl_Window(300,300)
236
# Window pops up here
237
>>> window.label("My new title")
238
# Window label changes immediately
239
>>> window.color(FL_RED)
241
# Window color changes to red immediately
244
... and so on, all without calling Fl.run().
added
removed
fltk/docs/CH2_Basics.html
