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