wxPython/docs/MigrationGuide.html

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   6 <meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
   7 <title>wxPython 2.5 Migration Guide</title>
   8 <link rel="stylesheet" href="default.css" type="text/css" />
   9 </head>
  10 <body>
  11 <div class="document" id="wxpython-2-5-migration-guide">
  12 <h1 class="title">wxPython 2.5 Migration Guide</h1>
  13 <p>This document will help explain some of the major changes in wxPython
  14 2.5 and let you know what you need to do to adapt your programs to
  15 those changes.  Be sure to also check in the CHANGES.txt file like
  16 usual to see info about the not so major changes and other things that
  17 have been added to wxPython.</p>
  18 <div class="section" id="module-initialization">
  19 <h1><a name="module-initialization">Module Initialization</a></h1>
  20 <p>The import-startup-bootstrap process employed by wxPython was changed
  21 such that wxWindows and the underlying gui toolkit are <strong>not</strong>
  22 initialized until the wx.App object is created (but before wx.App.OnInit
  23 is called.)  This was required because of some changes that were made
  24 to the C++ wxApp class.</p>
  25 <p>There are both benefits and potential problems with this change.  The
  26 benefits are that you can import wxPython without requiring access to
  27 a GUI (for checking version numbers, etc.) and that in a
  28 multi-threaded environment the thread that creates the app object will
  29 now be the GUI thread instead of the one that imports wxPython.  Some
  30 potential problems are that the C++ side of the &quot;stock-objects&quot;
  31 (wx.BLUE_PEN, wx.TheColourDatabase, etc.) are not initialized until
  32 the wx.App object is created, so you should not use them until after
  33 you have created your wx.App object.  If you do then an exception will
  34 be raised telling you that the C++ object has not bene initialized
  35 yet.</p>
  36 <p>Also, you will probably not be able to do any kind of GUI or bitmap
  37 operation unless you first have created an app object, (even on
  38 Windows where most anything was possible before.)</p>
  39 </div>
  40 <div class="section" id="swig-1-3">
  41 <h1><a name="swig-1-3">SWIG 1.3</a></h1>
  42 <p>wxPython is now using SWIG 1.3.x from CVS (with several of my own
  43 customizations added that I hope to get folded back into the main SWIG
  44 distribution.)  This has some far reaching ramifications:</p>
  45 <blockquote>
  46 <p>All classes derive from object and so all are now &quot;new-style
  47 classes&quot;</p>
  48 <p>Public data members of the C++ classes are wrapped as Python
  49 properties using property() instead of using __getattr__/__setattr__
  50 like before.  Normally you shouldn't notice any difference, but if
  51 you were previously doing something with __getattr__/__setattr__
  52 in derived classes then you may have to adjust things.</p>
  53 <p>Static C++ methods are wrapped using the staticmethod()
  54 feature of Python and so are accessible as ClassName.MethodName
  55 as expected.  They are still available as top level functions
  56 ClassName_MethodName as before.</p>
  57 <p>The relationship between the wxFoo and wxFooPtr classes have
  58 changed for the better.  Specifically, all instances that you see
  59 will be wxFoo even if they are created internally using wxFooPtr,
  60 because wxFooPtr.__init__ will change the instance's __class__ as
  61 part of the initialization.  If you have any code that checks
  62 class type using something like isinstance(obj, wxFooPtr) you will
  63 need to change it to isinstance(obj, wxFoo).</p>
  64 </blockquote>
  65 </div>
  66 <div class="section" id="binding-events">
  67 <h1><a name="binding-events">Binding Events</a></h1>
  68 <p>All of the EVT_* functions are now instances of the wx.PyEventBinder
  69 class.  They have a __call__ method so they can still be used as
  70 functions like before, but making them instances adds some
  71 flexibility.</p>
  72 <p>wx.EvtHandler (the base class for wx.Window) now has a Bind method that
  73 makes binding events to windows a little easier.  Here is its
  74 definition and docstring:</p>
  75 <pre class="literal-block">
  76 def Bind(self, event, handler, source=None, id=wxID_ANY, id2=wxID_ANY):
  77     &quot;&quot;&quot;
  78     Bind an event to an event handler.
  79
  80       event     One of the EVT_* objects that specifies the
  81                 type of event to bind.
  82
  83       handler   A callable object to be invoked when the event
  84                 is delivered to self.  Pass None to disconnect an
  85                 event handler.
  86
  87       source    Sometimes the event originates from a different window
  88                 than self, but you still want to catch it in self.  (For
  89                 example, a button event delivered to a frame.)  By
  90                 passing the source of the event, the event handling
  91                 system is able to differentiate between the same event
  92                 type from different controls.
  93
  94       id,id2    Used for menu IDs or for event types that require a
  95                 range of IDs
  96
  97     &quot;&quot;&quot;
  98 </pre>
  99 <p>Some examples of its use:</p>
 100 <pre class="literal-block">
 101 self.Bind(wx.EVT_SIZE,   self.OnSize)
 102 self.Bind(wx.EVT_BUTTON, self.OnButtonClick, theButton)
 103 self.Bind(wx.EVT_MENU,   self.OnExit, id=ID_EXIT)
 104 </pre>
 105 <p>I hope to be able to remove the need for using IDs even for menu
 106 events too...</p>
 107 <p>If you create your own custom event types and EVT_* functions, and you
 108 want to be able to use them with the Bind method above then you should
 109 change your EVT_* to be an instance of wxPyEventBinder instead of a
 110 function.  If you used to have something like this:</p>
 111 <pre class="literal-block">
 112 myCustomEventType = wxNewEventType()
 113 def EVT_MY_CUSTOM_EVENT(win, id, func):
 114     win.Connect(id, -1, myCustomEventType, func)
 115 </pre>
 116 <p>Change it like so:</p>
 117 <pre class="literal-block">
 118 myCustomEventType = wx.NewEventType()
 119 EVT_MY_CUSTOM_EVENT = wx.PyEventBinder(myCustomEventType, 1)
 120 </pre>
 121 <p>The second parameter is an integer in [0, 1, 2] that specifies the
 122 number of IDs that are needed to be passed to Connect.</p>
 123 </div>
 124 <div class="section" id="the-wx-namespace">
 125 <h1><a name="the-wx-namespace">The wx Namespace</a></h1>
 126 <p>The second phase of the wx Namespace Transition has begun.  That means
 127 that the real names of the classes and other symbols do not have the
 128 'wx' prefix and the modules are located in a Python package named
 129 wx.  There is still a Python package named wxPython with modules
 130 that have the names with the wx prefix for backwards compatibility.
 131 Instead of dynamically changing the names at module load time like in
 132 2.4, the compatibility modules are generated at build time and contain
 133 assignment statements like this:</p>
 134 <pre class="literal-block">
 135 wxWindow = wx.core.Window
 136 </pre>
 137 <p>Don't let the &quot;core&quot; in the name bother you.  That and some other
 138 modules are implementation details, and everything that was in the
 139 wxPython.wx module before will still be in the wx package namespace
 140 after this change.  So from your code you would use it as wx.Window.</p>
 141 <p>A few notes about how all of this was accomplished might be
 142 interesting...  SWIG is now run twice for each module that it is
 143 generating code for.  The first time it outputs an XML representaion
 144 of the parse tree, which can be up to 20MB and 300K lines in size!
 145 That XML is then run through a little Python script that creates a
 146 file full of SWIG %rename directives that take the wx off of the
 147 names, and also generates the Python compatibility file described
 148 above that puts the wx back on the names.  SWIG is then run a second
 149 time to generate the C++ code to implement the extension module, and
 150 uses the %rename directives that were generated in the first step.</p>
 151 <p>Not every name is handled correctly (but the bulk of them are) and so
 152 some work has to be done by hand, especially for the reverse-renamers.
 153 So expect a few flaws here and there until everything gets sorted out.</p>
 154 <p>In summary, the wx package and names without the &quot;wx&quot; prefix are now
 155 the official form of the wxPython classes.  For example:</p>
 156 <pre class="literal-block">
 157 import wx
 158
 159 class MyFrame(wx.Frame):
 160     def __init__(self, parent, title):
 161         wx.Frame.__init__(self, parent, -1, title)
 162         p = wx.Panel(self, -1)
 163         b = wx.Button(p, -1, &quot;Do It&quot;, (10,10))
 164         self.Bind(wx.EVT_BUTTON, self.JustDoIt, b)
 165
 166     def JustDoIt(self, evt):
 167         print &quot;It's done!&quot;
 168
 169 app = wx.PySimpleApp()
 170 f = MyFrame(None, &quot;What's up?&quot;)
 171 f.Show()
 172 app.MainLoop()
 173 </pre>
 174 <p>You shouldn't need to migrate all your modules over to use the new
 175 package and names right away as there are modules in place that try to
 176 provide as much backwards compatibility of the names as possible.  If
 177 you rewrote the above sample using &quot;from wxPython.wx import * &quot;, the
 178 old wxNames, and the old style of event binding it will still work
 179 just fine.</p>
 180 </div>
 181 <div class="section" id="new-wx-dc-methods">
 182 <h1><a name="new-wx-dc-methods">New wx.DC Methods</a></h1>
 183 <p>Many of the Draw methods of wx.DC have alternate forms in C++ that take
 184 wxPoint or wxSize parameters (let's call these <em>Type A</em>) instead of
 185 the individual x, y, width, height, etc. parameters (and we'll call
 186 these <em>Type B</em>).  In the rest of the library I normally made the <em>Type
 187 A</em> forms of the methods be the default method with the &quot;normal&quot; name,
 188 and had renamed the <em>Type B</em> forms of the methods to some similar
 189 name.  For example in wx.Window we have these Python methods:</p>
 190 <pre class="literal-block">
 191 SetSize(size)               # Type A
 192 SetSizeWH(width, height)    # Type B
 193 </pre>
 194 <p>For various reasons the new <em>Type A</em> methods in wx.DC were never added
 195 and the existing <em>Type B</em> methods were never renamed.  Now that lots
 196 of other things are also changing in wxPython it has been decided that
 197 it is a good time to also do the method renaming in wx.DC too in order
 198 to be consistent with the rest of the library.  The methods in wx.DC
 199 that are affected are listed here:</p>
 200 <pre class="literal-block">
 201 FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
 202 FloodFill(point, colour,  style = wx.FLOOD_SURFACE)
 203
 204 GetPixelXY(x, y)
 205 GetPixel(point)
 206
 207 DrawLineXY(x1, y1, x2, y2)
 208 DrawLine(point1, point2)
 209
 210 CrossHairXY(x, y)
 211 CrossHair(point)
 212
 213 DrawArcXY(x1, y1, x2, y2, xc, yc)
 214 DrawArc(point1, point2, center)
 215
 216 DrawCheckMarkXY(x, y, width, height)
 217 DrawCheckMark(rect)
 218
 219 DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
 220 DrawEllipticArc(point, size, start_angle, end_angle)
 221
 222 DrawPointXY(x, y)
 223 DrawPoint(point)
 224
 225 DrawRectangleXY(x, y, width, height)
 226 DrawRectangle(point, size)
 227 DrawRectangleRect(rect)
 228
 229 DrawRoundedRectangleXY(x, y, width, height, radius)
 230 DrawRoundedRectangle(point, size, radius)
 231 DrawRoundedRectangleRect(rect, radius)
 232
 233 DrawCircleXY(x, y, radius)
 234 DrawCircle(point, radius)
 235
 236 DrawEllipseXY(x, y, width, height)
 237 DrawEllipse(point, size)
 238 DrawEllipseRect(rect)
 239
 240 DrawIconXY(icon, x, y)
 241 DrawIcon(icon, point)
 242
 243 DrawBitmapXY(bmp, x, y, useMask = FALSE)
 244 DrawBitmap(bmp, point, useMask = FALSE)
 245
 246 DrawTextXY(text, x, y)
 247 DrawText(text, point)
 248
 249 DrawRotatedTextXY(text, x, y, angle)
 250 DrawRotatedText(text, point, angle)
 251
 252
 253 BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
 254        rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
 255 Blit(destPt, size, sourceDC, srcPt,
 256      rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
 257
 258 SetClippingRegionXY(x, y, width, height)
 259 SetClippingRegion(point, size)
 260 SetClippingRect(rect)
 261 SetClippingRegionAsRegion(region);
 262 </pre>
 263 <p>If you have code that draws on a DC and you are using the new wx
 264 namespace then you <strong>will</strong> get errors because of these changes, but
 265 it should be easy to fix the code.  You can either change the name of
 266 the <em>Type B</em> method called to the names shown above, or just add
 267 parentheses around the parameters as needed to turn them into tuples
 268 and let the SWIG typemaps turn them into the wx.Point or wx.Size
 269 object that is expected.  Then you will be calling the new <em>Type A</em>
 270 method.  For example, if you had this code before:</p>
 271 <pre class="literal-block">
 272 dc.DrawRectangle(x, y, width, height)
 273 </pre>
 274 <p>You could either continue to use the <em>Type B</em> method bu changing the
 275 name to DrawRectabgleXY, or just change it to the new <em>Type A</em> by
 276 adding some parentheses like this:</p>
 277 <pre class="literal-block">
 278 dc.DrawRectangle((x, y), (width, height))
 279 </pre>
 280 <p>Or if you were already using a point and size:</p>
 281 <pre class="literal-block">
 282 dc.DrawRectangle(p.x, p.y, s.width, s.height)
 283 </pre>
 284 <p>Then you can just simplify it like this:</p>
 285 <pre class="literal-block">
 286 dc.DrawRectangle(p, s)
 287 </pre>
 288 <p>Now before you start yelling and screaming at me for breaking all your
 289 code, take note that I said above &quot;...using the new wx namespace...&quot;
 290 That's because if you are still importing from wxPython.wx then there
 291 are some classes defined there with Draw and etc. methods that have
 292 2.4 compatible signatures.  However if/when the old wxPython.wx
 293 namespace is removed then these classes will be removed too so you
 294 should plan on migrating to the new namespace and new DC Draw methods
 295 before that time.</p>
 296 </div>
 297 <div class="section" id="building-extending-and-embedding-wxpython">
 298 <h1><a name="building-extending-and-embedding-wxpython">Building, Extending and Embedding wxPython</a></h1>
 299 <p>wxPython's setup.py script now expects to use existing libraries for
 300 the contribs (gizmos, stc, xrc, etc.) rather than building local
 301 copies of them.  If you build your own copies of wxPython please be
 302 aware that you now need to also build the ogl, stc, xrc, and gizmos
 303 libraries in addition to the main wx lib.  [[TODO: update the
 304 BUILD.*.txt files too!]]</p>
 305 <p>The wxPython.h and other header files are now in
 306 .../wxPython/include/wx/wxPython instead of in wxPython/src.  You should
 307 include it via the &quot;wx/wxPython/wxPython.h&quot; path and add
 308 .../wxPython/include to your list of include paths.  [[TODO:  Install
 309 these headers on Linux...]]</p>
 310 <p>You no longer need to call wxClassInfo::CleanUpClasses() and
 311 wxClassInfo::InitializeClasses() in your extensions or when embedding
 312 wxPython.</p>
 313 </div>
 314 <div class="section" id="two-or-three-phase-create">
 315 <h1><a name="two-or-three-phase-create">Two (or Three!) Phase Create</a></h1>
 316 <p>If you use the Precreate/Create method of instantiating a window, (for
 317 example, to set an extended style flag, or for XRC handlers) then
 318 there is now a new method named PostCreate to help with transplanting
 319 the brain of the prewindow instance into the derived window instance.
 320 For example:</p>
 321 <pre class="literal-block">
 322 class MyDialog(wx.Dialog):
 323     def __init__(self, parent, ID, title, pos, size, style):
 324         pre = wx.PreDialog()
 325         pre.SetExtraStyle(wx.DIALOG_EX_CONTEXTHELP)
 326         pre.Create(parent, ID, title, pos, size, style)
 327         self.PostCreate(pre)
 328 </pre>
 329 </div>
 330 <div class="section" id="sizers">
 331 <h1><a name="sizers">Sizers</a></h1>
 332 <p>The hack allowing the old &quot;option&quot; keyword parameter has been
 333 removed.  If you use keyworkd args with wxSizer Add, Insert, or
 334 Prepend then you will need to use the &quot;proportion&quot; name instead of
 335 &quot;option&quot;.</p>
 336 <p>When adding a spacer to a sizer you now need to use a wxSize or a
 337 2-integer sequence instead of separate width and height parameters.</p>
 338 <p>The wxGridBagSizer class (very similar to the RowColSizer in the
 339 library) has been added to C++ and wrapped for wxPython.  It can also
 340 be used from XRC.</p>
 341 <p>You should not use AddWindow, AddSizer, AddSpacer (and similar for
 342 Insert, Prepend, and etc.) methods any longer.  Just use Add and the
 343 wrappers will figure out what to do.</p>
 344 </div>
 345 <div class="section" id="other-stuff">
 346 <h1><a name="other-stuff">Other Stuff</a></h1>
 347 <p>Instead of over a dozen separate extension modules linked together
 348 into a single extension module, the &quot;core&quot; module is now just a few
 349 extensions that are linked independently, and then merged together
 350 later into the main namespace via Python code.</p>
 351 <p>Because of the above, the &quot;internal&quot; module names have changed, but
 352 you shouldn't have been using them anyway so it shouldn't bother
 353 you. ;-)</p>
 354 <p>The wxPython.help module no longer exists and the classes therein are
 355 now part of the core module imported with wxPython.wx or the wx
 356 package.</p>
 357 <p>wxPyDefaultPosition and wxPyDefaultSize are gone.  Use the
 358 wxDefaultPosition and wxDefaultSize objects instead.</p>
 359 <p>Similarly, the wxSystemSettings backwards compatibiility aliases for
 360 GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
 361 the bit-bucket.  Use GetColour, GetFont and GetMetric instead.</p>
 362 <p>The wx.NO_FULL_REPAINT_ON_RESIZE style is now the default style for
 363 all windows.  The name still exists for compatibility, but it is set
 364 to zero.  If you want to disable the setting (so it matches the old
 365 default) then you need to use the new wx.FULL_REPAINT_ON_RESIZE style
 366 flag otherwise only the freshly exposed areas of the window will be
 367 refreshed.</p>
 368 <p>wxPyTypeCast has been removed.  Since we've had the OOR (Original
 369 Object Return) for a couple years now there should be no need to use
 370 wxPyTypeCast at all.</p>
 371 </div>
 372 </div>
 373 <hr class="footer" />
 374 <div class="footer">
 375 <a class="reference" href="MigrationGuide.txt">View document source</a>.
 376 Generated on: 2004-01-13 20:47 UTC.
 377 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 378 </div>
 379 </body>
 380 </html>