1 ============================
2 wxPython 2.5 Migration Guide
3 ============================
5 This document will help explain some of the major changes in wxPython
6 2.5 and let you know what you need to do to adapt your programs to
7 those changes. Be sure to also check in the CHANGES.txt file like
8 usual to see info about the not so major changes and other things that
9 have been added to wxPython.
16 The import-startup-bootstrap process employed by wxPython was changed
17 such that wxWindows and the underlying gui toolkit are **not**
18 initialized until the wx.App object is created (but before wx.App.OnInit
19 is called.) This was required because of some changes that were made
20 to the C++ wxApp class.
22 There are both benefits and potential problems with this change. The
23 benefits are that you can import wxPython without requiring access to
24 a GUI (for checking version numbers, etc.) and that in a
25 multi-threaded environment the thread that creates the app object will
26 now be the GUI thread instead of the one that imports wxPython. Some
27 potential problems are that the C++ side of the "stock-objects"
28 (wx.BLUE_PEN, wx.TheColourDatabase, etc.) are not initialized until
29 the wx.App object is created, so you should not use them until after
30 you have created your wx.App object. (In fact, until I find a better
31 solution trying to use one of the stock objects before the app is
32 created will probably result in a crash.)
34 Also, you will probably not be able to do any kind of GUI or bitmap
35 operation unless you first have created an app object, (even on
36 Windows where most anything was possible before.)
43 wxPython is now using SWIG 1.3.x from CVS (with several of my own
44 customizations added that I hope to get folded back into the main SWIG
45 distribution.) This has some far reaching ramifications:
47 All classes derive from object and so all are now "new-style
50 Public data members of the C++ classes are wrapped as Python
51 properties using property() instead of using __getattr__/__setattr__
52 like before. Normally you shouldn't notice any difference, but if
53 you were previously doing something with __getattr__/__setattr__
54 in derived classes then you may have to adjust things.
56 Static C++ methods are wrapped using the staticmethod()
57 feature of Python and so are accessible as ClassName.MethodName
58 as expected. They are still available as top level functions
59 ClassName_MethodName as before.
61 The relationship between the wxFoo and wxFooPtr classes have
62 changed for the better. Specifically, all instances that you see
63 will be wxFoo even if they are created internally using wxFooPtr,
64 because wxFooPtr.__init__ will change the instance's __class__ as
65 part of the initialization. If you have any code that checks
66 class type using something like isinstance(obj, wxFooPtr) you will
67 need to change it to isinstance(obj, wxFoo).
74 All of the EVT_* functions are now instances of the wx.PyEventBinder
75 class. They have a __call__ method so they can still be used as
76 functions like before, but making them instances adds some
79 wx.EvtHandler (the base class for wx.Window) now has a Bind method that
80 makes binding events to windows a little easier. Here is its
81 definition and docstring::
83 def Bind(self, event, handler, source=None, id=wxID_ANY, id2=wxID_ANY):
85 Bind an event to an event handler.
87 event One of the EVT_* objects that specifies the
88 type of event to bind.
90 handler A callable object to be invoked when the event
91 is delivered to self. Pass None to disconnect an
94 source Sometimes the event originates from a different window
95 than self, but you still want to catch it in self. (For
96 example, a button event delivered to a frame.) By
97 passing the source of the event, the event handling
98 system is able to differentiate between the same event
99 type from different controls.
101 id,id2 Used for menu IDs or for event types that require a
106 Some examples of its use::
108 self.Bind(wx.EVT_SIZE, self.OnSize)
109 self.Bind(wx.EVT_BUTTON, self.OnButtonClick, theButton)
110 self.Bind(wx.EVT_MENU, self.OnExit, id=ID_EXIT)
112 I hope to be able to remove the need for using IDs even for menu
115 If you create your own custom event types and EVT_* functions, and you
116 want to be able to use them with the Bind method above then you should
117 change your EVT_* to be an instance of wxPyEventBinder instead of a
118 function. If you used to have something like this::
120 myCustomEventType = wxNewEventType()
121 def EVT_MY_CUSTOM_EVENT(win, id, func):
122 win.Connect(id, -1, myCustomEventType, func)
127 myCustomEventType = wxNewEventType()
128 EVT_MY_CUSTOM_EVENT = wxPyEventBinder(myCustomEventType, 1)
130 The second parameter is an integer in [0, 1, 2] that specifies the
131 number of IDs that are needed to be passed to Connect.
138 The second phase of the wx Namespace Transition has begun. That means
139 that the real names of the classes and other symbols do not have the
140 'wx' prefix and the modules are located in a Python package named
141 wx. There is still a Python package named wxPython with modules
142 that have the names with the wx prefix for backwards compatibility.
143 Instead of dynamically changing the names at module load time like in
144 2.4, the compatibility modules are generated at build time and contain
145 assignment statements like this::
147 wxWindow = wx.core.Window
149 Don't let the "core" in the name bother you. That and some other
150 modules are implementation details, and everything that was in the
151 wxPython.wx module before will still be in the wx package namespace
152 after this change. So from your code you would use it as wx.Window.
154 A few notes about how all of this was accomplished might be
155 interesting... SWIG is now run twice for each module that it is
156 generating code for. The first time it outputs an XML representaion
157 of the parse tree, which can be up to 20MB and 300K lines in size!
158 That XML is then run through a little Python script that creates a
159 file full of SWIG %rename directives that take the wx off of the
160 names, and also generates the Python compatibility file described
161 above that puts the wx back on the names. SWIG is then run a second
162 time to generate the C++ code to implement the extension module, and
163 uses the %rename directives that were generated in the first step.
165 Not every name is handled correctly (but the bulk of them are) and so
166 some work has to be done by hand, especially for the reverse-renamers.
167 So expect a few flaws here and there until everything gets sorted out.
169 In summary, the wx package and names without the "wx" prefix are now
170 the official form of the wxPython classes. For example::
174 class MyFrame(wx.Frame):
175 def __init__(self, parent, title):
176 wx.Frame.__init__(self, parent, -1, title)
177 p = wx.Panel(self, -1)
178 b = wx.Button(p, -1, "Do It", (10,10))
179 self.Bind(wx.EVT_BUTTON, self.JustDoIt, b)
181 def JustDoIt(self, evt):
184 app = wx.PySimpleApp()
185 f = MyFrame(None, "What's up?")
189 You shouldn't need to migrate all your modules over to use the new
190 package and names right away as there are modules in place that try to
191 provide as much backwards compatibility of the names as possible. If
192 you rewrote the above sample using "from wxPython.wx import *", the
193 old wxNames, and the old style of event binding it will still work
202 Many of the Draw methods of wx.DC have alternate forms in C++ that take
203 wxPoint or wxSize parameters (let's call these *Type A*) instead of
204 the individual x, y, width, height, etc. parameters (and we'll call
205 these *Type B*). In the rest of the library I normally made the *Type
206 A* forms of the methods be the default method with the "normal" name,
207 and had renamed the *Type B* forms of the methods to some similar
208 name. For example in wx.Window we have these Python methods::
210 SetSize(size) # Type A
211 SetSizeWH(width, height) # Type B
214 For various reasons the new *Type A* methods in wx.DC were never added
215 and the existing *Type B* methods were never renamed. Now that lots
216 of other things are also changing in wxPython it has been decided that
217 it is a good time to also do the method renaming in wx.DC too in order
218 to be consistent with the rest of the library. The methods in wx.DC
219 that are affected are listed here::
221 FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
222 FloodFill(point, colour, style = wx.FLOOD_SURFACE)
227 DrawLineXY(x1, y1, x2, y2)
228 DrawLine(point1, point2)
233 DrawArcXY(x1, y1, x2, y2, xc, yc)
234 DrawArc(point1, point2, center)
236 DrawCheckMarkXY(x, y, width, height)
239 DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
240 DrawEllipticArc(point, size, start_angle, end_angle)
245 DrawRectangleXY(x, y, width, height)
246 DrawRectangle(point, size)
247 DrawRectangleRect(rect)
249 DrawRoundedRectangleXY(x, y, width, height, radius)
250 DrawRoundedRectangle(point, size, radius)
251 DrawRoundedRectangleRect(rect, radius)
253 DrawCircleXY(x, y, radius)
254 DrawCircle(point, radius)
256 DrawEllipseXY(x, y, width, height)
257 DrawEllipse(point, size)
258 DrawEllipseRect(rect)
260 DrawIconXY(icon, x, y)
261 DrawIcon(icon, point)
263 DrawBitmapXY(bmp, x, y, useMask = FALSE)
264 DrawBitmap(bmp, point, useMask = FALSE)
266 DrawTextXY(text, x, y)
267 DrawText(text, point)
269 DrawRotatedTextXY(text, x, y, angle)
270 DrawRotatedText(text, point, angle)
273 BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
274 rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
275 Blit(destPt, size, sourceDC, srcPt,
276 rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
279 If you have code that draws on a DC you **will** get errors because of
280 these changes, but it should be easy to fix the code. You can either
281 change the name of the *Type B* method called to the names shown
282 above, or just add parentheses around the parameters as needed to turn
283 them into tuples and let the SWIG typemaps turn them into the wx.Point
284 or wx.Size object that is expected. Then you will be calling the new
285 *Type A* method. For example, if you had this code before::
287 dc.DrawRectangle(x, y, width, height)
289 You could either continue to use the *Type B* method bu changing the
290 name to DrawRectabgleXY, or just change it to the new *Type A* by
291 adding some parentheses like this::
293 dc.DrawRectangle((x, y), (width, height))
295 Or if you were already using a point and size::
297 dc.DrawRectangle(p.x, p.y, s.width, s.height)
299 Then you can just simplify it like this::
301 dc.DrawRectangle(p, s)
306 Building, Extending and Embedding wxPython
307 ------------------------------------------
309 wxPython's setup.py script now expects to use existing libraries for
310 the contribs (gizmos, stc, xrc, etc.) rather than building local
311 copies of them. If you build your own copies of wxPython please be
312 aware that you now need to also build the ogl, stc, xrc, and gizmos
313 libraries in addition to the main wx lib. [[TODO: update the
314 BUILD.*.txt files too!]]
316 The wxPython.h and other header files are now in
317 .../wxPython/include/wx/wxPython instead of in wxPython/src. You should
318 include it via the "wx/wxPython/wxPython.h" path and add
319 .../wxPython/include to your list of include paths. [[TODO: Install
320 these headers on Linux...]]
322 You no longer need to call wxClassInfo::CleanUpClasses() and
323 wxClassInfo::InitializeClasses() in your extensions or when embedding
329 Two (or Three!) Phase Create
330 ----------------------------
332 If you use the Precreate/Create method of instantiating a window, (for
333 example, to set an extended style flag, or for XRC handlers) then
334 there is now a new method named PostCreate to help with transplanting
335 the brain of the prewindow instance into the derived window instance.
338 class MyDialog(wx.Dialog):
339 def __init__(self, parent, ID, title, pos, size, style):
341 pre.SetExtraStyle(wx.DIALOG_EX_CONTEXTHELP)
342 pre.Create(parent, ID, title, pos, size, style)
350 The hack allowing the old "option" keyword parameter has been
351 removed. If you use keyworkd args with wxSizer Add, Insert, or
352 Prepend then you will need to use the "proportion" name instead of
355 When adding a spacer to a sizer you now need to use a wxSize or a
356 2-integer sequence instead of separate width and height parameters.
358 The wxGridBagSizer class (very similar to the RowColSizer in the
359 library) has been added to C++ and wrapped for wxPython. It can also
362 You should not use AddWindow, AddSizer, AddSpacer (and similar for
363 Insert, Prepend, and etc.) methods any longer. Just use Add and the
364 wrappers will figure out what to do.
371 Instead of over a dozen separate extension modules linked together
372 into a single extension module, the "core" module is now just a few
373 extensions that are linked independently, and then merged together
374 later into the main namespace via Python code.
376 Because of the above, the "internal" module names have changed, but
377 you shouldn't have been using them anyway so it shouldn't bother
380 The wxPython.help module no longer exists and the classes therein are
381 now part of the core module imported with wxPython.wx or the wx
384 wxPyDefaultPosition and wxPyDefaultSize are gone. Use the
385 wxDefaultPosition and wxDefaultSize objects instead.
387 Similarly, the wxSystemSettings backwards compatibiility aliases for
388 GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
389 the bit-bucket. Use GetColour, GetFont and GetMetric instead.