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=wx.ID_EXIT)
 104 </pre>
 105 <p>The wx.Menu methods that add items to a wx.Menu have been modified
 106 such that they return a reference to the wx.MenuItem that was created.
 107 Additionally menu items and toolbar items have been modified to
 108 automatically generate a new ID if -1 is given, similar to using -1
 109 with window classess.  This means that you can create menu or toolbar
 110 items and event bindings without having to predefine a unique menu ID,
 111 although you still can use IDs just like before if you want.  For
 112 example, these are all equivallent other than ID values:</p>
 113 <pre class="literal-block">
 114 1.
 115   item = menu.Append(-1, &quot;E&amp;xit&quot;, &quot;Terminate the App&quot;)
 116   self.Bind(wx.EVT_MENU, self.OnExit, item)
 117
 118 2.
 119   item = menu.Append(wx.ID_EXIT, &quot;E&amp;xit&quot;, &quot;Terminate the App&quot;)
 120   self.Bind(wx.EVT_MENU, self.OnExit, item)
 121
 122 3.
 123   menu.Append(wx.ID_EXIT, &quot;E&amp;xit&quot;, &quot;Terminate the App&quot;)
 124   self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT)
 125 </pre>
 126 <p>If you create your own custom event types and EVT_* functions, and you
 127 want to be able to use them with the Bind method above then you should
 128 change your EVT_* to be an instance of wxPyEventBinder instead of a
 129 function.  If you used to have something like this:</p>
 130 <pre class="literal-block">
 131 myCustomEventType = wxNewEventType()
 132 def EVT_MY_CUSTOM_EVENT(win, id, func):
 133     win.Connect(id, -1, myCustomEventType, func)
 134 </pre>
 135 <p>Change it like so:</p>
 136 <pre class="literal-block">
 137 myCustomEventType = wx.NewEventType()
 138 EVT_MY_CUSTOM_EVENT = wx.PyEventBinder(myCustomEventType, 1)
 139 </pre>
 140 <p>The second parameter is an integer in [0, 1, 2] that specifies the
 141 number of IDs that are needed to be passed to Connect.</p>
 142 </div>
 143 <div class="section" id="the-wx-namespace">
 144 <h1><a name="the-wx-namespace">The wx Namespace</a></h1>
 145 <p>The second phase of the wx Namespace Transition has begun.  That means
 146 that the real names of the classes and other symbols do not have the
 147 'wx' prefix and the modules are located in a Python package named
 148 wx.  There is still a Python package named wxPython with modules
 149 that have the names with the wx prefix for backwards compatibility.
 150 Instead of dynamically changing the names at module load time like in
 151 2.4, the compatibility modules are generated at build time and contain
 152 assignment statements like this:</p>
 153 <pre class="literal-block">
 154 wxWindow = wx.core.Window
 155 </pre>
 156 <p>Don't let the &quot;core&quot; in the name bother you.  That and some other
 157 modules are implementation details, and everything that was in the
 158 wxPython.wx module before will still be in the wx package namespace
 159 after this change.  So from your code you would use it as wx.Window.</p>
 160 <p>A few notes about how all of this was accomplished might be
 161 interesting...  SWIG is now run twice for each module that it is
 162 generating code for.  The first time it outputs an XML representaion
 163 of the parse tree, which can be up to 20MB and 300K lines in size!
 164 That XML is then run through a little Python script that creates a
 165 file full of SWIG %rename directives that take the wx off of the
 166 names, and also generates the Python compatibility file described
 167 above that puts the wx back on the names.  SWIG is then run a second
 168 time to generate the C++ code to implement the extension module, and
 169 uses the %rename directives that were generated in the first step.</p>
 170 <p>Not every name is handled correctly (but the bulk of them are) and so
 171 some work has to be done by hand, especially for the reverse-renamers.
 172 So expect a few flaws here and there until everything gets sorted out.</p>
 173 <p>In summary, the wx package and names without the &quot;wx&quot; prefix are now
 174 the official form of the wxPython classes.  For example:</p>
 175 <pre class="literal-block">
 176 import wx
 177
 178 class MyFrame(wx.Frame):
 179     def __init__(self, parent, title):
 180         wx.Frame.__init__(self, parent, -1, title)
 181         p = wx.Panel(self, -1)
 182         b = wx.Button(p, -1, &quot;Do It&quot;, (10,10))
 183         self.Bind(wx.EVT_BUTTON, self.JustDoIt, b)
 184
 185     def JustDoIt(self, evt):
 186         print &quot;It's done!&quot;
 187
 188 app = wx.PySimpleApp()
 189 f = MyFrame(None, &quot;What's up?&quot;)
 190 f.Show()
 191 app.MainLoop()
 192 </pre>
 193 <p>You shouldn't need to migrate all your modules over to use the new
 194 package and names right away as there are modules in place that try to
 195 provide as much backwards compatibility of the names as possible.  If
 196 you rewrote the above sample using &quot;from wxPython.wx import * &quot;, the
 197 old wxNames, and the old style of event binding it will still work
 198 just fine.</p>
 199 </div>
 200 <div class="section" id="new-wx-dc-methods">
 201 <h1><a name="new-wx-dc-methods">New wx.DC Methods</a></h1>
 202 <p>Many of the Draw methods of wx.DC have alternate forms in C++ that take
 203 wxPoint or wxSize parameters (let's call these <em>Type A</em>) instead of
 204 the individual x, y, width, height, etc. parameters (and we'll call
 205 these <em>Type B</em>).  In the rest of the library I normally made the <em>Type
 206 A</em> forms of the methods be the default method with the &quot;normal&quot; name,
 207 and had renamed the <em>Type B</em> forms of the methods to some similar
 208 name.  For example in wx.Window we have these Python methods:</p>
 209 <pre class="literal-block">
 210 SetSize(size)               # Type A
 211 SetSizeWH(width, height)    # Type B
 212 </pre>
 213 <p>For various reasons the new <em>Type A</em> methods in wx.DC were never added
 214 and the existing <em>Type B</em> methods were never renamed.  Now that lots
 215 of other things are also changing in wxPython it has been decided that
 216 it is a good time to also do the method renaming in wx.DC too in order
 217 to be consistent with the rest of the library.  The methods in wx.DC
 218 that are affected are listed here:</p>
 219 <pre class="literal-block">
 220 FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
 221 FloodFill(point, colour,  style = wx.FLOOD_SURFACE)
 222
 223 GetPixelXY(x, y)
 224 GetPixel(point)
 225
 226 DrawLineXY(x1, y1, x2, y2)
 227 DrawLine(point1, point2)
 228
 229 CrossHairXY(x, y)
 230 CrossHair(point)
 231
 232 DrawArcXY(x1, y1, x2, y2, xc, yc)
 233 DrawArc(point1, point2, center)
 234
 235 DrawCheckMarkXY(x, y, width, height)
 236 DrawCheckMark(rect)
 237
 238 DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
 239 DrawEllipticArc(point, size, start_angle, end_angle)
 240
 241 DrawPointXY(x, y)
 242 DrawPoint(point)
 243
 244 DrawRectangleXY(x, y, width, height)
 245 DrawRectangle(point, size)
 246 DrawRectangleRect(rect)
 247
 248 DrawRoundedRectangleXY(x, y, width, height, radius)
 249 DrawRoundedRectangle(point, size, radius)
 250 DrawRoundedRectangleRect(rect, radius)
 251
 252 DrawCircleXY(x, y, radius)
 253 DrawCircle(point, radius)
 254
 255 DrawEllipseXY(x, y, width, height)
 256 DrawEllipse(point, size)
 257 DrawEllipseRect(rect)
 258
 259 DrawIconXY(icon, x, y)
 260 DrawIcon(icon, point)
 261
 262 DrawBitmapXY(bmp, x, y, useMask = FALSE)
 263 DrawBitmap(bmp, point, useMask = FALSE)
 264
 265 DrawTextXY(text, x, y)
 266 DrawText(text, point)
 267
 268 DrawRotatedTextXY(text, x, y, angle)
 269 DrawRotatedText(text, point, angle)
 270
 271
 272 BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
 273        rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
 274 Blit(destPt, size, sourceDC, srcPt,
 275      rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
 276
 277 SetClippingRegionXY(x, y, width, height)
 278 SetClippingRegion(point, size)
 279 SetClippingRect(rect)
 280 SetClippingRegionAsRegion(region);
 281 </pre>
 282 <p>If you have code that draws on a DC and you are using the new wx
 283 namespace then you <strong>will</strong> get errors because of these changes, but
 284 it should be easy to fix the code.  You can either change the name of
 285 the <em>Type B</em> method called to the names shown above, or just add
 286 parentheses around the parameters as needed to turn them into tuples
 287 and let the SWIG typemaps turn them into the wx.Point or wx.Size
 288 object that is expected.  Then you will be calling the new <em>Type A</em>
 289 method.  For example, if you had this code before:</p>
 290 <pre class="literal-block">
 291 dc.DrawRectangle(x, y, width, height)
 292 </pre>
 293 <p>You could either continue to use the <em>Type B</em> method bu changing the
 294 name to DrawRectabgleXY, or just change it to the new <em>Type A</em> by
 295 adding some parentheses like this:</p>
 296 <pre class="literal-block">
 297 dc.DrawRectangle((x, y), (width, height))
 298 </pre>
 299 <p>Or if you were already using a point and size:</p>
 300 <pre class="literal-block">
 301 dc.DrawRectangle(p.x, p.y, s.width, s.height)
 302 </pre>
 303 <p>Then you can just simplify it like this:</p>
 304 <pre class="literal-block">
 305 dc.DrawRectangle(p, s)
 306 </pre>
 307 <p>Now before you start yelling and screaming at me for breaking all your
 308 code, take note that I said above &quot;...using the new wx namespace...&quot;
 309 That's because if you are still importing from wxPython.wx then there
 310 are some classes defined there with Draw and etc. methods that have
 311 2.4 compatible signatures.  However if/when the old wxPython.wx
 312 namespace is removed then these classes will be removed too so you
 313 should plan on migrating to the new namespace and new DC Draw methods
 314 before that time.</p>
 315 </div>
 316 <div class="section" id="building-extending-and-embedding-wxpython">
 317 <h1><a name="building-extending-and-embedding-wxpython">Building, Extending and Embedding wxPython</a></h1>
 318 <p>wxPython's setup.py script now expects to use existing libraries for
 319 the contribs (gizmos, stc, xrc, etc.) rather than building local
 320 copies of them.  If you build your own copies of wxPython please be
 321 aware that you now need to also build the ogl, stc, xrc, and gizmos
 322 libraries in addition to the main wx lib.  [[TODO: update the
 323 BUILD.*.txt files too!]]</p>
 324 <p>The wxPython.h and other header files are now in
 325 .../wxPython/include/wx/wxPython instead of in wxPython/src.  You should
 326 include it via the &quot;wx/wxPython/wxPython.h&quot; path and add
 327 .../wxPython/include to your list of include paths.  [[TODO:  Install
 328 these headers on Linux...]]</p>
 329 <p>You no longer need to call wxClassInfo::CleanUpClasses() and
 330 wxClassInfo::InitializeClasses() in your extensions or when embedding
 331 wxPython.</p>
 332 </div>
 333 <div class="section" id="two-or-three-phase-create">
 334 <h1><a name="two-or-three-phase-create">Two (or Three!) Phase Create</a></h1>
 335 <p>If you use the Precreate/Create method of instantiating a window, (for
 336 example, to set an extended style flag, or for XRC handlers) then
 337 there is now a new method named PostCreate to help with transplanting
 338 the brain of the prewindow instance into the derived window instance.
 339 For example:</p>
 340 <pre class="literal-block">
 341 class MyDialog(wx.Dialog):
 342     def __init__(self, parent, ID, title, pos, size, style):
 343         pre = wx.PreDialog()
 344         pre.SetExtraStyle(wx.DIALOG_EX_CONTEXTHELP)
 345         pre.Create(parent, ID, title, pos, size, style)
 346         self.PostCreate(pre)
 347 </pre>
 348 </div>
 349 <div class="section" id="sizers">
 350 <h1><a name="sizers">Sizers</a></h1>
 351 <p>The hack allowing the old &quot;option&quot; keyword parameter has been removed.
 352 If you use keyworkd args with wxSizer Add, Insert, or Prepend methods
 353 then you will need to use the &quot;proportion&quot; name instead of &quot;option&quot;.</p>
 354 <p>When adding a spacer to a sizer you now need to use a wxSize or a
 355 2-integer sequence instead of separate width and height parameters.</p>
 356 <p>The wxGridBagSizer class (very similar to the RowColSizer in the
 357 library) has been added to C++ and wrapped for wxPython.  It can also
 358 be used from XRC.</p>
 359 <p>You should not use AddWindow, AddSizer, AddSpacer (and similar for
 360 Insert, Prepend, and etc.) methods any longer.  Just use Add and the
 361 wrappers will figure out what to do.</p>
 362 </div>
 363 <div class="section" id="other-stuff">
 364 <h1><a name="other-stuff">Other Stuff</a></h1>
 365 <p>Instead of over a dozen separate extension modules linked together
 366 into a single extension module, the &quot;core&quot; module is now just a few
 367 extensions that are linked independently, and then merged together
 368 later into the main namespace via Python code.</p>
 369 <p>Because of the above and also because of the way the new SWIG works,
 370 the &quot;internal&quot; module names have changed, but you shouldn't have been
 371 using them anyway so it shouldn't bother you. ;-)</p>
 372 <p>The help module no longer exists and the classes therein are now part
 373 of the core module imported with wxPython.wx or the wx package.</p>
 374 <p>wxPyDefaultPosition and wxPyDefaultSize are gone.  Use the
 375 wxDefaultPosition and wxDefaultSize objects instead.</p>
 376 <p>Similarly, the wxSystemSettings backwards compatibiility aliases for
 377 GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
 378 the bit-bucket.  Use GetColour, GetFont and GetMetric instead.</p>
 379 <p>The wx.NO_FULL_REPAINT_ON_RESIZE style is now the default style for
 380 all windows.  The name still exists for compatibility, but it is set
 381 to zero.  If you want to disable the setting (so it matches the old
 382 default) then you need to use the new wx.FULL_REPAINT_ON_RESIZE style
 383 flag otherwise only the freshly exposed areas of the window will be
 384 refreshed.</p>
 385 <p>wxPyTypeCast has been removed.  Since we've had the OOR (Original
 386 Object Return) for a couple years now there should be no need to use
 387 wxPyTypeCast at all.</p>
 388 <p>If you use the old wxPython package and wxPython.wx namespace then
 389 there are compatibility aliases for much of the above items.</p>
 390 <p>The wxWave class has been renamed to wxSound, and now has a slightly
 391 different API.</p>
 392 </div>
 393 </div>
 394 <hr class="footer" />
 395 <div class="footer">
 396 Generated on: 2004-02-27 00:27 UTC.
 397 </div>
 398 </body>
 399 </html>