X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ac1edf3546bcb9305c288ab5c91cb6aaa08af69a..60b73526d6797ee466c272dbfca962a230bc5908:/docs/latex/wx/wxPython.tex diff --git a/docs/latex/wx/wxPython.tex b/docs/latex/wx/wxPython.tex index baf996cb0b..4c2d01d414 100644 --- a/docs/latex/wx/wxPython.tex +++ b/docs/latex/wx/wxPython.tex @@ -1,5 +1,5 @@ \chapter{wxPython Notes}\label{wxPython} -\pagenumbering{arabic}% + \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% \setfooter{\thepage}{}{}{}{}{\thepage}% @@ -14,8 +14,8 @@ wxPython is a blending of the wxWindows GUI classes and the \wxheading{Python} So what is Python? Go to -\urlref{http://www.python.org}{http://www.python.org} -to learn more, but in a nutshell Python is an interpreted, +\urlref{http://www.python.org}{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. @@ -33,38 +33,37 @@ commercial use. 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 wxWindows GUI classes. This extension module -attempts to mirror the class heiarchy of wxWindows as closely as -possble. This means that there is a wxFrame class in wxPython that +(native code). It provides a series of Python classes that mirror (or +shadow) many of the wxWindows GUI classes. This extension module +attempts to mirror the class heirarchy of wxWindows 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 versitile. It can be used to create standalone GUI +wxPython is very versitile. 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. The effort to -enable wxPython for wxMotif will begin shortly. See \helpref{Building Python}{wxpbuild} for +toolkit (wxGTK) on most Unix/X-windows platforms. See the wxPython +website \urlref{http://wxPython.org/}{http://wxPython.org/} for details about getting wxPython working for you. - %---------------------------------------------------------------------- \section{Why use wxPython?}\label{wxpwhy} So why would you want to use wxPython over just C++ and wxWindows? -Personally I prefer using Python for everything. I only use C++ when -I absolutely have to eek more performance out of an algorithm, and even -then I ususally code it as an extension module and leave the majority +Personally I prefer using Python for everything. I only use C++ when I +absolutely have to eek 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 -wxWindows apps. With C++ you have to continuously go though the -edit-compile-link-run cycle, which can be quite time comsuming. With -Python it is only an edit-run cycle. You can easily build an +wxWindows 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++/wxWindows app +days or longer with C++. Converting a wxPython app to a C++/wxWindows app should be a straight forward task. %---------------------------------------------------------------------- @@ -74,151 +73,67 @@ There are other GUI solutions out there for Python. \wxheading{Tkinter} -Tkinter is the defacto standard GUI for Python. It is available -on nearly every platform that Python and Tcl/TK are. Why Tcl/Tk? +Tkinter is the defacto 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 veristile 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 interchangably in your +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 +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 +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 lastest version of Tcl/Tk that native Look and -Feel's were possible on non-Motif platforms. This is because Tk -usually implements it's own widgets (controls) even when there are +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 +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. \wxheading{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 +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 +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. \wxheading{Others} There are quite a few other GUI modules available for Python, some in -active use, some that havn't been updated for ages. Most are simple +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 \urlref{this -link}{http://www.python.org/download/Contributed.html\#Graphics} +cross-platform compatible. See \urlref{this link}{http://www.python.org/download/Contributed.html\#Graphics} for a listing of a few of them. -%---------------------------------------------------------------------- -\section{Building wxPython}\label{wxpbuild} - -I used SWIG (\urlref{http://www.swig.org}{http://www.swig.org}) to -to create the source code for the -extension module. This enabled me to only have to deal with a small -amount of code and only have to bother with the exceptional issues. -SWIG takes care of the rest and generates all the repetative code for -me. You don't need SWIG to build the extension module as all the -generated C++ code is included under the src directory. - -I added a few minor features to SWIG to control some of the code -generation. If you want to play around with this you will need to get -a recent version of SWIG from their CVS or from a daily build. See -\urlref{http://www.swig.org/}{http://www.swig.org/} for details. - -wxPython is organized as a Python package. This means that the -directory containing the results of the build process should be a -subdirectory of a directory on the \tt{PYTHONPATH}. (And preferably should -be named wxPython.) You can control where the build process will dump -wxPython by setting the \tt{TARGETDIR} variable for the build utility, (see -below.) - -\begin{enumerate}\itemsep=0pt -\item Build wxWindows as described in its BuildCVS.txt file. For *nix - systems I run configure with these flags: - -\begin{verbatim} - --with-gtk - --with-libjpeg - --without-odbc - --enable-unicode=no - --enable-threads=yes - --enable-socket=yes - --enable-static=no - --enable-shared=yes - --disable-std_iostreams -\end{verbatim} - - You can use whatever flags you want, but I know these work. - - For Win32 systems I use Visual C++ 6.0, but 5.0 should work also. The - build utility currently does not support any other win32 compilers. - -\item At this point you may want to make an alias or symlink, script, - batch file, whatever on the PATH that invokes - \tt{\$(WXWIN)/utils/wxPython/distrib/build.py} to help simplify matters - somewhat. For example, on my win32 system I have a file named - \tt{build}.bat in a directory on the PATH that contains: - - \tt{python \%WXWIN/utils/wxPython/distrib/build.py \%1 \%2 \%3 \%4 \%5 \%6} - - -\item Change into the \tt{\$(WXWIN)/utils/wxPython/src} directory. - -\item Type "\tt{build -b}" to build wxPython and "\tt{build -i}" to -install it, or \"\tt{build -bi}\" to do both steps at once. - - The build.py script actually generates a Makefile based on what it - finds on your system and information found in the build.cfg file. - If you have troubles building or you want it built or installed in - a different way, take a look at the docstring in build.py. You are - able to to override many configuration options in a file named - build.local. - -\item To build and install the add-on modules, change to the appropriate - directory under \tt{\$(WXWIN)/utils/wxPython/modules} and run the build - utility again. - -\item Change to the \tt{\$(WXWIN)/utils/wxPython/demo} directory. - -\item Try executing the demo program. For example: - - \tt{python demo.py} - -To run it without requiring a console on win32, you can use the -\tt{pythonw.exe} version of Python either from the command line or from a -shortcut. - - - -\end{enumerate} - %---------------------------------------------------------------------- \section{Using wxPython}\label{wxpusing} \wxheading{First things first...} -I'm not going to try and teach the Python language here. You can do +I'm not going to try and teach the Python language here. You can do that at the \urlref{Python Tutorial}{http://www.python.org/doc/tut/tut.html}. I'm also going to assume that you know a bit about wxWindows 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 \tt{wxPython/demo} directory, named \tt{DialogUnits.py}. If your +Take a look at the following wxPython program. You can find a similar +program in the {\tt wxPython/demo} directory, named {\tt DialogUnits.py}. If your Python and wxPython are properly installed, you should be able to run it by issuing this command: \begin{indented}{1cm} - \bftt{python DialogUnits.py} + {\bf\tt python DialogUnits.py} \end{indented} \hrule @@ -303,51 +218,51 @@ it by issuing this command: \wxheading{Things to notice} -\begin{enumerate}\itemsep=0pt +\begin{enumerate}\itemsep=11pt \item 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 "\tt{from wxPython import wx}" and +into the current module's namespace. If you prefer to reduce +namespace pollution you can use "{\tt from wxPython import wx}" and then access all the wxPython identifiers through the wx module, for -example, "\tt{wx.wxFrame}". +example, "{\tt wx.wxFrame}". \item 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 wxWindows employs. But since static event +methods of the class. These helper functions are intended to be like +the event table macros that wxWindows 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 arguemnt to the event helpers is always the window that +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. -\item Notice the use of \tt{wxDLG\_PNT} and \tt{wxDLG\_SZE} in lines 19 -- 29 to convert from dialog units to pixels. These helpers are unique +\item Notice the use of {\tt wxDLG\_PNT} and {\tt 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++. -\item There is an \tt{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 -\em{standard} events are attached to windows that have the associated -\em{standard} method names. I have tried to follow the lead of the -C++ classes in this area to determine what is \em{standard} but since -that changes from time to time I can make no guarentees, nor will it -be fully documented. When in doubt, use an EVT\_*** function. +\item There is an {\tt 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 +{\em standard} events are attached to windows that have the associated +{\em standard} method names. I have tried to follow the lead of the +C++ classes in this area to determine what is {\em 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. \item 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 +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 -coresponding C++ objects. Once the C++ windows and controls are +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 +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 +deleted. If you ever have the need to forcibly delete a window, use the Destroy() method as shown on line 36. \item Just like wxWindows in C++, wxPython apps need to create a class -derived from \tt{wxApp} (line 56) that implements a method named -\tt{OnInit}, (line 59.) This method should create the application's -main window (line 62) and use \tt{wxApp.SetTopWindow()} (line 66) to +derived from {\tt wxApp} (line 56) that implements a method named +{\tt OnInit}, (line 59.) This method should create the application's +main window (line 62) and use {\tt wxApp.SetTopWindow()} (line 66) to inform wxWindows about it. \item And finally, at line 72 an instance of the application class is -created. At this point wxPython finishes initializing itself, and calls -the \tt{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 \tt{MainLoop} at line 73 starts the event +created. At this point wxPython finishes initializing itself, and calls +the {\tt 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 {\tt MainLoop} at line 73 starts the event loop which continues until the application terminates or all the top level windows are closed. \end{enumerate} @@ -355,25 +270,32 @@ level windows are closed. %---------------------------------------------------------------------- \section{wxWindows classes implemented in wxPython}\label{wxpclasses} -The following classes are supported in wxPython. Most provide nearly +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 +documentation, others are less so. They will all be brought as close as possible to the C++ spec over time. \begin{itemize}\itemsep=0pt \item \helpref{wxAcceleratorEntry}{wxacceleratorentry} \item \helpref{wxAcceleratorTable}{wxacceleratortable} \item \helpref{wxActivateEvent}{wxactivateevent} -\item \helpref{wxBitmapButton}{wxbitmapbutton} \item \helpref{wxBitmap}{wxbitmap} +\item \helpref{wxBitmapButton}{wxbitmapbutton} +\item \helpref{wxBitmapDataObject}{wxbitmapdataobject} \item wxBMPHandler +\item \helpref{wxBoxSizer}{wxboxsizer} \item \helpref{wxBrush}{wxbrush} +\item \helpref{wxBusyInfo}{wxbusyinfo} +\item \helpref{wxBusyCursor}{wxbusycursor} \item \helpref{wxButton}{wxbutton} \item \helpref{wxCalculateLayoutEvent}{wxcalculatelayoutevent} +\item \helpref{wxCalendarCtrl}{wxcalendarctrl} +\item wxCaret \item \helpref{wxCheckBox}{wxcheckbox} \item \helpref{wxCheckListBox}{wxchecklistbox} \item \helpref{wxChoice}{wxchoice} \item \helpref{wxClientDC}{wxclientdc} +\item \helpref{wxClipboard}{wxclipboard} \item \helpref{wxCloseEvent}{wxcloseevent} \item \helpref{wxColourData}{wxcolourdata} \item \helpref{wxColourDialog}{wxcolourdialog} @@ -383,25 +305,54 @@ as possible to the C++ spec over time. \item \helpref{wxConfig}{wxconfigbase} \item \helpref{wxControl}{wxcontrol} \item \helpref{wxCursor}{wxcursor} +\item \helpref{wxCustomDataObject}{wxcustomdataobject} +\item \helpref{wxDataFormat}{wxdataformat} +\item \helpref{wxDataObject}{wxdataobject} +\item \helpref{wxDataObjectComposite}{wxdataobjectcomposite} +\item \helpref{wxDataObjectSimple}{wxdataobjectsimple} +\item \helpref{wxDateTime}{wxdatetime} +\item \helpref{wxDateSpan}{wxdatespan} \item \helpref{wxDC}{wxdc} \item \helpref{wxDialog}{wxdialog} \item \helpref{wxDirDialog}{wxdirdialog} +\item \helpref{wxDragImage}{wxdragimage} \item \helpref{wxDropFilesEvent}{wxdropfilesevent} +\item \helpref{wxDropSource}{wxdropsource} +\item \helpref{wxDropTarget}{wxdroptarget} \item \helpref{wxEraseEvent}{wxeraseevent} \item \helpref{wxEvent}{wxevent} \item \helpref{wxEvtHandler}{wxevthandler} +\item wxFileConfig +\item \helpref{wxFileDataObject}{wxfiledataobject} \item \helpref{wxFileDialog}{wxfiledialog} +\item \helpref{wxFileDropTarget}{wxfiledroptarget} +\item \helpref{wxFileSystem}{wxfilesystem} +\item \helpref{wxFileSystemHandler}{wxfilesystemhandler} \item \helpref{wxFocusEvent}{wxfocusevent} \item \helpref{wxFontData}{wxfontdata} \item \helpref{wxFontDialog}{wxfontdialog} \item \helpref{wxFont}{wxfont} \item \helpref{wxFrame}{wxframe} +\item \helpref{wxFSFile}{wxfsfile} \item \helpref{wxGauge}{wxgauge} \item wxGIFHandler \item wxGLCanvas +\begin{comment} \item wxGridCell \item wxGridEvent \item \helpref{wxGrid}{wxgrid} +\end{comment} +\item \helpref{wxHtmlCell}{wxhtmlcell} +\item \helpref{wxHtmlContainerCell}{wxhtmlcontainercell} +\item \helpref{wxHtmlDCRenderer}{wxhtmldcrenderer} +\item \helpref{wxHtmlEasyPrinting}{wxhtmleasyprinting} +\item \helpref{wxHtmlParser}{wxhtmlparser} +\item \helpref{wxHtmlTagHandler}{wxhtmltaghandler} +\item \helpref{wxHtmlTag}{wxhtmltag} +\item \helpref{wxHtmlWinParser}{wxhtmlwinparser} +\item \helpref{wxHtmlPrintout}{wxhtmlprintout} +\item \helpref{wxHtmlWinTagHandler}{wxhtmlwintaghandler} +\item \helpref{wxHtmlWindow}{wxhtmlwindow} \item wxIconizeEvent \item \helpref{wxIcon}{wxicon} \item \helpref{wxIdleEvent}{wxidleevent} @@ -410,6 +361,8 @@ as possible to the C++ spec over time. \item \helpref{wxImageList}{wximagelist} \item \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint} \item \helpref{wxInitDialogEvent}{wxinitdialogevent} +\item \helpref{wxInputStream}{wxinputstream} +\item \helpref{wxInternetFSHandler}{fs} \item \helpref{wxJoystickEvent}{wxjoystickevent} \item wxJPEGHandler \item \helpref{wxKeyEvent}{wxkeyevent} @@ -419,12 +372,13 @@ as possible to the C++ spec over time. \item \helpref{wxListCtrl}{wxlistctrl} \item \helpref{wxListEvent}{wxlistevent} \item \helpref{wxListItem}{wxlistctrlsetitem} +\item \helpref{wxMask}{wxmask} +\item wxMaximizeEvent \item \helpref{wxMDIChildFrame}{wxmdichildframe} \item \helpref{wxMDIClientWindow}{wxmdiclientwindow} \item \helpref{wxMDIParentFrame}{wxmdiparentframe} -\item \helpref{wxMask}{wxmask} -\item wxMaximizeEvent \item \helpref{wxMemoryDC}{wxmemorydc} +\item \helpref{wxMemoryFSHandler}{wxmemoryfshandler} \item \helpref{wxMenuBar}{wxmenubar} \item \helpref{wxMenuEvent}{wxmenuevent} \item \helpref{wxMenuItem}{wxmenuitem} @@ -454,6 +408,7 @@ as possible to the C++ spec over time. \item \helpref{wxPrintPreview}{wxprintpreview} \item \helpref{wxPrinterDC}{wxprinterdc} \item \helpref{wxPrintout}{wxprintout} +\item \helpref{wxProcess}{wxprocess} \item \helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent} \item \helpref{wxRadioBox}{wxradiobox} \item \helpref{wxRadioButton}{wxradiobutton} @@ -468,24 +423,33 @@ as possible to the C++ spec over time. \item \helpref{wxScrollBar}{wxscrollbar} \item \helpref{wxScrollEvent}{wxscrollevent} \item \helpref{wxScrolledWindow}{wxscrolledwindow} +\item \helpref{wxScrollWinEvent}{wxscrollwinevent} \item wxShowEvent \item \helpref{wxSingleChoiceDialog}{wxsinglechoicedialog} \item \helpref{wxSizeEvent}{wxsizeevent} \item \helpref{wxSize}{wxsize} +\item \helpref{wxSizer}{wxsizer} +\item wxSizerItem \item \helpref{wxSlider}{wxslider} \item \helpref{wxSpinButton}{wxspinbutton} \item wxSpinEvent \item \helpref{wxSplitterWindow}{wxsplitterwindow} \item \helpref{wxStaticBitmap}{wxstaticbitmap} \item \helpref{wxStaticBox}{wxstaticbox} -\item wxStaticLine +\item \helpref{wxStaticBoxSizer}{wxstaticboxsizer} +\item \helpref{wxStaticLine}{wxstaticline} \item \helpref{wxStaticText}{wxstatictext} \item \helpref{wxStatusBar}{wxstatusbar} \item \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent} \item \helpref{wxTaskBarIcon}{wxtaskbaricon} \item \helpref{wxTextCtrl}{wxtextctrl} +\item \helpref{wxTextDataObject}{wxtextdataobject} +\item \helpref{wxTextDropTarget}{wxtextdroptarget} \item \helpref{wxTextEntryDialog}{wxtextentrydialog} \item \helpref{wxTimer}{wxtimer} +\item \helpref{wxTimerEvent}{wxtimerevent} +\item \helpref{wxTimeSpan}{wxtimespan} +\item \helpref{wxTipProvider}{wxtipprovider} \item wxToolBarTool \item \helpref{wxToolBar}{wxtoolbar} \item wxToolTip @@ -494,10 +458,10 @@ as possible to the C++ spec over time. \item \helpref{wxTreeItemData}{wxtreeitemdata} \item wxTreeItemId \item \helpref{wxUpdateUIEvent}{wxupdateuievent} +\item \helpref{wxValidator}{wxvalidator} \item \helpref{wxWindowDC}{wxwindowdc} \item \helpref{wxWindow}{wxwindow} - - +\item \helpref{wxZipFSHandler}{fs} \end{itemize} %---------------------------------------------------------------------- @@ -505,14 +469,15 @@ as possible to the C++ spec over time. Since wxPython is a blending of multiple technologies, help comes from multiple sources. See -\urlref{http://alldunn.com/wxPython}{http://alldunn.com/wxPython} for details on +\urlref{http://wxpython.org/}{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 +wxPython-users mail list. You can view the archive or subscribe by going to -\urlref{http://starship.python.net/mailman/listinfo/wxpython-users}{http://starship.python.net/mailman/listinfo/wxpython-users} +\urlref{http://lists.wxwindows.org/mailman/listinfo/wxpython-users}{http://lists.wxwindows.org/mailman/listinfo/wxpython-users} Or you can send mail directly to the list using this address: -wxpython-users@starship.python.net +wxpython-users@lists.wxwindows.org +