X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0699c8646a72ffd13f3a0b3ab746ec3cbec5bd28..90bc25c7c932a6f7510bd6f7155efb958e73974d:/utils/wxPython/README.txt diff --git a/utils/wxPython/README.txt b/utils/wxPython/README.txt index 84de32ebda..d2b1fa6b0a 100644 --- a/utils/wxPython/README.txt +++ b/utils/wxPython/README.txt @@ -1,44 +1,30 @@ wxPython README --------------- -Introduction ------------- -The code in this subtree is a Python Extension Module that enables the -use of wxWindows from the Python language. So what is Python? Go to -http://www.python.org to learn more but in a nutshell, it's an -extremly cool object oriented language. It's easier than Perl and -nearly as powerful. It runs on more platforms than Java, and by some -reports, is even faster than Java with a JIT compiler! - -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 absolutly have to eek more performance out of an algorithm, and even -then I ususally 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 application in a few hours with Python that would -normally take a few days with C++. Converting a wxPython app to a -C++/wxWindows app should be a straight forward task. - -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 looks, smells, tastes and acts almost the same -as the wxFrame class in the C++ version. Unfortunatly, I wasn't able -to match things exactly because of differences in the languages, but -the differences should be easy to absorb because they are natural to -Python. For example, some methods that return mutliple values via -argument pointers in C++ will return a tuple of values in Python. -These differences have not been documented yet so if something isn't -working the same as described in the wxWindows documents the best -thing to do is to scan through the wxPython sources, especially the .i -files, as that is where the interfaces for wxPython are defined. - -I have reports of successfully embedding wxPython within a wxWindows -C++ app on GTK. It hasn't yet been attempted on MSW (to my knowledge) -so I don't know how successful such an attempt would be. However it -is certainly possible. +Welcome to the wonderful world of wxPython! + +Once you have installed the wxPython extension module, you can try it +out by going to the [install dir]\wxPython\demo directory and typing: + + python demo.py + +There are also some other sample files there for you to play with and +learn from. + +If you selected to install the documentation then point your browser +to [install dir]\wxPython\docs\index.htm and you will then be looking +at the docs for wxWindows. For the most part you can use the C++ docs +as most classes and methods are used identically. Where there are +differences they are documented with a "wxPython Note." + +On Win32 systems the binary self-installer creates a program group on +the Start Menu that contains a link to running the demo and a link to +the help file. To help you save disk space I'm now using Microsoft's +HTML Help format. If your system doesn't know what to do with the help +file, you can install the HTML Help Viewer as part of IE 4+, NT +Service Pack 4+, or the HTML Workshop at + +http://msdn.microsoft.com/workshop/author/htmlhelp/download.asp. @@ -57,8 +43,333 @@ Or you can send mail directly to the list using this address: wxpython-users@starship.python.net +---------------------------------------------------------------------- + +What's new in 2.1.5 +------------------- +This is a quick bug-fix release to take care of a few nasties that +crept in at the last minute before 2.1.4 was called done. No new +major features. + + + +What's new in 2.1.4 +-------------------- + +This release is NOT syncronized with a snapshot release of wxGTK or +wxMSW. For MSW this isn't much of a problem since you can get the +binaries from the web site. For other platforms you'll have to build +wxGTK from CVS. (See http://web.ukonline.co.uk/julian.smart/wxwin/cvs.htm) +To get the same set of sources from CVS that I used, checkout using +the wxPy-2-1-4 tag. + +Now back to what's new... + +Much more support for event-less callbacks and add-on modules. + +Created add-on module with wxOGL classes. + +Added wxWindow.GetChildren(). Be careful of this. It returns a *copy* +of the list of the window's children. While you are using the list if +anything changes in the real list (a child is deleted, etc.) then the +list you are holding will suddenly have window references to garbage +memory and your app will likely crash. But if you are careful it works +great! + +Added a bunch of new and missing methods to wxTreeCrtl. The +SortChildren method is now supported, but currently only for the +default sort order. + +Added typemaps for wxSize, wxPoint, wxRealPoint, and wxRect that allow +either the actual objects or Python sequence values to be used. For +example, the following are equivallent: + + win = wxWindow(parent, size = wxSize(100, 100)) + win = wxWindow(parent, size = (100, 100)) + +Super-charged the wxHtml module. You can now create your own tag +handlers and also have access to the parser and cell classes. There +is a tag handler in the library at wxPython.lib.wxpTag that +understands the WXP tag and is able to place wxPython windows on HTML +pages. See the demo for an example. + +A bunch of the methods of wxMenuBar were previously ifdef'd out for +wxGTK. Added them back in since the methods exist now. + +Wrapped the wxHtmlHelpController and related classes. + +Wrapped the C++ versions of wxSizer and firends. The Python-only +versions are still in the library, but depreciated. (You will get a +warning message if you try to use them, but the warning can be +disabled.) The usage of the C++ versions is slightly different, and +the functionality of wxBorderSizer is now part of wxBoxSizer. I have +added a few methods to wxSizer to try and make the transition as +smooth as possible, I combined all Add methods into a single method +that handles all cases, added an AddMany method, etc. One step I did +not take was to make the default value of flag in the Add method be +wxGROW. This would have made it more backward compatible, but less +portable to and from wxWin C++ code. Please see the docs and demo for +further details. + +Added wxPyEvent and wxPyCommandEvent classes, derived from wxEvent and +wxCommandEvent. Each of them has SetPyData and GetPyData methods that +accept or return a single Python object. You can use these classes +directly or derive from them to create your own types of event objects +that can pass through the wxWindows event system without loosing their +Python parts (as long as they are stored with SetPyData.) Stay tuned +for more info and examples in future releases. + +Added wxPython.lib.grids as an example of how to derive a new sizer +from the C++ sizers. In this module you will find wxGridSizer and +wxFlexGridSizer. wxGridSizer arrainges its items in a grid in which +all the widths and heights are the same. wxFlexgridSizer allows +different widths and heights, and you can also specify rows and/or +columns that are growable. See the demo for a couple examples for how +to use them. + +Added the wxValidator class, and created a class named wxPyValidator +that should be used for the base class of any Python validators. See +the demo for an example. Please note that you MUST implement a Clone +method in your validator classes because of the way some things work +in the underlying C++ library. I did not add wxTextValidator because +of some issues of how it transfers data to and from a wxString, which +in wxPython is automatically translated to and from Python strings, so +there would never be a concrete wxString that would hang around long +enough for the validator to do its job. On the other hand, it should +be real easy to duplicate the functionality of wxTextValidator in a +pure Python class derived from wxPyValidator. + +I've finally added a feature that has been on my list for close to two +years! Ever wondered what that zero is for when you create your app +object? Well now you can leave it out or explicitly set it to a true +value. This value now controls what is to be done with sys.stdout and +sys.stderr. A false value leaves them alone, and a true value sets +them to an instance of wxPyOnDemandOutputWindow. (On windows the +default is true, on unix platforms the default is false.) This class +creates a frame containing a wxTextCtrl as soon as anything is written +to sys.stdout or sys.stderr. If you close the window it will come +back again the next time something is written. (You can call +app.RestoreStdio to turn this off.) If you would rather that the stdio be +redirected to a file, you can provide a second parameter to your app +object's constructor that is a filename. If you want to use your own +class instead of wxPyOnDemandOutputWindow you can either implement +RedirectStdio() in you app class or change the value of +wxApp.outputWindowClass like this: + + class MyApp(wxApp): + outputWindowClass = MyClass + + def OnInit(self): + frame = MyFrame() + self.SetTopWindow(frame) + return true + +Please see the implementation of wxPyOnDemandOutputWindow and wxApp in +wx.py for more details. A few words of caution: if you are running +your app in a debugger, changing sys.stdout and sys.stderr is likely +to really screw things up. + +Added wxCaret. Unfortunately it's author has still not documented it +in the wxWindows docs... + +Some new 3rd party contributions in wxPython.lib. PyShell, in +shell.py is an interesting implementaion of an interactive Python +shell in wxWindows. floatbar.py has a class derived from wxTooBar +that can sense mouse drags and then reparent itself into another +frame. Moving the new frame close to where it came from puts the tool +bar back into the original parent. (Unfortunately there is currently +a bug in wxGTK's wxFrame.SetToolBar so the FloatBar has some +problems...) + + + + +What's new in 2.1b3 +-------------------- + +This release is syncronized with release 2.1 snapshot 9 of wxWindows. + +Switched to using SWIG from CVS (see http://swig.cs.uchicago.edu/cvs.html) +for some of the new features and such. Also they have encorporated my +patches so there is really no reason to stick with the current (very +old) release... This version of SWIG gives the following new +features: + + 1. Keyword arguments. You no longer have to specify all the + parameters with defaults to a method just to specify a + non-default value on the end. You can now do this instead: + + win = wxWindow(parent, -1, style = mystyle) + + 2. There is now an an equivalence between Python's None and C++'s + NULL. This means that any methods that might return NULL will + now return None and you can use none where wxWindows might be + expecting NULL. This makes things much more snake-ish. + + +There is a new build system based on a new Python program instead of +raw makefiles. Now wxPython builds are virtually the same on MSW or +Unix systems. See the end of this file for new build instructions and +see distrib/build.py for more details. + +wxDC.Bilt now includes the useMask parameter, and has been split into +two different versions. wxDC.BlitXY is like what was there before and +takes raw coordinants and sizes, and the new wxDC.Blit is for the new +interface using wxPoints and a wxSize. + + + + + +What's new in 2.1b2 +-------------------- + +Added the missing wxWindow.GetUpdateRegion() method. + +Made a new change in SWIG (update your patches everybody) that +provides a fix for global shadow objects that get an exception in +their __del__ when their extension module has already been deleted. +It was only a 1 line change in .../SWIG/Modules/pycpp.cxx at about +line 496 if you want to do it by hand. + +It is now possible to run through MainLoop more than once in any one +process. The cleanup that used to happen as MainLoop completed (and +prevented it from running again) has been delayed until the wxc module +is being unloaded by Python. + +I fixed a bunch of stuff in the C++ version of wxGrid so it wouldn't +make wxPython look bad. + +wxWindow.PopupMenu() now takes a wxPoint instead of x,y. Added +wxWindow.PopupMenuXY to be consistent with some other methods. + +Added wxGrid.SetEditInPlace and wxGrid.GetEditInPlace. + +You can now provide your own app.MainLoop method. See +wxPython/demo/demoMainLoop.py for an example and some explaination. + +Got the in-place-edit for the wxTreeCtrl fixed and added some demo +code to show how to use it. + +Put the wxIcon constructor back in for GTK as it now has one that +matches MSW's. + +Added wxGrid.GetCells + +Added wxSystemSettings static methods as functions with names like +wxSystemSettings_GetSystemColour. + +Removed wxPyMenu since using menu callbacks have been depreciated in +wxWindows. Use wxMenu and events instead. + +Added alternate wxBitmap constructor (for MSW only) as + wxBitmapFromData(data, type, width, height, depth = 1) + +Added a helper function named wxPyTypeCast that can convert shadow +objects of one type into shadow objects of another type. (Like doing +a down-cast.) See the implementation in wx.py for some docs. + +Fixed wxImage GetData and SetData to properly use String objects for +data transfer. + +Added access methods to wxGridEvent. + +New Makefile/Setup files supporting multiple dynamic extension modules +for unix systems. + +Fixes for the wxGLCanvas demo to work around a strange bug in gtk. + +SWIG support routines now compiled separately instead of being bundled +in wx.cpp. + + + +What's new in 2.1b1 +-------------------- +Fixed wxComboBox.SetSelection so that it actually sets the selected +item. (Actually just removed it from wxPython and let it default to +wxChoice.SetSelection which was already doing the right thing.) + +Added the Printing Framework. + +Switched back to using the wxWindows DLL for the pre-built Win32 +version. The problem was needing to reinitialize static class info +data after loading each extension module. + +Lots of little tweaks and additions to reflect changes to various +wxWindows classes. + +Fixed a bug with attaching objects to tree items. Actually was a +symptom of a larger problem with not obtaining the interpreter lock +when doing any Py_DECREFs. + +wxSizer and friends. Sizers are layout tools that manage a colection +of windows and sizers. Different types of sizers apply different +types of layout algorithms. You saw it here first! These classes are +not even in the wxWindows C++ library yet! + + + +What's new in 2.0b9 +------------------- +Bug fix for ListCtrl in test4.py (Was a missing file... DSM!) + +Bug fix for occassional GPF on Win32 systems upon termination of a +wxPython application. + +Added wxListBox.GetSelections returning selections as a Tuple. + +Added a wxTreeItemData that is able to hold any Python object and be +associated with items in a wxTreeCtrl. Added test pytree.py to show +this feature off. + +Added wxSafeYield function. + +OpenGL Canvas can be optionally compiled in to wxPython. + +Awesome new Demo Framework for showing off wxPython and for learning +how it all works. + +The pre-built Win32 version is no longer distributing the wxWindows +DLL. It is statically linked with the wxWindows library instead. + +Added a couple missing items from the docs. + +Added wxImage, wxImageHandler, wxPNGHandler, wxJPEGHandler, +wxGIFHandler and wxBMPHandler. + +Added new methods to wxTextCtrl. + +Fixed some problems with how SWIG was wrapping some wxTreeCtrl +methods. + + + +What's new in 2.0b8 +------------------- +Support for using Python threads in wxPython apps. + +Several missing methods from various classes. + +Various bug fixes. + + + +What's new in 2.0b7 +------------------- +Added DLG_PNT and DLG_SZE convienience methods to wxWindow class. + +Added missing constructor and other methods for wxMenuItem. + + + +What's new in 2.0b6 +------------------- +Just a quickie update to fix the self-installer to be compatible with +Python 1.5.2b2's Registry settings. + What's new in 2.0b5 ------------------- @@ -70,7 +381,7 @@ with the 2.0 version of wxWindows. I have finally started documenting wxPython. There are several pages in the wxWindows documentation tree specifically about wxPython, and I -have added notes within the class references about where wxPython +have added notes within the class references about where and how wxPython diverges from wxWindows. Added wxWindow_FromHWND(hWnd) for wxMSW to construct a wxWindow from a @@ -128,7 +439,6 @@ down a nasty DECREF bug. Okay so I have to confess that it was just a DSM (Dumb Stupid Mistake) on my part but it was nasty none the less because the behavior was so different on different platforms. - The dynamicly loaded module on Solaris is still segfaulting, so it must have been a different issue all along... @@ -148,6 +458,8 @@ version segfault shortly after starting up. 3. Varioius bug fixes, enhancements, etc. +---------------------------------------------------------------------- + Build Instructions @@ -160,89 +472,79 @@ 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 playaround with this the patches are in -wxPython/SWIG.patches and they should be applied to the 1.1p5 version -of SWIG. These new patches are documented at -http://starship.skyport.net/crew/robind/python/#swig, and they should -also end up in the 1.2 version of SWIG. +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 +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 PYTHONPATH. (And preferably should be named wxPython.) You can control where the build process will dump -wxPython by setting the TARGETDIR makefile variable. The default is -$(WXWIN)/utils/wxPython, where this README.txt is located. If you -leave it here then you should add $(WXWIN)/utils to your PYTHONPATH. -However, you may prefer to use something that is already on your -PYTHONPATH, such as the site-packages directory on Unix systems. - - -Win32 ------ - -1. Build wxWindows with wxUSE_RESOURCE_LOADING_IN_MSW set to 1 in -include/wx/msw/setup.h so icons can be loaded dynamically. While -there, make sure wxUSE_OWNER_DRAWN is also set to 1. - -2. Change into the $(WXWIN)/utils/wxPython/src directory. +wxPython by setting the TARGETDIR variable for the build utility, (see +below.) -3. Edit makefile.vc and specify where your python installation is at. -You may also want to fiddle with the TARGETDIR variable as described -above. -4. Run nmake -f makefile.vc +1. Build wxWindows as described in its BuildCVS.txt file. For *nix + systems I run configure with these flags: -5. If it builds successfully, congratulations! Move on to the next -step. If not then you can try mailing me for help. Also, I will -always have a pre-built win32 version of this extension module at -http://starship.skyport.net/crew/robind/python. + --with-gtk + --with-libjpeg + --without-odbc + --enable-unicode=no + --enable-threads=yes + --enable-socket=yes + --enable-static=no + --enable-shared=yes + --disable-std_iostreams -6. Change to the $(WXWIN)/utils/wxPython/tests directory. + You can use whatever flags you want, but I know these work. -7. Try executing the test programs. Note that some of these print -diagnositc or test info to standard output, so they will require the -console version of python. For example: + For Win32 systems I use Visual C++ 6.0, but 5.0 should work. The + build utility currently does not support any other win32 compilers. - python test1.py +2. At this point you may want to make an alias or symlink, script, + batch file, whatever on the PATH that invokes + $(WXWIN)/utils/wxPython/distrib/build.py to help simplify matters + somewhat. For example, on my win32 system I have a file named + build.bat in a directory on the PATH that contains: -To run them without requiring a console, you can use the pythonw.exe -version of Python either from the command line or from a shortcut. + python $(WXWIN)/utils/wxPython/distrib/build.py %1 %2 %3 %4 %5 %6 +3. Change into the $(WXWIN)/utils/wxPython/src directory. -Unix ----- +4. Type "build -b" to build wxPython and "build -i" to install it. -1. Change into the $(WXWIN)/utils/wxPython/src directory. + 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 may + be able to override configuration options in a file named + build.local. -2. Edit Setup.in and ensure that the flags, directories, and toolkit -options are correct. See the above commentary about TARGETDIR. There -are a few sample Setup.in.[platform] files provided. +5. To build and install the add-on modules, change to the appropriate + directory under $(WXWIN)/utils/wxPython/modules and run the build + utility again. -3. Run this command to generate a makefile: +6. Change to the $(WXWIN)/utils/wxPython/demo directory. - make -f Makefile.pre.in boot +7. Try executing the demo program. For example: -4. Run these commands to build and then install the wxPython extension -module: + python demo.py - make - make install +To run it without requiring a console on win32, you can use the +pythonw.exe version of Python either from the command line or from a +shortcut. -5. Change to the $(WXWIN)/utils/wxPython/tests directory. -6. Try executing the test programs. For example: - - python test1.py +---------------- +Robin Dunn +robin@alldunn.com ------------------------- -10/20/1998 -Robin Dunn -robin@alldunn.com