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 <a href="#id1" name="id2"><span class="problematic" id="id2">*</span></a>&quot;, the
 178 old wxNames, and the old style of event binding it will still work
 179 just fine.</p>
 180 <div class="system-message" id="id1">
 181 <p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt>MigrationGuide.txt</tt>, line 189); <em><a href="#id2">backlink</a></em></p>
 182 Inline emphasis start-string without end-string.</div>
 183 </div>
 184 <div class="section" id="new-wx-dc-methods">
 185 <h1><a name="new-wx-dc-methods">New wx.DC Methods</a></h1>
 186 <p>Many of the Draw methods of wx.DC have alternate forms in C++ that take
 187 wxPoint or wxSize parameters (let's call these <em>Type A</em>) instead of
 188 the individual x, y, width, height, etc. parameters (and we'll call
 189 these <em>Type B</em>).  In the rest of the library I normally made the <em>Type
 190 A</em> forms of the methods be the default method with the &quot;normal&quot; name,
 191 and had renamed the <em>Type B</em> forms of the methods to some similar
 192 name.  For example in wx.Window we have these Python methods:</p>
 193 <pre class="literal-block">
 194 SetSize(size)               # Type A
 195 SetSizeWH(width, height)    # Type B
 196 </pre>
 197 <p>For various reasons the new <em>Type A</em> methods in wx.DC were never added
 198 and the existing <em>Type B</em> methods were never renamed.  Now that lots
 199 of other things are also changing in wxPython it has been decided that
 200 it is a good time to also do the method renaming in wx.DC too in order
 201 to be consistent with the rest of the library.  The methods in wx.DC
 202 that are affected are listed here:</p>
 203 <pre class="literal-block">
 204 FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
 205 FloodFill(point, colour,  style = wx.FLOOD_SURFACE)
 206
 207 GetPixelXY(x, y)
 208 GetPixel(point)
 209
 210 DrawLineXY(x1, y1, x2, y2)
 211 DrawLine(point1, point2)
 212
 213 CrossHairXY(x, y)
 214 CrossHair(point)
 215
 216 DrawArcXY(x1, y1, x2, y2, xc, yc)
 217 DrawArc(point1, point2, center)
 218
 219 DrawCheckMarkXY(x, y, width, height)
 220 DrawCheckMark(rect)
 221
 222 DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
 223 DrawEllipticArc(point, size, start_angle, end_angle)
 224
 225 DrawPointXY(x, y)
 226 DrawPoint(point)
 227
 228 DrawRectangleXY(x, y, width, height)
 229 DrawRectangle(point, size)
 230 DrawRectangleRect(rect)
 231
 232 DrawRoundedRectangleXY(x, y, width, height, radius)
 233 DrawRoundedRectangle(point, size, radius)
 234 DrawRoundedRectangleRect(rect, radius)
 235
 236 DrawCircleXY(x, y, radius)
 237 DrawCircle(point, radius)
 238
 239 DrawEllipseXY(x, y, width, height)
 240 DrawEllipse(point, size)
 241 DrawEllipseRect(rect)
 242
 243 DrawIconXY(icon, x, y)
 244 DrawIcon(icon, point)
 245
 246 DrawBitmapXY(bmp, x, y, useMask = FALSE)
 247 DrawBitmap(bmp, point, useMask = FALSE)
 248
 249 DrawTextXY(text, x, y)
 250 DrawText(text, point)
 251
 252 DrawRotatedTextXY(text, x, y, angle)
 253 DrawRotatedText(text, point, angle)
 254
 255
 256 BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
 257        rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
 258 Blit(destPt, size, sourceDC, srcPt,
 259      rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
 260
 261 SetClippingRegionXY SetClippingRegion(x, y, width, height)
 262 SetClippingRegion(point, size)
 263 SetClippingRect(rect)
 264 SetClippingRegionAsRegion(region);
 265 </pre>
 266 <p>If you have code that draws on a DC you <strong>will</strong> get errors because of
 267 these changes, but it should be easy to fix the code.  You can either
 268 change the name of the <em>Type B</em> method called to the names shown
 269 above, or just add parentheses around the parameters as needed to turn
 270 them into tuples and let the SWIG typemaps turn them into the wx.Point
 271 or wx.Size object that is expected.  Then you will be calling the new
 272 <em>Type A</em> method.  For example, if you had this code before:</p>
 273 <pre class="literal-block">
 274 dc.DrawRectangle(x, y, width, height)
 275 </pre>
 276 <p>You could either continue to use the <em>Type B</em> method bu changing the
 277 name to DrawRectabgleXY, or just change it to the new <em>Type A</em> by
 278 adding some parentheses like this:</p>
 279 <pre class="literal-block">
 280 dc.DrawRectangle((x, y), (width, height))
 281 </pre>
 282 <p>Or if you were already using a point and size:</p>
 283 <pre class="literal-block">
 284 dc.DrawRectangle(p.x, p.y, s.width, s.height)
 285 </pre>
 286 <p>Then you can just simplify it like this:</p>
 287 <pre class="literal-block">
 288 dc.DrawRectangle(p, s)
 289 </pre>
 290 </div>
 291 <div class="section" id="building-extending-and-embedding-wxpython">
 292 <h1><a name="building-extending-and-embedding-wxpython">Building, Extending and Embedding wxPython</a></h1>
 293 <p>wxPython's setup.py script now expects to use existing libraries for
 294 the contribs (gizmos, stc, xrc, etc.) rather than building local
 295 copies of them.  If you build your own copies of wxPython please be
 296 aware that you now need to also build the ogl, stc, xrc, and gizmos
 297 libraries in addition to the main wx lib.  [[TODO: update the
 298 BUILD.*.txt files too!]]</p>
 299 <p>The wxPython.h and other header files are now in
 300 .../wxPython/include/wx/wxPython instead of in wxPython/src.  You should
 301 include it via the &quot;wx/wxPython/wxPython.h&quot; path and add
 302 .../wxPython/include to your list of include paths.  [[TODO:  Install
 303 these headers on Linux...]]</p>
 304 <p>You no longer need to call wxClassInfo::CleanUpClasses() and
 305 wxClassInfo::InitializeClasses() in your extensions or when embedding
 306 wxPython.</p>
 307 </div>
 308 <div class="section" id="two-or-three-phase-create">
 309 <h1><a name="two-or-three-phase-create">Two (or Three!) Phase Create</a></h1>
 310 <p>If you use the Precreate/Create method of instantiating a window, (for
 311 example, to set an extended style flag, or for XRC handlers) then
 312 there is now a new method named PostCreate to help with transplanting
 313 the brain of the prewindow instance into the derived window instance.
 314 For example:</p>
 315 <pre class="literal-block">
 316 class MyDialog(wx.Dialog):
 317     def __init__(self, parent, ID, title, pos, size, style):
 318         pre = wx.PreDialog()
 319         pre.SetExtraStyle(wx.DIALOG_EX_CONTEXTHELP)
 320         pre.Create(parent, ID, title, pos, size, style)
 321         self.PostCreate(pre)
 322 </pre>
 323 </div>
 324 <div class="section" id="sizers">
 325 <h1><a name="sizers">Sizers</a></h1>
 326 <p>The hack allowing the old &quot;option&quot; keyword parameter has been
 327 removed.  If you use keyworkd args with wxSizer Add, Insert, or
 328 Prepend then you will need to use the &quot;proportion&quot; name instead of
 329 &quot;option&quot;.</p>
 330 <p>When adding a spacer to a sizer you now need to use a wxSize or a
 331 2-integer sequence instead of separate width and height parameters.</p>
 332 <p>The wxGridBagSizer class (very similar to the RowColSizer in the
 333 library) has been added to C++ and wrapped for wxPython.  It can also
 334 be used from XRC.</p>
 335 <p>You should not use AddWindow, AddSizer, AddSpacer (and similar for
 336 Insert, Prepend, and etc.) methods any longer.  Just use Add and the
 337 wrappers will figure out what to do.</p>
 338 </div>
 339 <div class="section" id="other-stuff">
 340 <h1><a name="other-stuff">Other Stuff</a></h1>
 341 <p>Instead of over a dozen separate extension modules linked together
 342 into a single extension module, the &quot;core&quot; module is now just a few
 343 extensions that are linked independently, and then merged together
 344 later into the main namespace via Python code.</p>
 345 <p>Because of the above, the &quot;internal&quot; module names have changed, but
 346 you shouldn't have been using them anyway so it shouldn't bother
 347 you. ;-)</p>
 348 <p>The wxPython.help module no longer exists and the classes therein are
 349 now part of the core module imported with wxPython.wx or the wx
 350 package.</p>
 351 <p>wxPyDefaultPosition and wxPyDefaultSize are gone.  Use the
 352 wxDefaultPosition and wxDefaultSize objects instead.</p>
 353 <p>Similarly, the wxSystemSettings backwards compatibiility aliases for
 354 GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
 355 the bit-bucket.  Use GetColour, GetFont and GetMetric instead.</p>
 356 <p>The wx.NO_FULL_REPAINT_ON_RESIZE style is now the default style for
 357 all windows.  The name still exists for compatibility, but it is set
 358 to zero.  If you want to disable the setting (so it matches the old
 359 default) then you need to use the new wx.FULL_REPAINT_ON_RESIZE style
 360 flag otherwise only the freshly exposed areas of the window will be
 361 refreshed.</p>
 362 <p>wxPyTypeCast has been removed.  Since we've had the OOR (Original
 363 Object Return) for a couple years now there should be no need to use
 364 wxPyTypeCast at all.</p>
 365 </div>
 366 </div>
 367 <hr class="footer" />
 368 <div class="footer">
 369 <a class="reference" href="MigrationGuide.txt">View document source</a>.
 370 Generated on: 2003-12-18 18:35 UTC.
 371 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.
 372 </div>
 373 </body>
 374 </html>