]>
Commit | Line | Data |
---|---|---|
6158f936 | 1 | <?xml version="1.0" encoding="iso-8859-1" ?> |
d14a1e28 RD |
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> | |
6158f936 | 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
d14a1e28 RD |
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 "stock-objects" | |
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 | |
6158f936 RD |
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> | |
d14a1e28 RD |
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 "new-style | |
47 | classes"</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 | """ | |
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 | """ | |
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) | |
8eda5e35 RD |
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, "E&xit", "Terminate the App") | |
116 | self.Bind(wx.EVT_MENU, self.OnExit, item) | |
117 | ||
118 | 2. | |
119 | item = menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App") | |
120 | self.Bind(wx.EVT_MENU, self.OnExit, item) | |
121 | ||
122 | 3. | |
123 | menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App") | |
124 | self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT) | |
d14a1e28 | 125 | </pre> |
d14a1e28 RD |
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"> | |
6158f936 RD |
137 | myCustomEventType = wx.NewEventType() |
138 | EVT_MY_CUSTOM_EVENT = wx.PyEventBinder(myCustomEventType, 1) | |
d14a1e28 RD |
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 "core" in the name bother you. That and some other | |
157 | modules are implementation details, and everything that was in the | |
6158f936 RD |
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> | |
d14a1e28 RD |
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> | |
6158f936 RD |
173 | <p>In summary, the wx package and names without the "wx" 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, "Do It", (10,10)) | |
183 | self.Bind(wx.EVT_BUTTON, self.JustDoIt, b) | |
184 | ||
185 | def JustDoIt(self, evt): | |
186 | print "It's done!" | |
187 | ||
188 | app = wx.PySimpleApp() | |
189 | f = MyFrame(None, "What's up?") | |
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 | |
82a074ce | 196 | you rewrote the above sample using "from wxPython.wx import * ", the |
6158f936 RD |
197 | old wxNames, and the old style of event binding it will still work |
198 | just fine.</p> | |
d14a1e28 RD |
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 "normal" 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 | |
6158f936 RD |
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 | |
d14a1e28 RD |
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) | |
6158f936 | 276 | |
82a074ce | 277 | SetClippingRegionXY(x, y, width, height) |
6158f936 RD |
278 | SetClippingRegion(point, size) |
279 | SetClippingRect(rect) | |
280 | SetClippingRegionAsRegion(region); | |
d14a1e28 | 281 | </pre> |
e75fd8a4 RD |
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> | |
d14a1e28 RD |
290 | <pre class="literal-block"> |
291 | dc.DrawRectangle(x, y, width, height) | |
292 | </pre> | |
6158f936 RD |
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> | |
d14a1e28 RD |
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> | |
6158f936 | 303 | <p>Then you can just simplify it like this:</p> |
d14a1e28 RD |
304 | <pre class="literal-block"> |
305 | dc.DrawRectangle(p, s) | |
306 | </pre> | |
e75fd8a4 RD |
307 | <p>Now before you start yelling and screaming at me for breaking all your |
308 | code, take note that I said above "...using the new wx namespace..." | |
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> | |
d14a1e28 RD |
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 "wx/wxPython/wxPython.h" 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> | |
6158f936 RD |
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> | |
8eda5e35 RD |
351 | <p>The hack allowing the old "option" 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 "proportion" name instead of "option".</p> | |
6158f936 RD |
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> | |
d14a1e28 RD |
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 "core" 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> | |
8eda5e35 RD |
369 | <p>Because of the above and also because of the way the new SWIG works, |
370 | the "internal" 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> | |
6158f936 RD |
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> | |
8eda5e35 RD |
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> | |
6158f936 | 392 | </div> |
d14a1e28 | 393 | </div> |
6158f936 RD |
394 | <hr class="footer" /> |
395 | <div class="footer"> | |
8eda5e35 | 396 | Generated on: 2004-02-04 23:31 UTC. |
d14a1e28 RD |
397 | </div> |
398 | </body> | |
399 | </html> |