]> git.saurik.com Git - wxWidgets.git/blame - wxPython/docs/MigrationGuide.html
distrib tweaks
[wxWidgets.git] / wxPython / docs / MigrationGuide.html
CommitLineData
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
142.5 and let you know what you need to do to adapt your programs to
15those changes. Be sure to also check in the CHANGES.txt file like
16usual to see info about the not so major changes and other things that
17have 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
21such that wxWindows and the underlying gui toolkit are <strong>not</strong>
22initialized until the wx.App object is created (but before wx.App.OnInit
23is called.) This was required because of some changes that were made
24to the C++ wxApp class.</p>
25<p>There are both benefits and potential problems with this change. The
26benefits are that you can import wxPython without requiring access to
27a GUI (for checking version numbers, etc.) and that in a
28multi-threaded environment the thread that creates the app object will
29now be the GUI thread instead of the one that imports wxPython. Some
30potential problems are that the C++ side of the &quot;stock-objects&quot;
31(wx.BLUE_PEN, wx.TheColourDatabase, etc.) are not initialized until
32the wx.App object is created, so you should not use them until after
6158f936
RD
33you have created your wx.App object. If you do then an exception will
34be raised telling you that the C++ object has not bene initialized
35yet.</p>
d14a1e28
RD
36<p>Also, you will probably not be able to do any kind of GUI or bitmap
37operation unless you first have created an app object, (even on
38Windows 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
43customizations added that I hope to get folded back into the main SWIG
44distribution.) This has some far reaching ramifications:</p>
45<blockquote>
46<p>All classes derive from object and so all are now &quot;new-style
47classes&quot;</p>
48<p>Public data members of the C++ classes are wrapped as Python
49properties using property() instead of using __getattr__/__setattr__
50like before. Normally you shouldn't notice any difference, but if
51you were previously doing something with __getattr__/__setattr__
52in derived classes then you may have to adjust things.</p>
53<p>Static C++ methods are wrapped using the staticmethod()
54feature of Python and so are accessible as ClassName.MethodName
55as expected. They are still available as top level functions
56ClassName_MethodName as before.</p>
57<p>The relationship between the wxFoo and wxFooPtr classes have
58changed for the better. Specifically, all instances that you see
59will be wxFoo even if they are created internally using wxFooPtr,
60because wxFooPtr.__init__ will change the instance's __class__ as
61part of the initialization. If you have any code that checks
62class type using something like isinstance(obj, wxFooPtr) you will
63need 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
69class. They have a __call__ method so they can still be used as
70functions like before, but making them instances adds some
71flexibility.</p>
72<p>wx.EvtHandler (the base class for wx.Window) now has a Bind method that
73makes binding events to windows a little easier. Here is its
74definition and docstring:</p>
75<pre class="literal-block">
76def 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">
101self.Bind(wx.EVT_SIZE, self.OnSize)
102self.Bind(wx.EVT_BUTTON, self.OnButtonClick, theButton)
8eda5e35
RD
103self.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
106such that they return a reference to the wx.MenuItem that was created.
107Additionally menu items and toolbar items have been modified to
108automatically generate a new ID if -1 is given, similar to using -1
109with window classess. This means that you can create menu or toolbar
110items and event bindings without having to predefine a unique menu ID,
111although you still can use IDs just like before if you want. For
112example, these are all equivallent other than ID values:</p>
113<pre class="literal-block">
1141.
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
1182.
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
1223.
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)
d14a1e28 125</pre>
d14a1e28
RD
126<p>If you create your own custom event types and EVT_* functions, and you
127want to be able to use them with the Bind method above then you should
128change your EVT_* to be an instance of wxPyEventBinder instead of a
129function. If you used to have something like this:</p>
130<pre class="literal-block">
131myCustomEventType = wxNewEventType()
132def 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
137myCustomEventType = wx.NewEventType()
138EVT_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
141number 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
146that 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
148wx. There is still a Python package named wxPython with modules
149that have the names with the wx prefix for backwards compatibility.
150Instead of dynamically changing the names at module load time like in
1512.4, the compatibility modules are generated at build time and contain
152assignment statements like this:</p>
153<pre class="literal-block">
154wxWindow = wx.core.Window
155</pre>
156<p>Don't let the &quot;core&quot; in the name bother you. That and some other
157modules are implementation details, and everything that was in the
6158f936
RD
158wxPython.wx module before will still be in the wx package namespace
159after 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
161interesting... SWIG is now run twice for each module that it is
162generating code for. The first time it outputs an XML representaion
163of the parse tree, which can be up to 20MB and 300K lines in size!
164That XML is then run through a little Python script that creates a
165file full of SWIG %rename directives that take the wx off of the
166names, and also generates the Python compatibility file described
167above that puts the wx back on the names. SWIG is then run a second
168time to generate the C++ code to implement the extension module, and
169uses 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
171some work has to be done by hand, especially for the reverse-renamers.
172So 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 &quot;wx&quot; prefix are now
174the official form of the wxPython classes. For example:</p>
175<pre class="literal-block">
176import wx
177
178class 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
188app = wx.PySimpleApp()
189f = MyFrame(None, &quot;What's up?&quot;)
190f.Show()
191app.MainLoop()
192</pre>
193<p>You shouldn't need to migrate all your modules over to use the new
194package and names right away as there are modules in place that try to
195provide as much backwards compatibility of the names as possible. If
82a074ce 196you rewrote the above sample using &quot;from wxPython.wx import * &quot;, the
6158f936
RD
197old wxNames, and the old style of event binding it will still work
198just 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
203wxPoint or wxSize parameters (let's call these <em>Type A</em>) instead of
204the individual x, y, width, height, etc. parameters (and we'll call
205these <em>Type B</em>). In the rest of the library I normally made the <em>Type
206A</em> forms of the methods be the default method with the &quot;normal&quot; name,
207and had renamed the <em>Type B</em> forms of the methods to some similar
208name. For example in wx.Window we have these Python methods:</p>
209<pre class="literal-block">
210SetSize(size) # Type A
211SetSizeWH(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
214and the existing <em>Type B</em> methods were never renamed. Now that lots
215of other things are also changing in wxPython it has been decided that
216it is a good time to also do the method renaming in wx.DC too in order
d14a1e28
RD
217to be consistent with the rest of the library. The methods in wx.DC
218that are affected are listed here:</p>
219<pre class="literal-block">
220FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
221FloodFill(point, colour, style = wx.FLOOD_SURFACE)
222
223GetPixelXY(x, y)
224GetPixel(point)
225
226DrawLineXY(x1, y1, x2, y2)
227DrawLine(point1, point2)
228
229CrossHairXY(x, y)
230CrossHair(point)
231
232DrawArcXY(x1, y1, x2, y2, xc, yc)
233DrawArc(point1, point2, center)
234
235DrawCheckMarkXY(x, y, width, height)
236DrawCheckMark(rect)
237
238DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
239DrawEllipticArc(point, size, start_angle, end_angle)
240
241DrawPointXY(x, y)
242DrawPoint(point)
243
244DrawRectangleXY(x, y, width, height)
245DrawRectangle(point, size)
246DrawRectangleRect(rect)
247
248DrawRoundedRectangleXY(x, y, width, height, radius)
249DrawRoundedRectangle(point, size, radius)
250DrawRoundedRectangleRect(rect, radius)
251
252DrawCircleXY(x, y, radius)
253DrawCircle(point, radius)
254
255DrawEllipseXY(x, y, width, height)
256DrawEllipse(point, size)
257DrawEllipseRect(rect)
258
259DrawIconXY(icon, x, y)
260DrawIcon(icon, point)
261
262DrawBitmapXY(bmp, x, y, useMask = FALSE)
263DrawBitmap(bmp, point, useMask = FALSE)
264
265DrawTextXY(text, x, y)
266DrawText(text, point)
267
268DrawRotatedTextXY(text, x, y, angle)
269DrawRotatedText(text, point, angle)
270
271
272BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
273 rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
274Blit(destPt, size, sourceDC, srcPt,
275 rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
6158f936 276
82a074ce 277SetClippingRegionXY(x, y, width, height)
6158f936
RD
278SetClippingRegion(point, size)
279SetClippingRect(rect)
280SetClippingRegionAsRegion(region);
d14a1e28 281</pre>
e75fd8a4
RD
282<p>If you have code that draws on a DC and you are using the new wx
283namespace then you <strong>will</strong> get errors because of these changes, but
284it should be easy to fix the code. You can either change the name of
285the <em>Type B</em> method called to the names shown above, or just add
286parentheses around the parameters as needed to turn them into tuples
287and let the SWIG typemaps turn them into the wx.Point or wx.Size
288object that is expected. Then you will be calling the new <em>Type A</em>
289method. For example, if you had this code before:</p>
d14a1e28
RD
290<pre class="literal-block">
291dc.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
294name to DrawRectabgleXY, or just change it to the new <em>Type A</em> by
295adding some parentheses like this:</p>
d14a1e28
RD
296<pre class="literal-block">
297dc.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">
301dc.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">
305dc.DrawRectangle(p, s)
306</pre>
e75fd8a4
RD
307<p>Now before you start yelling and screaming at me for breaking all your
308code, take note that I said above &quot;...using the new wx namespace...&quot;
309That's because if you are still importing from wxPython.wx then there
310are some classes defined there with Draw and etc. methods that have
3112.4 compatible signatures. However if/when the old wxPython.wx
312namespace is removed then these classes will be removed too so you
313should plan on migrating to the new namespace and new DC Draw methods
314before 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
319the contribs (gizmos, stc, xrc, etc.) rather than building local
320copies of them. If you build your own copies of wxPython please be
321aware that you now need to also build the ogl, stc, xrc, and gizmos
322libraries in addition to the main wx lib. [[TODO: update the
323BUILD.*.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
326include it via the &quot;wx/wxPython/wxPython.h&quot; path and add
327.../wxPython/include to your list of include paths. [[TODO: Install
328these headers on Linux...]]</p>
329<p>You no longer need to call wxClassInfo::CleanUpClasses() and
330wxClassInfo::InitializeClasses() in your extensions or when embedding
331wxPython.</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
336example, to set an extended style flag, or for XRC handlers) then
337there is now a new method named PostCreate to help with transplanting
338the brain of the prewindow instance into the derived window instance.
339For example:</p>
340<pre class="literal-block">
341class 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 &quot;option&quot; keyword parameter has been removed.
352If you use keyworkd args with wxSizer Add, Insert, or Prepend methods
353then you will need to use the &quot;proportion&quot; name instead of &quot;option&quot;.</p>
6158f936
RD
354<p>When adding a spacer to a sizer you now need to use a wxSize or a
3552-integer sequence instead of separate width and height parameters.</p>
356<p>The wxGridBagSizer class (very similar to the RowColSizer in the
357library) has been added to C++ and wrapped for wxPython. It can also
358be used from XRC.</p>
359<p>You should not use AddWindow, AddSizer, AddSpacer (and similar for
360Insert, Prepend, and etc.) methods any longer. Just use Add and the
361wrappers 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
366into a single extension module, the &quot;core&quot; module is now just a few
367extensions that are linked independently, and then merged together
368later 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,
370the &quot;internal&quot; module names have changed, but you shouldn't have been
371using them anyway so it shouldn't bother you. ;-)</p>
372<p>The help module no longer exists and the classes therein are now part
373of the core module imported with wxPython.wx or the wx package.</p>
6158f936
RD
374<p>wxPyDefaultPosition and wxPyDefaultSize are gone. Use the
375wxDefaultPosition and wxDefaultSize objects instead.</p>
376<p>Similarly, the wxSystemSettings backwards compatibiility aliases for
377GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
378the 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
380all windows. The name still exists for compatibility, but it is set
381to zero. If you want to disable the setting (so it matches the old
382default) then you need to use the new wx.FULL_REPAINT_ON_RESIZE style
383flag otherwise only the freshly exposed areas of the window will be
384refreshed.</p>
385<p>wxPyTypeCast has been removed. Since we've had the OOR (Original
386Object Return) for a couple years now there should be no need to use
387wxPyTypeCast at all.</p>
8eda5e35
RD
388<p>If you use the old wxPython package and wxPython.wx namespace then
389there 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
391different API.</p>
6158f936 392</div>
d14a1e28 393</div>
6158f936
RD
394<hr class="footer" />
395<div class="footer">
8eda5e35 396Generated on: 2004-02-04 23:31 UTC.
d14a1e28
RD
397</div>
398</body>
399</html>