distrib/gtk/README.txt

   1 wxPython README
   2 ---------------
   3
   4 Introduction
   5 ------------
   6 The code in this subtree is a Python Extension Module that enables the
   7 use of wxWindows from the Python language.  So what is Python?  Go to
   8 http://www.python.org to learn more but in a nutshell, it's an
   9 extremly cool object oriented language.  It's easier than Perl and
  10 nearly as powerful.  It runs on more platforms than Java, and by some
  11 reports, is even faster than Java with a JIT compiler!
  12
  13 So why would you want to use wxPython over just C++ and wxWindows?
  14 Personally I prefer using Python for everything.  I only use C++ when
  15 I absolutly have to eek more performance out of an algorithm, and even
  16 then I ususally code it as an extension module and leave the majority
  17 of the program in Python.  Another good thing to use wxPython for is
  18 quick prototyping of your wxWindows apps.  With C++ you have to
  19 continuously go though the edit-compile-link-run cycle, which can be
  20 quite time comsuming.  With Python it is only an edit-run cycle.  You
  21 can easily build an application in a few hours with Python that would
  22 normally take a few days with C++.  Converting a wxPython app to a
  23 C++/wxWindows app should be a straight forward task.
  24
  25 This extension module attempts to mirror the class heiarchy of
  26 wxWindows as closely as possble.  This means that there is a wxFrame
  27 class in wxPython that looks, smells, tastes and acts almost the same
  28 as the wxFrame class in the C++ version.  Unfortunatly, I wasn't able
  29 to match things exactly because of differences in the languages, but
  30 the differences should be easy to absorb because they are natural to
  31 Python.  For example, some methods that return mutliple values via
  32 argument pointers in C++ will return a tuple of values in Python.
  33 These differences have not been documented yet so if something isn't
  34 working the same as described in the wxWindows documents the best
  35 thing to do is to scan through the wxPython sources, especially the .i
  36 files, as that is where the interfaces for wxPython are defined.
  37
  38 I have reports of successfully embedding wxPython within a wxWindows
  39 C++ app on GTK.  It hasn't yet been attempted on MSW (to my knowledge)
  40 so I don't know how successful such an attempt would be.  However it
  41 is certainly possible.
  42
  43
  44
  45 Getting Help
  46 ------------
  47
  48 Since wxPython is a blending of multiple technologies, help comes from
  49 multiple sources.  See the http://alldunn.com/wxPython for details on
  50 various sources of help, but probably the best source is the
  51 wxPython-users mail list.  You can view the archive or subscribe by
  52 going to
  53
  54        http://starship.python.net/mailman/listinfo/wxpython-users
  55
  56 Or you can send mail directly to the list using this address:
  57
  58        wxpython-users@starship.python.net
  59
  60
  61
  62 What's new in 2.0b9
  63 -------------------
  64 Bug fix for ListCtrl in test4.py (Was a missing file...  DSM!)
  65
  66 Bug fix for occassional GPF on Win32 systems upon termination of a
  67 wxPython application.
  68
  69 Added wxListBox.GetSelections returning selections as a Tuple.
  70
  71 Added a wxTreeItemData that is able to hold any Python object and be
  72 associated with items in a wxTreeCtrl.  Added test pytree.py to show
  73 this feature off.
  74
  75 Added wxSafeYield function.
  76
  77 OpenGL Canvas can be optionally compiled in to wxPython.
  78
  79 Awesome new Demo Framework for showing off wxPython and for learning
  80 how it all works.
  81
  82 The pre-built Win32 version is no longer distributing the wxWindows
  83 DLL.  It is statically linked with the wxWindows library instead.
  84
  85 Added a couple missing items from the docs.
  86
  87 Added wxImage, wxImageHandler, wxPNGHandler, wxJPEGHandler,
  88 wxGIFHandler and wxBMPHandler.
  89
  90 Added new methods to wxTextCtrl.
  91
  92
  93
  94 What's new in 2.0b8
  95 -------------------
  96 Support for using Python threads in wxPython apps.
  97
  98 Several missing methods from various classes.
  99
 100 Various bug fixes.
 101
 102
 103
 104 What's new in 2.0b7
 105 -------------------
 106 Added DLG_PNT and DLG_SZE convienience methods to wxWindow class.
 107
 108 Added missing constructor and other methods for wxMenuItem.
 109
 110
 111
 112 What's new in 2.0b6
 113 -------------------
 114 Just a quickie update to fix the self-installer to be compatible with
 115 Python 1.5.2b2's Registry settings.
 116
 117
 118 What's new in 2.0b5
 119 -------------------
 120 Well obviously the numbering scheme has changed.  I did this to
 121 reflect the fact that this truly is the second major revision of
 122 wxPython, (well the third actually if you count the one I did for
 123 wxWindows 1.68 and then threw away...) and also that it is associated
 124 with the 2.0 version of wxWindows.
 125
 126 I have finally started documenting wxPython.  There are several pages
 127 in the wxWindows documentation tree specifically about wxPython, and I
 128 have added notes within the class references about where wxPython
 129 diverges from wxWindows.
 130
 131 Added wxWindow_FromHWND(hWnd) for wxMSW to construct a wxWindow from a
 132 window handle.  If you can get the window handle into the python code,
 133 it should just work...  More news on this later.
 134
 135 Added wxImageList, wxToolTip.
 136
 137 Re-enabled wxConfig.DeleteAll() since it is reportedly fixed for the
 138 wxRegConfig class.
 139
 140 As usual, some bug fixes, tweaks, etc.
 141
 142
 143
 144 What's new in 0.5.3
 145 -------------------
 146 Added wxSashWindow, wxSashEvent, wxLayoutAlgorithm, etc.
 147
 148 Various cleanup, tweaks, minor additions, etc. to maintain
 149 compatibility with the current wxWindows.
 150
 151
 152
 153 What's new in 0.5.0
 154 -------------------
 155 Changed the import semantics from "from wxPython import *" to "from
 156 wxPython.wx import *"  This is for people who are worried about
 157 namespace pollution, they can use "from wxPython import wx" and then
 158 prefix all the wxPython identifiers with "wx."
 159
 160 Added wxTaskbarIcon for wxMSW.
 161
 162 Made the events work for wxGrid.
 163
 164 Added wxConfig.
 165
 166 Added wxMiniFrame for wxGTK.
 167
 168 Changed many of the args and return values that were pointers to gdi
 169 objects to references to reflect changes in the wxWindows API.
 170
 171 Other assorted fixes and additions.
 172
 173
 174
 175
 176 What's new in 0.4.2
 177 -------------------
 178
 179 wxPython on wxGTK works!!!  Both dynamic and static on Linux and
 180 static on Solaris have been tested.  Many thanks go to Harm
 181 <H.v.d.Heijden@phys.tue.nl> for his astute detective work on tracking
 182 down a nasty DECREF bug.  Okay so I have to confess that it was just a
 183 DSM (Dumb Stupid Mistake) on my part but it was nasty none the less
 184 because the behavior was so different on different platforms.
 185
 186
 187 The dynamicly loaded module on Solaris is still segfaulting, so it
 188 must have been a different issue all along...
 189
 190
 191
 192 What's New in 0.4
 193 -----------------
 194
 195 1. Worked on wxGTK compatibility.  It is partially working.  On a
 196 Solaris/Sparc box wxPython is working but only when it is statically
 197 linked with the Python interpreter.  When built as a dyamically loaded
 198 extension module, things start acting weirdly and it soon seg-faults.
 199 And on Linux both the statically linked and the dynamically linked
 200 version segfault shortly after starting up.
 201
 202 2. Added Toolbar, StatusBar and SplitterWindow classes.
 203
 204 3. Varioius bug fixes, enhancements, etc.
 205
 206
 207
 208 Build Instructions
 209 ------------------
 210 I used SWIG (http://www.swig.org) to create the source code for the
 211 extension module.  This enabled me to only have to deal with a small
 212 amount of code and only have to bother with the exceptional issues.
 213 SWIG takes care of the rest and generates all the repetative code for
 214 me.  You don't need SWIG to build the extension module as all the
 215 generated C++ code is included under the src directory.
 216
 217 I added a few minor features to SWIG to control some of the code
 218 generation.  If you want to playaround with this the patches are in
 219 wxPython/SWIG.patches and they should be applied to the 1.1p5 version
 220 of SWIG.  These new patches are documented at
 221 http://starship.skyport.net/crew/robind/python/#swig, and they should
 222 also end up in the 1.2 version of SWIG.
 223
 224 wxPython is organized as a Python package.  This means that the
 225 directory containing the results of the build process should be a
 226 subdirectory of a directory on the PYTHONPATH.  (And preferably should
 227 be named wxPython.)  You can control where the build process will dump
 228 wxPython by setting the TARGETDIR makefile variable.  The default is
 229 $(WXWIN)/utils/wxPython, where this README.txt is located.  If you
 230 leave it here then you should add $(WXWIN)/utils to your PYTHONPATH.
 231 However, you may prefer to use something that is already on your
 232 PYTHONPATH, such as the site-packages directory on Unix systems.
 233
 234
 235 Win32
 236 -----
 237
 238 1. Build wxWindows with wxUSE_RESOURCE_LOADING_IN_MSW set to 1 in
 239 include/wx/msw/setup.h so icons can be loaded dynamically.  While
 240 there, make sure wxUSE_OWNER_DRAWN is also set to 1.
 241
 242 2. Change into the $(WXWIN)/utils/wxPython/src directory.
 243
 244 3. Edit makefile.vc and specify where your python installation is at.
 245 You may also want to fiddle with the TARGETDIR variable as described
 246 above.
 247
 248 4. Run nmake -f makefile.vc
 249
 250 5. If it builds successfully, congratulations!  Move on to the next
 251 step.  If not then you can try mailing me for help.  Also, I will
 252 always have a pre-built win32 version of this extension module at
 253 http://starship.skyport.net/crew/robind/python.
 254
 255 6. Change to the $(WXWIN)/utils/wxPython/tests directory.
 256
 257 7. Try executing the test programs.  Note that some of these print
 258 diagnositc or test info to standard output, so they will require the
 259 console version of python.  For example:
 260
 261     python test1.py
 262
 263 To run them without requiring a console, you can use the pythonw.exe
 264 version of Python either from the command line or from a shortcut.
 265
 266
 267
 268 Unix
 269 ----
 270
 271 1. Change into the $(WXWIN)/utils/wxPython/src directory.
 272
 273 2. Edit Setup.in and ensure that the flags, directories, and toolkit
 274 options are correct.  See the above commentary about TARGETDIR.  There
 275 are a few sample Setup.in.[platform] files provided.
 276
 277 [I've written a Setup which should work in almost all Unix systems,
 278  so that the steps 1 and 2 don't have to be done. Robert Roebling. ]
 279
 280 3. Run this command to generate a makefile:
 281
 282     make -f Makefile.pre.in boot
 283
 284 4. Run these commands to build and then install the wxPython extension
 285 module:
 286
 287     make
 288
 289 4b. Log in as root. [Robert Roebling]
 290
 291     make install
 292
 293 4c. Log out from root. [Robert Roebling]
 294
 295
 296 5. Change to the $(WXWIN)/utils/wxPython/tests directory.
 297
 298 6. Try executing the test programs.  For example:
 299
 300     python test1.py
 301
 302
 303 ------------------------
 304 10/20/1998
 305
 306 Robin Dunn
 307 robin@alldunn.com
 308
 309
 310