--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// Name: python
+// Purpose: topic overview
+// Author: wxWidgets team
+// RCS-ID: $Id$
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/*!
+
+ @page python_overview wxPython overview
+
+ This topic was written by Robin Dunn, author of the wxPython wrapper.
+ @ref pwhat_overview
+ @ref pwhy_overview
+ @ref pother_overview
+ @ref pusing_overview
+ @ref pclasses_overview
+ @ref phelp_overview
+
+
+ @section wxpwhat What is wxPython?
+
+ wxPython is a blending of the wxWidgets GUI classes and the
+ #Python programming language.
+ @b Python
+ So what is Python? Go to
+ #http://www.python.org to learn more,
+ but in a nutshell Python is an interpreted,
+ interactive, object-oriented programming language. It is often
+ compared to Tcl, Perl, Scheme or Java.
+ Python combines remarkable power with very clear syntax. It has
+ modules, classes, exceptions, very high level dynamic data types, and
+ dynamic typing. There are interfaces to many system calls and
+ libraries, and new built-in modules are easily written in C or
+ C++. Python is also usable as an extension language for applications
+ that need a programmable interface.
+ Python is copyrighted but freely usable and distributable, even for
+ commercial use.
+ @b wxPython
+ wxPython is a Python package that can be imported at runtime that
+ includes a collection of Python modules and an extension module
+ (native code). It provides a series of Python classes that mirror (or
+ shadow) many of the wxWidgets GUI classes. This extension module
+ attempts to mirror the class hierarchy of wxWidgets as closely as
+ possible. This means that there is a wxFrame class in wxPython that
+ looks, smells, tastes and acts almost the same as the wxFrame class in
+ the C++ version.
+ wxPython is very versatile. It can be used to create standalone GUI
+ applications, or in situations where Python is embedded in a C++
+ application as an internal scripting or macro language.
+ Currently wxPython is available for Win32 platforms and the GTK
+ toolkit (wxGTK) on most Unix/X-windows platforms. See the wxPython
+ website #http://wxPython.org/ for
+ details about getting wxPython working for you.
+
+ @section wxpwhy Why use wxPython?
+
+ So why would you want to use wxPython over just C++ and wxWidgets?
+ Personally I prefer using Python for everything. I only use C++ when I
+ absolutely have to eke more performance out of an algorithm, and even
+ then I usually code it as an extension module and leave the majority
+ of the program in Python.
+ Another good thing to use wxPython for is quick prototyping of your
+ wxWidgets apps. With C++ you have to continuously go though the
+ edit-compile-link-run cycle, which can be quite time consuming. With
+ Python it is only an edit-run cycle. You can easily build an
+ application in a few hours with Python that would normally take a few
+ days or longer with C++. Converting a wxPython app to a C++/wxWidgets app
+ should be a straight forward task.
+
+ @section wxpother Other Python GUIs
+
+ There are other GUI solutions out there for Python.
+ @b Tkinter
+ Tkinter is the de facto standard GUI for Python. It is available
+ on nearly every platform that Python and Tcl/TK are. Why Tcl/Tk?
+ Well because Tkinter is just a wrapper around Tcl's GUI toolkit, Tk.
+ This has its upsides and its downsides...
+ The upside is that Tk is a pretty versatile toolkit. It can be made
+ to do a lot of things in a lot of different environments. It is fairly
+ easy to create new widgets and use them interchangeably in your
+ programs.
+ The downside is Tcl. When using Tkinter you actually have two
+ separate language interpreters running, the Python interpreter and the
+ Tcl interpreter for the GUI. Since the guts of Tcl is mostly about
+ string processing, it is fairly slow as well. (Not too bad on a fast
+ Pentium II, but you really notice the difference on slower machines.)
+ It wasn't until the latest version of Tcl/Tk that native Look and
+ Feel was possible on non-Motif platforms. This is because Tk
+ usually implements its own widgets (controls) even when there are
+ native controls available.
+ Tkinter is a pretty low-level toolkit. You have to do a lot of work
+ (verbose program code) to do things that would be much simpler with a higher
+ level of abstraction.
+ @b PythonWin
+ PythonWin is an add-on package for Python for the Win32 platform. It
+ includes wrappers for MFC as well as much of the Win32 API. Because
+ of its foundation, it is very familiar for programmers who have
+ experience with MFC and the Win32 API. It is obviously not compatible
+ with other platforms and toolkits. PythonWin is organized as separate
+ packages and modules so you can use the pieces you need without having
+ to use the GUI portions.
+ @b Others
+ There are quite a few other GUI modules available for Python, some in
+ active use, some that haven't been updated for ages. Most are simple
+ wrappers around some C or C++ toolkit or another, and most are not
+ cross-platform compatible. See @ref Graphics_overview
+ for a listing of a few of them.
+
+ @section wxpusing Using wxPython
+
+ @b First things first...
+ I'm not going to try and teach the Python language here. You can do
+ that at the http://www.python.org/doc/tut/tut.html.
+ I'm also going to assume that you know a bit about wxWidgets already,
+ enough to notice the similarities in the classes used.
+ Take a look at the following wxPython program. You can find a similar
+ program in the @c wxPython/demo directory, named @c DialogUnits.py. If your
+ Python and wxPython are properly installed, you should be able to run
+ it by issuing this command:
+
+
+ @b @c python DialogUnits.py
+
+
+
+
+
+ @code
+ 001: ## import all of the wxPython GUI package
+ 002: from wxPython.wx import *
+ 003:
+ 004: ## Create a new frame class, derived from the wxPython Frame.
+ 005: class MyFrame(wxFrame):
+ 006:
+ 007: def __init__(self, parent, id, title):
+ 008: # First, call the base class' __init__ method to create the frame
+ 009: wxFrame.__init__(self, parent, id, title,
+ 010: wxPoint(100, 100), wxSize(160, 100))
+ 011:
+ 012: # Associate some events with methods of this class
+ 013: EVT_SIZE(self, self.OnSize)
+ 014: EVT_MOVE(self, self.OnMove)
+ 015:
+ 016: # Add a panel and some controls to display the size and position
+ 017: panel = wxPanel(self, -1)
+ 018: wxStaticText(panel, -1, "Size:",
+ 019: wxDLG_PNT(panel, wxPoint(4, 4)), wxDefaultSize)
+ 020: wxStaticText(panel, -1, "Pos:",
+ 021: wxDLG_PNT(panel, wxPoint(4, 14)), wxDefaultSize)
+ 022: self.sizeCtrl = wxTextCtrl(panel, -1, "",
+ 023: wxDLG_PNT(panel, wxPoint(24, 4)),
+ 024: wxDLG_SZE(panel, wxSize(36, -1)),
+ 025: wxTE_READONLY)
+ 026: self.posCtrl = wxTextCtrl(panel, -1, "",
+ 027: wxDLG_PNT(panel, wxPoint(24, 14)),
+ 028: wxDLG_SZE(panel, wxSize(36, -1)),
+ 029: wxTE_READONLY)
+ 030:
+ 031:
+ 032: # This method is called automatically when the CLOSE event is
+ 033: # sent to this window
+ 034: def OnCloseWindow(self, event):
+ 035: # tell the window to kill itself
+ 036: self.Destroy()
+ 037:
+ 038: # This method is called by the system when the window is resized,
+ 039: # because of the association above.
+ 040: def OnSize(self, event):
+ 041: size = event.GetSize()
+ 042: self.sizeCtrl.SetValue("%s, %s" % (size.width, size.height))
+ 043:
+ 044: # tell the event system to continue looking for an event handler,
+ 045: # so the default handler will get called.
+ 046: event.Skip()
+ 047:
+ 048: # This method is called by the system when the window is moved,
+ 049: # because of the association above.
+ 050: def OnMove(self, event):
+ 051: pos = event.GetPosition()
+ 052: self.posCtrl.SetValue("%s, %s" % (pos.x, pos.y))
+ 053:
+ 054:
+ 055: # Every wxWidgets application must have a class derived from wxApp
+ 056: class MyApp(wxApp):
+ 057:
+ 058: # wxWidgets calls this method to initialize the application
+ 059: def OnInit(self):
+ 060:
+ 061: # Create an instance of our customized Frame class
+ 062: frame = MyFrame(@NULL, -1, "This is a test")
+ 063: frame.Show(@true)
+ 064:
+ 065: # Tell wxWidgets that this is our main window
+ 066: self.SetTopWindow(frame)
+ 067:
+ 068: # Return a success flag
+ 069: return @true
+ 070:
+ 071:
+ 072: app = MyApp(0) # Create an instance of the application class
+ 073: app.MainLoop() # Tell it to start processing events
+ 074:
+ @endcode
+
+
+
+ @b Things to notice
+
+
+ At line 2 the wxPython classes, constants, and etc. are imported
+ into the current module's namespace. If you prefer to reduce
+ namespace pollution you can use "@c from wxPython import wx" and
+ then access all the wxPython identifiers through the wx module, for
+ example, "@c wx.wxFrame".
+ At line 13 the frame's sizing and moving events are connected to
+ methods of the class. These helper functions are intended to be like
+ the event table macros that wxWidgets employs. But since static event
+ tables are impossible with wxPython, we use helpers that are named the
+ same to dynamically build the table. The only real difference is
+ that the first argument to the event helpers is always the window that
+ the event table entry should be added to.
+ Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19
+ - 29 to convert from dialog units to pixels. These helpers are unique
+ to wxPython since Python can't do method overloading like C++.
+ There is an @c OnCloseWindow method at line 34 but no call to
+ EVT_CLOSE to attach the event to the method. Does it really get
+ called? The answer is, yes it does. This is because many of the
+ standard events are attached to windows that have the associated
+ standard method names. I have tried to follow the lead of the
+ C++ classes in this area to determine what is standard but since
+ that changes from time to time I can make no guarantees, nor will it
+ be fully documented. When in doubt, use an EVT_*** function.
+ At lines 17 to 21 notice that there are no saved references to
+ the panel or the static text items that are created. Those of you
+ who know Python might be wondering what happens when Python deletes
+ these objects when they go out of scope. Do they disappear from the GUI? They
+ don't. Remember that in wxPython the Python objects are just shadows of the
+ corresponding C++ objects. Once the C++ windows and controls are
+ attached to their parents, the parents manage them and delete them
+ when necessary. For this reason, most wxPython objects do not need to
+ have a __del__ method that explicitly causes the C++ object to be
+ deleted. If you ever have the need to forcibly delete a window, use
+ the Destroy() method as shown on line 36.
+ Just like wxWidgets in C++, wxPython apps need to create a class
+ derived from @c wxApp (line 56) that implements a method named
+ @c OnInit, (line 59.) This method should create the application's
+ main window (line 62) and use @c wxApp.SetTopWindow() (line 66) to
+ inform wxWidgets about it.
+ And finally, at line 72 an instance of the application class is
+ created. At this point wxPython finishes initializing itself, and calls
+ the @c OnInit method to get things started. (The zero parameter here is
+ a flag for functionality that isn't quite implemented yet. Just
+ ignore it for now.) The call to @c MainLoop at line 73 starts the event
+ loop which continues until the application terminates or all the top
+ level windows are closed.
+
+
+
+ @section wxpclasses wxWidgets classes implemented in wxPython
+
+ The following classes are supported in wxPython. Most provide nearly
+ full implementations of the public interfaces specified in the C++
+ documentation, others are less so. They will all be brought as close
+ as possible to the C++ spec over time.
+
+
+ #wxAcceleratorEntry
+ #wxAcceleratorTable
+ #wxActivateEvent
+ #wxBitmap
+ #wxBitmapButton
+ #wxBitmapDataObject
+ wxBMPHandler
+ #wxBoxSizer
+ #wxBrush
+ #wxBusyInfo
+ #wxBusyCursor
+ #wxButton
+ #wxCalculateLayoutEvent
+ #wxCalendarCtrl
+ #wxCaret
+ #wxCheckBox
+ #wxCheckListBox
+ #wxChoice
+ #wxClientDC
+ #wxClipboard
+ #wxCloseEvent
+ #wxColourData
+ #wxColourDialog
+ #wxColour
+ #wxComboBox
+ #wxCommandEvent
+ #wxConfig
+ #wxControl
+ #wxCursor
+ #wxCustomDataObject
+ #wxDataFormat
+ #wxDataObject
+ #wxDataObjectComposite
+ #wxDataObjectSimple
+ #wxDateTime
+ #wxDateSpan
+ #wxDC
+ #wxDialog
+ #wxDirDialog
+ #wxDragImage
+ #wxDropFilesEvent
+ #wxDropSource
+ #wxDropTarget
+ #wxEraseEvent
+ #wxEvent
+ #wxEvtHandler
+ #wxFileConfig
+ #wxFileDataObject
+ #wxFileDialog
+ #wxFileDropTarget
+ #wxFileSystem
+ #wxFileSystemHandler
+ #wxFocusEvent
+ #wxFontData
+ #wxFontDialog
+ #wxFont
+ #wxFrame
+ #wxFSFile
+ #wxGauge
+ wxGIFHandler
+ #wxGLCanvas
+ #wxHtmlCell
+ #wxHtmlContainerCell
+ #wxHtmlDCRenderer
+ #wxHtmlEasyPrinting
+ #wxHtmlParser
+ #wxHtmlTagHandler
+ #wxHtmlTag
+ #wxHtmlWinParser
+ #wxHtmlPrintout
+ #wxHtmlWinTagHandler
+ #wxHtmlWindow
+ #wxIconizeEvent
+ #wxIcon
+ #wxIdleEvent
+ #wxImage
+ #wxImageHandler
+ #wxImageList
+ #wxIndividualLayoutConstraint
+ #wxInitDialogEvent
+ #wxInputStream
+ #wxInternetFSHandler
+ #wxJoystickEvent
+ wxJPEGHandler
+ #wxKeyEvent
+ #wxLayoutAlgorithm
+ #wxLayoutConstraints
+ #wxListBox
+ #wxListCtrl
+ #wxListEvent
+ #wxListItem
+ #wxMask
+ #wxMaximizeEvent
+ #wxMDIChildFrame
+ #wxMDIClientWindow
+ #wxMDIParentFrame
+ #wxMemoryDC
+ #wxMemoryFSHandler
+ #wxMenuBar
+ #wxMenuEvent
+ #wxMenuItem
+ #wxMenu
+ #wxMessageDialog
+ #wxMetaFileDC
+ #wxMiniFrame
+ #wxMouseEvent
+ #wxMoveEvent
+ #wxNotebookEvent
+ #wxNotebook
+ #wxPageSetupDialogData
+ #wxPageSetupDialog
+ #wxPaintDC
+ #wxPaintEvent
+ #wxPalette
+ #wxPanel
+ #wxPen
+ wxPNGHandler
+ #wxPoint
+ #wxPostScriptDC
+ #wxPreviewFrame
+ #wxPrintData
+ #wxPrintDialogData
+ #wxPrintDialog
+ #wxPrinter
+ #wxPrintPreview
+ #wxPrinterDC
+ #wxPrintout
+ #wxProcess
+ #wxQueryLayoutInfoEvent
+ #wxRadioBox
+ #wxRadioButton
+ #wxRealPoint
+ #wxRect
+ #wxRegionIterator
+ #wxRegion
+ #wxSashEvent
+ #wxSashLayoutWindow
+ #wxSashWindow
+ #wxScreenDC
+ #wxScrollBar
+ #wxScrollEvent
+ #wxScrolledWindow
+ #wxScrollWinEvent
+ wxShowEvent
+ #wxSingleChoiceDialog
+ #wxSizeEvent
+ #wxSize
+ #wxSizer
+ #wxSizerItem
+ #wxSlider
+ #wxSpinButton
+ #wxSpinEvent
+ #wxSplitterWindow
+ #wxStaticBitmap
+ #wxStaticBox
+ #wxStaticBoxSizer
+ #wxStaticLine
+ #wxStaticText
+ #wxStatusBar
+ #wxSysColourChangedEvent
+ #wxTaskBarIcon
+ #wxTextCtrl
+ #wxTextDataObject
+ #wxTextDropTarget
+ #wxTextEntryDialog
+ #wxTimer
+ #wxTimerEvent
+ #wxTimeSpan
+ #wxTipProvider
+ wxToolBarTool
+ #wxToolBar
+ #wxToolTip
+ #wxTreeCtrl
+ #wxTreeEvent
+ #wxTreeItemData
+ wxTreeItemId
+ #wxUpdateUIEvent
+ #wxValidator
+ #wxWindowDC
+ #wxWindow
+ #wxZipFSHandler
+
+
+
+ @section wxphelp Where to go for help
+
+ Since wxPython is a blending of multiple technologies, help comes from
+ multiple sources. See
+ #http://wxpython.org/ for details on
+ various sources of help, but probably the best source is the
+ wxPython-users mail list. You can view the archive or subscribe by
+ going to
+ #http://lists.wxwindows.org/mailman/listinfo/wxpython-users
+ Or you can send mail directly to the list using this address:
+ wxpython-users@lists.wxwindows.org
+
+ */
+
+
projects / wxWidgets.git / blobdiff