]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/python.h
Check wxDateTime components validity more rigorously.
[wxWidgets.git] / docs / doxygen / overviews / python.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
2cd3cc94 2// Name: python.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
15b6757b
FM
7/////////////////////////////////////////////////////////////////////////////
8
880efa2a 9/**
36c9828f 10
2cd3cc94 11@page overview_python wxPython Overview
36c9828f 12
3ed3a1c8
BP
13This topic was written by Robin Dunn, author of the
14<a href="http://www.python.org/">wxPython</a> wrapper.
2cd3cc94
BP
15
16@li @ref overview_python_what
17@li @ref overview_python_why
18@li @ref overview_python_othergui
19@li @ref overview_python_using
20@li @ref overview_python_classes
21@li @ref overview_python_help
22
23
24<hr>
25
26
27@section overview_python_what What is wxPython?
28
29wxPython is a blending of the wxWidgets GUI classes and the Python programming
30language.
31
32@subsection overview_python_what_py Python
33
34So what is Python? Go to http://www.python.org to learn more, but in a
35nutshell Python is an interpreted, interactive, object-oriented programming
36language. It is often compared to Tcl, Perl, Scheme or Java.
37
38Python combines remarkable power with very clear syntax. It has modules,
39classes, exceptions, very high level dynamic data types, and dynamic typing.
40There are interfaces to many system calls and libraries, and new built-in
41modules are easily written in C or C++. Python is also usable as an extension
42language for applications that need a programmable interface.
43
44Python is copyrighted but freely usable and distributable, even for commercial
45use.
46
47@subsection overview_python_what_wxpy wxPython
48
49wxPython is a Python package that can be imported at runtime that includes a
50collection of Python modules and an extension module (native code). It provides
51a series of Python classes that mirror (or shadow) many of the wxWidgets GUI
52classes. This extension module attempts to mirror the class hierarchy of
53wxWidgets as closely as possible. This means that there is a wxFrame class in
54wxPython that looks, smells, tastes and acts almost the same as the wxFrame
55class in the C++ version.
56
57wxPython is very versatile. It can be used to create standalone GUI
58applications, or in situations where Python is embedded in a C++ application as
59an internal scripting or macro language.
60
61Currently wxPython is available for Win32 platforms and the GTK toolkit (wxGTK)
62on most Unix/X-windows platforms. See the wxPython website http://wxPython.org/
63for details about getting wxPython working for you.
64
65
66@section overview_python_why Why Use wxPython?
67
68So why would you want to use wxPython over just C++ and wxWidgets? Personally I
69prefer using Python for everything. I only use C++ when I absolutely have to
70eke more performance out of an algorithm, and even then I usually code it as an
71extension module and leave the majority of the program in Python.
72
73Another good thing to use wxPython for is quick prototyping of your wxWidgets
74apps. With C++ you have to continuously go though the edit-compile-link-run
75cycle, which can be quite time consuming. With Python it is only an edit-run
76cycle. You can easily build an application in a few hours with Python that
77would normally take a few days or longer with C++. Converting a wxPython app to
78a C++/wxWidgets app should be a straight forward task.
79
80
81@section overview_python_othergui Other Python GUIs
82
83There are other GUI solutions out there for Python.
84
85@subsection overview_python_othergui_tkinter Tkinter
86
87Tkinter is the de facto standard GUI for Python. It is available on nearly
88every platform that Python and Tcl/TK are. Why Tcl/Tk? Well because Tkinter is
89just a wrapper around Tcl's GUI toolkit, Tk. This has it's upsides and it's
90downsides...
91
92The upside is that Tk is a pretty versatile toolkit. It can be made to do a lot
93of things in a lot of different environments. It is fairly easy to create new
94widgets and use them interchangeably in your programs.
95
96The downside is Tcl. When using Tkinter you actually have two separate language
97interpreters running, the Python interpreter and the Tcl interpreter for the
98GUI. Since the guts of Tcl is mostly about string processing, it is fairly slow
99as well. (Not too bad on a fast Pentium II, but you really notice the
100difference on slower machines.)
101
102It wasn't until the latest version of Tcl/Tk that native Look and Feel was
103possible on non-Motif platforms. This is because Tk usually implements its own
104widgets (controls) even when there are native controls available.
105
106Tkinter is a pretty low-level toolkit. You have to do a lot of work (verbose
107program code) to do things that would be much simpler with a higher level of
108abstraction.
109
110@subsection overview_python_othergui_pythonwin PythonWin
111
112PythonWin is an add-on package for Python for the Win32 platform. It includes
113wrappers for MFC as well as much of the Win32 API. Because of its foundation,
114it is very familiar for programmers who have experience with MFC and the Win32
115API. It is obviously not compatible with other platforms and toolkits.
116PythonWin is organized as separate packages and modules so you can use the
117pieces you need without having to use the GUI portions.
118
119@subsection overview_python_othergui_others Others
120
121There are quite a few other GUI modules available for Python, some in active
122use, some that haven't been updated for ages. Most are simple wrappers around
123some C or C++ toolkit or another, and most are not cross-platform compatible.
3ed3a1c8
BP
124See <a href="http://pypi.python.org/pypi?:action=browse&show=all&c=433">this link</a>
125for a listing of a few of them.
2cd3cc94
BP
126
127
128@section overview_python_using Using wxPython
129
130I'm not going to try and teach the Python language here. You can do that at the
3ed3a1c8
BP
131<a href="http://www.python.org/doc/tut/tut.html">Python Tutorial</a>. I'm also
132going to assume that you know a bit about wxWidgets already, enough to notice
133the similarities in the classes used.
2cd3cc94
BP
134
135Take a look at the following wxPython program. You can find a similar program
3ed3a1c8 136in the @c wxPython/demo directory, named @c DialogUnits.py. If your Python and
2cd3cc94
BP
137wxPython are properly installed, you should be able to run it by issuing this
138command:
139
140@code
141python DialogUnits.py
142@endcode
143
144@code
14501: ## import all of the wxPython GUI package
14602: from wxPython.wx import *
14703:
14804: ## Create a new frame class, derived from the wxPython Frame.
14905: class MyFrame(wxFrame):
15006:
15107: def __init__(self, parent, id, title):
15208: # First, call the base class' __init__ method to create the frame
15309: wxFrame.__init__(self, parent, id, title,
15410: wxPoint(100, 100), wxSize(160, 100))
15511:
15612: # Associate some events with methods of this class
15713: EVT_SIZE(self, self.OnSize)
15814: EVT_MOVE(self, self.OnMove)
15915:
16016: # Add a panel and some controls to display the size and position
16117: panel = wxPanel(self, -1)
16218: wxStaticText(panel, -1, "Size:",
16319: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize)
16420: wxStaticText(panel, -1, "Pos:",
16521: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
16622: self.sizeCtrl = wxTextCtrl(panel, -1, "",
16723: wxDLG_PNT(panel, wxPoint(24, 4)),
16824: wxDLG_SZE(panel, wxSize(36, -1)),
16925: wxTE_READONLY)
17026: self.posCtrl = wxTextCtrl(panel, -1, "",
17127: wxDLG_PNT(panel, wxPoint(24, 14)),
17228: wxDLG_SZE(panel, wxSize(36, -1)),
17329: wxTE_READONLY)
17430:
17531:
17632: # This method is called automatically when the CLOSE event is
17733: # sent to this window
17834: def OnCloseWindow(self, event):
17935: # tell the window to kill itself
18036: self.Destroy()
18137:
18238: # This method is called by the system when the window is resized,
18339: # because of the association above.
18440: def OnSize(self, event):
18541: size = event.GetSize()
18642: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
18743:
18844: # tell the event system to continue looking for an event handler,
18945: # so the default handler will get called.
19046: event.Skip()
19147:
19248: # This method is called by the system when the window is moved,
19349: # because of the association above.
19450: def OnMove(self, event):
19551: pos = event.GetPosition()
19652: self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
19753:
19854:
19955: # Every wxWidgets application must have a class derived from wxApp
20056: class MyApp(wxApp):
20157:
20258: # wxWidgets calls this method to initialize the application
20359: def OnInit(self):
20460:
20561: # Create an instance of our customized Frame class
20662: frame = MyFrame(NULL, -1, "This is a test")
20763: frame.Show(true)
20864:
20965: # Tell wxWidgets that this is our main window
21066: self.SetTopWindow(frame)
21167:
21268: # Return a success flag
21369: return true
21470:
21571:
21672: app = MyApp(0) # Create an instance of the application class
21773: app.MainLoop() # Tell it to start processing events
21874:
219@endcode
220
221@subsection overview_python_using_notice Things to Notice
222
223At line 2 the wxPython classes, constants, and etc. are imported into the
224current module's namespace. If you prefer to reduce namespace pollution you can
3ed3a1c8
BP
225use @c "from wxPython import wx" and then access all the wxPython identifiers
226through the wx module, for example, @c "wx.wxFrame".
2cd3cc94
BP
227
228At line 13 the frame's sizing and moving events are connected to methods of the
229class. These helper functions are intended to be like the event table macros
230that wxWidgets employs. But since static event tables are impossible with
231wxPython, we use helpers that are named the same to dynamically build the
232table. The only real difference is that the first argument to the event helpers
233is always the window that the event table entry should be added to.
234
235Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19-29 to convert from
236dialog units to pixels. These helpers are unique to wxPython since Python can't
237do method overloading like C++.
238
3ed3a1c8 239There is an @c OnCloseWindow method at line 34 but no call to @c EVT_CLOSE to
2cd3cc94
BP
240attach the event to the method. Does it really get called? The answer is, yes
241it does. This is because many of the standard events are attached to windows
242that have the associated standard method names. I have tried to follow the lead
243of the C++ classes in this area to determine what is standard but since that
244changes from time to time I can make no guarantees, nor will it be fully
3ed3a1c8 245documented. When in doubt, use an @c EVT_*** function.
2cd3cc94
BP
246
247At lines 17 to 21 notice that there are no saved references to the panel or the
248static text items that are created. Those of you who know Python might be
249wondering what happens when Python deletes these objects when they go out of
250scope. Do they disappear from the GUI? They don't. Remember that in wxPython
251the Python objects are just shadows of the corresponding C++ objects. Once the
252C++ windows and controls are attached to their parents, the parents manage them
253and delete them when necessary. For this reason, most wxPython objects do not
3ed3a1c8 254need to have a @c __del__ method that explicitly causes the C++ object to be
2cd3cc94
BP
255deleted. If you ever have the need to forcibly delete a window, use the
256Destroy() method as shown on line 36.
257
258Just like wxWidgets in C++, wxPython apps need to create a class derived from
259@c wxApp (line 56) that implements a method named @c OnInit, (line 59.) This
260method should create the application's main window (line 62) and use
261wxApp.SetTopWindow() (line 66) to inform wxWidgets about it.
262
263And finally, at line 72 an instance of the application class is created. At
264this point wxPython finishes initializing itself, and calls the @c OnInit
265method to get things started. (The zero parameter here is a flag for
266functionality that isn't quite implemented yet. Just ignore it for now.) The
267call to @c MainLoop at line 73 starts the event loop which continues until the
268application terminates or all the top level windows are closed.
269
270
271@section overview_python_classes Classes Implemented in wxPython
272
273The following classes are supported in wxPython. Most provide nearly full
274implementations of the public interfaces specified in the C++ documentation,
275others are less so. They will all be brought as close as possible to the C++
276spec over time.
277
278@li wxAcceleratorEntry
279@li wxAcceleratorTable
280@li wxActivateEvent
281@li wxBitmap
282@li wxBitmapButton
283@li wxBitmapDataObject
284@li wxBMPHandler
285@li wxBoxSizer
286@li wxBrush
287@li wxBusyInfo
288@li wxBusyCursor
289@li wxButton
290@li wxCalculateLayoutEvent
291@li wxCalendarCtrl
292@li wxCaret
293@li wxCheckBox
294@li wxCheckListBox
295@li wxChoice
296@li wxClientDC
297@li wxClipboard
298@li wxCloseEvent
299@li wxColourData
300@li wxColourDialog
301@li wxColour
302@li wxComboBox
303@li wxCommandEvent
3ed3a1c8 304@li wxConfigBase
2cd3cc94
BP
305@li wxControl
306@li wxCursor
307@li wxCustomDataObject
308@li wxDataFormat
309@li wxDataObject
310@li wxDataObjectComposite
311@li wxDataObjectSimple
312@li wxDateTime
313@li wxDateSpan
314@li wxDC
315@li wxDialog
316@li wxDirDialog
317@li wxDragImage
318@li wxDropFilesEvent
319@li wxDropSource
320@li wxDropTarget
321@li wxEraseEvent
322@li wxEvent
323@li wxEvtHandler
324@li wxFileConfig
325@li wxFileDataObject
326@li wxFileDialog
327@li wxFileDropTarget
328@li wxFileSystem
329@li wxFileSystemHandler
330@li wxFocusEvent
331@li wxFontData
332@li wxFontDialog
333@li wxFont
334@li wxFrame
335@li wxFSFile
336@li wxGauge
337@li wxGIFHandler
338@li wxGLCanvas
339@li wxHtmlCell
340@li wxHtmlContainerCell
341@li wxHtmlDCRenderer
342@li wxHtmlEasyPrinting
343@li wxHtmlParser
344@li wxHtmlTagHandler
345@li wxHtmlTag
346@li wxHtmlWinParser
347@li wxHtmlPrintout
348@li wxHtmlWinTagHandler
349@li wxHtmlWindow
350@li wxIconizeEvent
351@li wxIcon
352@li wxIdleEvent
353@li wxImage
354@li wxImageHandler
355@li wxImageList
356@li wxIndividualLayoutConstraint
357@li wxInitDialogEvent
358@li wxInputStream
3ed3a1c8 359@li @ref wxFileSystem "wxInternetFSHandler"
2cd3cc94
BP
360@li wxJoystickEvent
361@li wxJPEGHandler
362@li wxKeyEvent
363@li wxLayoutAlgorithm
364@li wxLayoutConstraints
365@li wxListBox
366@li wxListCtrl
367@li wxListEvent
368@li wxListItem
369@li wxMask
370@li wxMaximizeEvent
371@li wxMDIChildFrame
372@li wxMDIClientWindow
373@li wxMDIParentFrame
374@li wxMemoryDC
375@li wxMemoryFSHandler
376@li wxMenuBar
377@li wxMenuEvent
378@li wxMenuItem
379@li wxMenu
380@li wxMessageDialog
3ed3a1c8 381@li wxMetafileDC
2cd3cc94
BP
382@li wxMiniFrame
383@li wxMouseEvent
384@li wxMoveEvent
385@li wxNotebookEvent
386@li wxNotebook
387@li wxPageSetupDialogData
388@li wxPageSetupDialog
389@li wxPaintDC
390@li wxPaintEvent
391@li wxPalette
392@li wxPanel
393@li wxPen
394@li wxPNGHandler
395@li wxPoint
396@li wxPostScriptDC
397@li wxPreviewFrame
398@li wxPrintData
399@li wxPrintDialogData
400@li wxPrintDialog
401@li wxPrinter
402@li wxPrintPreview
403@li wxPrinterDC
404@li wxPrintout
405@li wxProcess
406@li wxQueryLayoutInfoEvent
407@li wxRadioBox
408@li wxRadioButton
409@li wxRealPoint
410@li wxRect
411@li wxRegionIterator
412@li wxRegion
413@li wxSashEvent
414@li wxSashLayoutWindow
415@li wxSashWindow
416@li wxScreenDC
417@li wxScrollBar
418@li wxScrollEvent
f09b5681 419@li ::wxScrolledWindow
2cd3cc94
BP
420@li wxScrollWinEvent
421@li wxShowEvent
422@li wxSingleChoiceDialog
423@li wxSizeEvent
424@li wxSize
425@li wxSizer
426@li wxSizerItem
427@li wxSlider
428@li wxSpinButton
429@li wxSpinEvent
430@li wxSplitterWindow
431@li wxStaticBitmap
432@li wxStaticBox
433@li wxStaticBoxSizer
434@li wxStaticLine
435@li wxStaticText
436@li wxStatusBar
437@li wxSysColourChangedEvent
438@li wxTaskBarIcon
439@li wxTextCtrl
440@li wxTextDataObject
441@li wxTextDropTarget
442@li wxTextEntryDialog
443@li wxTimer
444@li wxTimerEvent
445@li wxTimeSpan
446@li wxTipProvider
447@li wxToolBarTool
448@li wxToolBar
449@li wxToolTip
450@li wxTreeCtrl
451@li wxTreeEvent
452@li wxTreeItemData
453@li wxTreeItemId
454@li wxUpdateUIEvent
455@li wxValidator
456@li wxWindowDC
457@li wxWindow
3ed3a1c8 458@li @ref wxFileSystem "wxZipFSHandler"
2cd3cc94
BP
459
460
461@section overview_python_help Where to Go for Help
462
463Since wxPython is a blending of multiple technologies, help comes from multiple
464sources. See http://wxpython.org/ for details on various sources of help, but
465probably the best source is the wxPython-users mail list. You can view the
466archive or subscribe by going to http://wxpython.org/maillist.php
467
468Or you can send mail directly to the list using this address:
469wxpython-users@lists.wxwidgets.org
470
471*/
36c9828f 472