]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/wxPython.tex
Added documentation for wxMenuBar::Refresh()
[wxWidgets.git] / docs / latex / wx / wxPython.tex
1 \chapter{wxPython Notes}\label{wxPython}
2 \pagenumbering{arabic}%
3 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
4 \setfooter{\thepage}{}{}{}{}{\thepage}%
5
6 This addendum is written by Robin Dunn, author of the wxPython wrapper
7
8 %----------------------------------------------------------------------
9 \section{What is wxPython?}\label{wxpwhat}
10
11 wxPython is a blending of the wxWindows GUI classes and the
12 \urlref{Python}{http://www.python.org/} programming language.
13
14 \wxheading{Python}
15
16 So what is Python? Go to
17 \urlref{http://www.python.org}{http://www.python.org} to learn more,
18 but in a nutshell Python is an interpreted,
19 interactive, object-oriented programming language. It is often
20 compared to Tcl, Perl, Scheme or Java.
21
22 Python combines remarkable power with very clear syntax. It has
23 modules, classes, exceptions, very high level dynamic data types, and
24 dynamic typing. There are interfaces to many system calls and
25 libraries, and new built-in modules are easily written in C or
26 C++. Python is also usable as an extension language for applications
27 that need a programmable interface.
28
29 Python is copyrighted but freely usable and distributable, even for
30 commercial use.
31
32 \wxheading{wxPython}
33
34 wxPython is a Python package that can be imported at runtime that
35 includes a collection of Python modules and an extension module
36 (native code). It provides a series of Python classes that mirror (or
37 shadow) many of the wxWindows GUI classes. This extension module
38 attempts to mirror the class heiarchy of wxWindows as closely as
39 possble. This means that there is a wxFrame class in wxPython that
40 looks, smells, tastes and acts almost the same as the wxFrame class in
41 the C++ version.
42
43 wxPython is very versitile. It can be used to create standalone GUI
44 applications, or in situations where Python is embedded in a C++
45 application as an internal scripting or macro language.
46
47 Currently wxPython is available for Win32 platforms and the GTK
48 toolkit (wxGTK) on most Unix/X-windows platforms. The effort to
49 enable wxPython for wxMotif will begin shortly. See \helpref{Building Python}{wxpbuild} for
50 details about getting wxPython working for you.
51
52 %----------------------------------------------------------------------
53 \section{Why use wxPython?}\label{wxpwhy}
54
55 So why would you want to use wxPython over just C++ and wxWindows?
56 Personally I prefer using Python for everything. I only use C++ when
57 I absolutely have to eke more performance out of an algorithm, and even
58 then I ususally code it as an extension module and leave the majority
59 of the program in Python.
60
61 Another good thing to use wxPython for is quick prototyping of your
62 wxWindows apps. With C++ you have to continuously go though the
63 edit-compile-link-run cycle, which can be quite time consuming. With
64 Python it is only an edit-run cycle. You can easily build an
65 application in a few hours with Python that would normally take a few
66 days or longer with C++. Converting a wxPython app to a C++/wxWindows app
67 should be a straight forward task.
68
69 %----------------------------------------------------------------------
70 \section{Other Python GUIs}\label{wxpother}
71
72 There are other GUI solutions out there for Python.
73
74 \wxheading{Tkinter}
75
76 Tkinter is the defacto standard GUI for Python. It is available
77 on nearly every platform that Python and Tcl/TK are. Why Tcl/Tk?
78 Well because Tkinter is just a wrapper around Tcl's GUI toolkit, Tk.
79 This has its upsides and its downsides...
80
81 The upside is that Tk is a pretty versatile toolkit. It can be made
82 to do a lot of things in a lot of different environments. It is fairly
83 easy to create new widgets and use them interchangably in your
84 programs.
85
86 The downside is Tcl. When using Tkinter you actually have two
87 separate language interpreters running, the Python interpreter and the
88 Tcl interpreter for the GUI. Since the guts of Tcl is mostly about
89 string processing, it is fairly slow as well. (Not too bad on a fast
90 Pentium II, but you really notice the difference on slower machines.)
91
92 It wasn't until the lastest version of Tcl/Tk that native Look and
93 Feel was possible on non-Motif platforms. This is because Tk
94 usually implements its own widgets (controls) even when there are
95 native controls available.
96
97 Tkinter is a pretty low-level toolkit. You have to do a lot of work
98 (verbose program code) to do things that would be much simpler with a higher
99 level of abstraction.
100
101 \wxheading{PythonWin}
102
103 PythonWin is an add-on package for Python for the Win32 platform. It
104 includes wrappers for MFC as well as much of the Win32 API. Because
105 of its foundation, it is very familiar for programmers who have
106 experience with MFC and the Win32 API. It is obviously not compatible
107 with other platforms and toolkits. PythonWin is organized as separate
108 packages and modules so you can use the pieces you need without having
109 to use the GUI portions.
110
111 \wxheading{Others}
112
113 There are quite a few other GUI modules available for Python, some in
114 active use, some that havn't been updated for ages. Most are simple
115 wrappers around some C or C++ toolkit or another, and most are not
116 cross-platform compatible. See \urlref{this link}{http://www.python.org/download/Contributed.html\#Graphics}
117 for a listing of a few of them.
118
119 %----------------------------------------------------------------------
120 \section{Building wxPython}\label{wxpbuild}
121
122 I used SWIG (\urlref{http://www.swig.org}{http://www.swig.org}) to
123 to create the source code for the
124 extension module. This enabled me to only have to deal with a small
125 amount of code and only have to bother with the exceptional issues.
126 SWIG takes care of the rest and generates all the repetative code for
127 me. You don't need SWIG to build the extension module as all the
128 generated C++ code is included under the src directory.
129
130 I added a few minor features to SWIG to control some of the code
131 generation. If you want to play around with this you will need to get
132 a recent version of SWIG from their CVS or from a daily build. See
133 \urlref{http://www.swig.org/}{http://www.swig.org/} for details.
134
135 wxPython is organized as a Python package. This means that the
136 directory containing the results of the build process should be a
137 subdirectory of a directory on the \tt{PYTHONPATH}. (And preferably should
138 be named wxPython.) You can control where the build process will dump
139 wxPython by setting the \tt{TARGETDIR} variable for the build utility (see
140 below).
141
142 \begin{enumerate}\itemsep=0pt
143 \item Build wxWindows as described in its BuildCVS.txt file. For Unix
144 systems I run configure with these flags:
145
146 \begin{verbatim}
147 --with-gtk
148 --with-libjpeg
149 --without-odbc
150 --enable-unicode=no
151 --enable-threads=yes
152 --enable-socket=yes
153 --enable-static=no
154 --enable-shared=yes
155 --disable-std_iostreams
156 \end{verbatim}
157
158 You can use whatever flags you want, but I know these work.
159
160 For Win32 systems I use Visual C++ 6.0, but 5.0 should work also. The
161 build utility currently does not support any other Win32 compilers.
162 \item At this point you may want to make an alias or symlink, script,
163 batch file, whatever on the PATH that invokes \tt{\$(WXWIN)/utils/wxPython/distrib/build.py} to
164 help simplify matters somewhat. For example, on my Win32 system I have a file named
165 \tt{build}.bat in a directory on the PATH that contains:
166
167 \tt{python \%WXWIN/utils/wxPython/distrib/build.py \%1 \%2 \%3 \%4 \%5 \%6}
168
169 \item Change into the \tt{\$(WXWIN)/utils/wxPython/src} directory.
170 \item Type "\tt{build -b}" to build wxPython and "\tt{build -i}" to
171 install it, or "\tt{build -bi}" to do both steps at once.
172
173 The build.py script actually generates a Makefile based on what it
174 finds on your system and information found in the build.cfg file.
175 If you have troubles building or you want it built or installed in
176 a different way, take a look at the docstring in build.py. You are
177 able to to override many configuration options in a file named
178 build.local.
179 \item To build and install the add-on modules, change to the appropriate
180 directory under \tt{\$(WXWIN)/utils/wxPython/modules} and run the build
181 utility again.
182 \item Change to the \tt{\$(WXWIN)/utils/wxPython/demo} directory.
183 \item Try executing the demo program. For example:
184
185 \tt{python demo.py}
186
187 To run it without requiring a console on Win32, you can use the
188 \tt{pythonw.exe} version of Python either from the command line or from a
189 shortcut.
190 \end{enumerate}
191
192 %----------------------------------------------------------------------
193 \section{Using wxPython}\label{wxpusing}
194
195 \wxheading{First things first...}
196
197 I'm not going to try and teach the Python language here. You can do
198 that at the \urlref{Python Tutorial}{http://www.python.org/doc/tut/tut.html}.
199 I'm also going to assume that you know a bit about wxWindows already,
200 enough to notice the similarities in the classes used.
201
202 Take a look at the following wxPython program. You can find a similar
203 program in the \tt{wxPython/demo} directory, named \tt{DialogUnits.py}. If your
204 Python and wxPython are properly installed, you should be able to run
205 it by issuing this command:
206
207 \begin{indented}{1cm}
208 \bftt{python DialogUnits.py}
209 \end{indented}
210
211 \hrule
212
213 \begin{verbatim}
214 001: ## import all of the wxPython GUI package
215 002: from wxPython.wx import *
216 003:
217 004: ## Create a new frame class, derived from the wxPython Frame.
218 005: class MyFrame(wxFrame):
219 006:
220 007: def __init__(self, parent, id, title):
221 008: # First, call the base class' __init__ method to create the frame
222 009: wxFrame.__init__(self, parent, id, title,
223 010: wxPoint(100, 100), wxSize(160, 100))
224 011:
225 012: # Associate some events with methods of this class
226 013: EVT_SIZE(self, self.OnSize)
227 014: EVT_MOVE(self, self.OnMove)
228 015:
229 016: # Add a panel and some controls to display the size and position
230 017: panel = wxPanel(self, -1)
231 018: wxStaticText(panel, -1, "Size:",
232 019: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize)
233 020: wxStaticText(panel, -1, "Pos:",
234 021: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
235 022: self.sizeCtrl = wxTextCtrl(panel, -1, "",
236 023: wxDLG_PNT(panel, wxPoint(24, 4)),
237 024: wxDLG_SZE(panel, wxSize(36, -1)),
238 025: wxTE_READONLY)
239 026: self.posCtrl = wxTextCtrl(panel, -1, "",
240 027: wxDLG_PNT(panel, wxPoint(24, 14)),
241 028: wxDLG_SZE(panel, wxSize(36, -1)),
242 029: wxTE_READONLY)
243 030:
244 031:
245 032: # This method is called automatically when the CLOSE event is
246 033: # sent to this window
247 034: def OnCloseWindow(self, event):
248 035: # tell the window to kill itself
249 036: self.Destroy()
250 037:
251 038: # This method is called by the system when the window is resized,
252 039: # because of the association above.
253 040: def OnSize(self, event):
254 041: size = event.GetSize()
255 042: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
256 043:
257 044: # tell the event system to continue looking for an event handler,
258 045: # so the default handler will get called.
259 046: event.Skip()
260 047:
261 048: # This method is called by the system when the window is moved,
262 049: # because of the association above.
263 050: def OnMove(self, event):
264 051: pos = event.GetPosition()
265 052: self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
266 053:
267 054:
268 055: # Every wxWindows application must have a class derived from wxApp
269 056: class MyApp(wxApp):
270 057:
271 058: # wxWindows calls this method to initialize the application
272 059: def OnInit(self):
273 060:
274 061: # Create an instance of our customized Frame class
275 062: frame = MyFrame(NULL, -1, "This is a test")
276 063: frame.Show(true)
277 064:
278 065: # Tell wxWindows that this is our main window
279 066: self.SetTopWindow(frame)
280 067:
281 068: # Return a success flag
282 069: return true
283 070:
284 071:
285 072: app = MyApp(0) # Create an instance of the application class
286 073: app.MainLoop() # Tell it to start processing events
287 074:
288 \end{verbatim}
289 \hrule
290
291 \wxheading{Things to notice}
292
293 \begin{enumerate}\itemsep=0pt
294 \item At line 2 the wxPython classes, constants, and etc. are imported
295 into the current module's namespace. If you prefer to reduce
296 namespace pollution you can use "\tt{from wxPython import wx}" and
297 then access all the wxPython identifiers through the wx module, for
298 example, "\tt{wx.wxFrame}".
299 \item At line 13 the frame's sizing and moving events are connected to
300 methods of the class. These helper functions are intended to be like
301 the event table macros that wxWindows employs. But since static event
302 tables are impossible with wxPython, we use helpers that are named the
303 same to dynamically build the table. The only real difference is
304 that the first arguemnt to the event helpers is always the window that
305 the event table entry should be added to.
306 \item Notice the use of \tt{wxDLG\_PNT} and \tt{wxDLG\_SZE} in lines 19
307 - 29 to convert from dialog units to pixels. These helpers are unique
308 to wxPython since Python can't do method overloading like C++.
309 \item There is an \tt{OnCloseWindow} method at line 34 but no call to
310 EVT\_CLOSE to attach the event to the method. Does it really get
311 called? The answer is, yes it does. This is because many of the
312 \em{standard} events are attached to windows that have the associated
313 \em{standard} method names. I have tried to follow the lead of the
314 C++ classes in this area to determine what is \em{standard} but since
315 that changes from time to time I can make no guarentees, nor will it
316 be fully documented. When in doubt, use an EVT\_*** function.
317 \item At lines 17 to 21 notice that there are no saved references to
318 the panel or the static text items that are created. Those of you
319 who know Python might be wondering what happens when Python deletes
320 these objects when they go out of scope. Do they disappear from the GUI? They
321 don't. Remember that in wxPython the Python objects are just shadows of the
322 coresponding C++ objects. Once the C++ windows and controls are
323 attached to their parents, the parents manage them and delete them
324 when necessary. For this reason, most wxPython objects do not need to
325 have a \_\_del\_\_ method that explicitly causes the C++ object to be
326 deleted. If you ever have the need to forcibly delete a window, use
327 the Destroy() method as shown on line 36.
328 \item Just like wxWindows in C++, wxPython apps need to create a class
329 derived from \tt{wxApp} (line 56) that implements a method named
330 \tt{OnInit}, (line 59.) This method should create the application's
331 main window (line 62) and use \tt{wxApp.SetTopWindow()} (line 66) to
332 inform wxWindows about it.
333 \item And finally, at line 72 an instance of the application class is
334 created. At this point wxPython finishes initializing itself, and calls
335 the \tt{OnInit} method to get things started. (The zero parameter here is
336 a flag for functionality that isn't quite implemented yet. Just
337 ignore it for now.) The call to \tt{MainLoop} at line 73 starts the event
338 loop which continues until the application terminates or all the top
339 level windows are closed.
340 \end{enumerate}
341
342 %----------------------------------------------------------------------
343 \section{wxWindows classes implemented in wxPython}\label{wxpclasses}
344
345 The following classes are supported in wxPython. Most provide nearly
346 full implementations of the public interfaces specified in the C++
347 documentation, others are less so. They will all be brought as close
348 as possible to the C++ spec over time.
349
350 \begin{itemize}\itemsep=0pt
351 \item \helpref{wxAcceleratorEntry}{wxacceleratorentry}
352 \item \helpref{wxAcceleratorTable}{wxacceleratortable}
353 \item \helpref{wxActivateEvent}{wxactivateevent}
354 \item \helpref{wxBitmapButton}{wxbitmapbutton}
355 \item \helpref{wxBitmap}{wxbitmap}
356 \item wxBMPHandler
357 \item \helpref{wxBrush}{wxbrush}
358 \item \helpref{wxButton}{wxbutton}
359 \item \helpref{wxCalculateLayoutEvent}{wxcalculatelayoutevent}
360 \item \helpref{wxCheckBox}{wxcheckbox}
361 \item \helpref{wxCheckListBox}{wxchecklistbox}
362 \item \helpref{wxChoice}{wxchoice}
363 \item \helpref{wxClientDC}{wxclientdc}
364 \item \helpref{wxCloseEvent}{wxcloseevent}
365 \item \helpref{wxColourData}{wxcolourdata}
366 \item \helpref{wxColourDialog}{wxcolourdialog}
367 \item \helpref{wxColour}{wxcolour}
368 \item \helpref{wxComboBox}{wxcombobox}
369 \item \helpref{wxCommandEvent}{wxcommandevent}
370 \item \helpref{wxConfig}{wxconfigbase}
371 \item \helpref{wxControl}{wxcontrol}
372 \item \helpref{wxCursor}{wxcursor}
373 \item \helpref{wxDC}{wxdc}
374 \item \helpref{wxDialog}{wxdialog}
375 \item \helpref{wxDirDialog}{wxdirdialog}
376 \item \helpref{wxDropFilesEvent}{wxdropfilesevent}
377 \item \helpref{wxEraseEvent}{wxeraseevent}
378 \item \helpref{wxEvent}{wxevent}
379 \item \helpref{wxEvtHandler}{wxevthandler}
380 \item \helpref{wxFileDialog}{wxfiledialog}
381 \item \helpref{wxFocusEvent}{wxfocusevent}
382 \item \helpref{wxFontData}{wxfontdata}
383 \item \helpref{wxFontDialog}{wxfontdialog}
384 \item \helpref{wxFont}{wxfont}
385 \item \helpref{wxFrame}{wxframe}
386 \item \helpref{wxGauge}{wxgauge}
387 \item wxGIFHandler
388 \item wxGLCanvas
389 \item wxGridCell
390 \item wxGridEvent
391 \item \helpref{wxGrid}{wxgrid}
392 \item wxIconizeEvent
393 \item \helpref{wxIcon}{wxicon}
394 \item \helpref{wxIdleEvent}{wxidleevent}
395 \item \helpref{wxImage}{wximage}
396 \item \helpref{wxImageHandler}{wximagehandler}
397 \item \helpref{wxImageList}{wximagelist}
398 \item \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}
399 \item \helpref{wxInitDialogEvent}{wxinitdialogevent}
400 \item \helpref{wxJoystickEvent}{wxjoystickevent}
401 \item wxJPEGHandler
402 \item \helpref{wxKeyEvent}{wxkeyevent}
403 \item \helpref{wxLayoutAlgorithm}{wxlayoutalgorithm}
404 \item \helpref{wxLayoutConstraints}{wxlayoutconstraints}
405 \item \helpref{wxListBox}{wxlistbox}
406 \item \helpref{wxListCtrl}{wxlistctrl}
407 \item \helpref{wxListEvent}{wxlistevent}
408 \item \helpref{wxListItem}{wxlistctrlsetitem}
409 \item \helpref{wxMDIChildFrame}{wxmdichildframe}
410 \item \helpref{wxMDIClientWindow}{wxmdiclientwindow}
411 \item \helpref{wxMDIParentFrame}{wxmdiparentframe}
412 \item \helpref{wxMask}{wxmask}
413 \item wxMaximizeEvent
414 \item \helpref{wxMemoryDC}{wxmemorydc}
415 \item \helpref{wxMenuBar}{wxmenubar}
416 \item \helpref{wxMenuEvent}{wxmenuevent}
417 \item \helpref{wxMenuItem}{wxmenuitem}
418 \item \helpref{wxMenu}{wxmenu}
419 \item \helpref{wxMessageDialog}{wxmessagedialog}
420 \item \helpref{wxMetaFileDC}{wxmetafiledc}
421 \item \helpref{wxMiniFrame}{wxminiframe}
422 \item \helpref{wxMouseEvent}{wxmouseevent}
423 \item \helpref{wxMoveEvent}{wxmoveevent}
424 \item \helpref{wxNotebookEvent}{wxnotebookevent}
425 \item \helpref{wxNotebook}{wxnotebook}
426 \item \helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}
427 \item \helpref{wxPageSetupDialog}{wxpagesetupdialog}
428 \item \helpref{wxPaintDC}{wxpaintdc}
429 \item \helpref{wxPaintEvent}{wxpaintevent}
430 \item \helpref{wxPalette}{wxpalette}
431 \item \helpref{wxPanel}{wxpanel}
432 \item \helpref{wxPen}{wxpen}
433 \item wxPNGHandler
434 \item \helpref{wxPoint}{wxpoint}
435 \item \helpref{wxPostScriptDC}{wxpostscriptdc}
436 \item \helpref{wxPreviewFrame}{wxpreviewframe}
437 \item \helpref{wxPrintData}{wxprintdata}
438 \item \helpref{wxPrintDialogData}{wxprintdialogdata}
439 \item \helpref{wxPrintDialog}{wxprintdialog}
440 \item \helpref{wxPrinter}{wxprinter}
441 \item \helpref{wxPrintPreview}{wxprintpreview}
442 \item \helpref{wxPrinterDC}{wxprinterdc}
443 \item \helpref{wxPrintout}{wxprintout}
444 \item \helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}
445 \item \helpref{wxRadioBox}{wxradiobox}
446 \item \helpref{wxRadioButton}{wxradiobutton}
447 \item \helpref{wxRealPoint}{wxrealpoint}
448 \item \helpref{wxRect}{wxrect}
449 \item \helpref{wxRegionIterator}{wxregioniterator}
450 \item \helpref{wxRegion}{wxregion}
451 \item \helpref{wxSashEvent}{wxsashevent}
452 \item \helpref{wxSashLayoutWindow}{wxsashlayoutwindow}
453 \item \helpref{wxSashWindow}{wxsashwindow}
454 \item \helpref{wxScreenDC}{wxscreendc}
455 \item \helpref{wxScrollBar}{wxscrollbar}
456 \item \helpref{wxScrollEvent}{wxscrollevent}
457 \item \helpref{wxScrolledWindow}{wxscrolledwindow}
458 \item wxShowEvent
459 \item \helpref{wxSingleChoiceDialog}{wxsinglechoicedialog}
460 \item \helpref{wxSizeEvent}{wxsizeevent}
461 \item \helpref{wxSize}{wxsize}
462 \item \helpref{wxSlider}{wxslider}
463 \item \helpref{wxSpinButton}{wxspinbutton}
464 \item wxSpinEvent
465 \item \helpref{wxSplitterWindow}{wxsplitterwindow}
466 \item \helpref{wxStaticBitmap}{wxstaticbitmap}
467 \item \helpref{wxStaticBox}{wxstaticbox}
468 \item wxStaticLine
469 \item \helpref{wxStaticText}{wxstatictext}
470 \item \helpref{wxStatusBar}{wxstatusbar}
471 \item \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
472 \item \helpref{wxTaskBarIcon}{wxtaskbaricon}
473 \item \helpref{wxTextCtrl}{wxtextctrl}
474 \item \helpref{wxTextEntryDialog}{wxtextentrydialog}
475 \item \helpref{wxTimer}{wxtimer}
476 \item wxToolBarTool
477 \item \helpref{wxToolBar}{wxtoolbar}
478 \item wxToolTip
479 \item \helpref{wxTreeCtrl}{wxtreectrl}
480 \item \helpref{wxTreeEvent}{wxtreeevent}
481 \item \helpref{wxTreeItemData}{wxtreeitemdata}
482 \item wxTreeItemId
483 \item \helpref{wxUpdateUIEvent}{wxupdateuievent}
484 \item \helpref{wxWindowDC}{wxwindowdc}
485 \item \helpref{wxWindow}{wxwindow}
486 \end{itemize}
487
488 %----------------------------------------------------------------------
489 \section{Where to go for help}\label{wxphelp}
490
491 Since wxPython is a blending of multiple technologies, help comes from
492 multiple sources. See
493 \urlref{http://alldunn.com/wxPython}{http://alldunn.com/wxPython} for details on
494 various sources of help, but probably the best source is the
495 wxPython-users mail list. You can view the archive or subscribe by
496 going to
497
498 \urlref{http://starship.python.net/mailman/listinfo/wxpython-users}{http://starship.python.net/mailman/listinfo/wxpython-users}
499
500 Or you can send mail directly to the list using this address:
501
502 wxpython-users@starship.python.net
503