]> git.saurik.com Git - wxWidgets.git/blob - wxPython/docs/MigrationGuide.html
Reworked how stock objects are initialized. They now have an
[wxWidgets.git] / wxPython / docs / MigrationGuide.html
1 <?xml version="1.0" encoding="utf-8" ?>
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=utf-8" />
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. (In fact, until I find a better
34 solution trying to use one of the stock objects before the app is
35 created will probably result in a crash.)</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 = wxNewEventType()
119 EVT_MY_CUSTOM_EVENT = wxPyEventBinder(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 before will still be in the wx package namespace after
140 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 </div>
155 <div class="section" id="new-wx-dc-methods">
156 <h1><a name="new-wx-dc-methods">New wx.DC Methods</a></h1>
157 <p>Many of the Draw methods of wx.DC have alternate forms in C++ that take
158 wxPoint or wxSize parameters (let's call these <em>Type A</em>) instead of
159 the individual x, y, width, height, etc. parameters (and we'll call
160 these <em>Type B</em>). In the rest of the library I normally made the <em>Type
161 A</em> forms of the methods be the default method with the &quot;normal&quot; name,
162 and had renamed the <em>Type B</em> forms of the methods to some similar
163 name. For example in wx.Window we have these Python methods:</p>
164 <pre class="literal-block">
165 SetSize(size) # Type A
166 SetSizeWH(width, height) # Type B
167 </pre>
168 <p>For various reasons the new <em>Type A</em> methods in wx.DC were never added
169 and the existing <em>Type B</em> methods renamed. Now that lots of other
170 things are also changing in wxPython that it has been decided that it
171 is a good time to also do the method renaming in wx.DC too, in order
172 to be consistent with the rest of the library. The methods in wx.DC
173 that are affected are listed here:</p>
174 <pre class="literal-block">
175 FloodFillXY(x, y, colour, style = wx.FLOOD_SURFACE)
176 FloodFill(point, colour, style = wx.FLOOD_SURFACE)
177
178 GetPixelXY(x, y)
179 GetPixel(point)
180
181 DrawLineXY(x1, y1, x2, y2)
182 DrawLine(point1, point2)
183
184 CrossHairXY(x, y)
185 CrossHair(point)
186
187 DrawArcXY(x1, y1, x2, y2, xc, yc)
188 DrawArc(point1, point2, center)
189
190 DrawCheckMarkXY(x, y, width, height)
191 DrawCheckMark(rect)
192
193 DrawEllipticArcXY(x, y, w, h, start_angle, end_angle)
194 DrawEllipticArc(point, size, start_angle, end_angle)
195
196 DrawPointXY(x, y)
197 DrawPoint(point)
198
199 DrawRectangleXY(x, y, width, height)
200 DrawRectangle(point, size)
201 DrawRectangleRect(rect)
202
203 DrawRoundedRectangleXY(x, y, width, height, radius)
204 DrawRoundedRectangle(point, size, radius)
205 DrawRoundedRectangleRect(rect, radius)
206
207 DrawCircleXY(x, y, radius)
208 DrawCircle(point, radius)
209
210 DrawEllipseXY(x, y, width, height)
211 DrawEllipse(point, size)
212 DrawEllipseRect(rect)
213
214 DrawIconXY(icon, x, y)
215 DrawIcon(icon, point)
216
217 DrawBitmapXY(bmp, x, y, useMask = FALSE)
218 DrawBitmap(bmp, point, useMask = FALSE)
219
220 DrawTextXY(text, x, y)
221 DrawText(text, point)
222
223 DrawRotatedTextXY(text, x, y, angle)
224 DrawRotatedText(text, point, angle)
225
226
227 BlitXY(xdest, ydest, width, height, sourceDC, xsrc, ysrc,
228 rop = wxCOPY, useMask = FALSE, xsrcMask = -1, ysrcMask = -1)
229 Blit(destPt, size, sourceDC, srcPt,
230 rop = wxCOPY, useMask = FALSE, srcPtMask = wx.DefaultPosition)
231 </pre>
232 <p>If you have code that draws on a DC you <strong>will</strong> get errors because of
233 these changes, but it should be easy to fix the code. You can either
234 change the name of the <em>Type B</em> method called as shown above, or just
235 add parentheses around the parameters as needed to turn them into
236 tuples and let the SWIG typemaps turn them into the wx.Point or
237 wx.Size object that is expected. For example, if you had this code
238 before:</p>
239 <pre class="literal-block">
240 dc.DrawRectangle(x, y, width, height)
241 </pre>
242 <p>You could just change it like this:</p>
243 <pre class="literal-block">
244 dc.DrawRectangle((x, y), (width, height))
245 </pre>
246 <p>Or if you were already using a point and size:</p>
247 <pre class="literal-block">
248 dc.DrawRectangle(p.x, p.y, s.width, s.height)
249 </pre>
250 <p>Then you can just change it like this:</p>
251 <pre class="literal-block">
252 dc.DrawRectangle(p, s)
253 </pre>
254 </div>
255 <div class="section" id="building-extending-and-embedding-wxpython">
256 <h1><a name="building-extending-and-embedding-wxpython">Building, Extending and Embedding wxPython</a></h1>
257 <p>wxPython's setup.py script now expects to use existing libraries for
258 the contribs (gizmos, stc, xrc, etc.) rather than building local
259 copies of them. If you build your own copies of wxPython please be
260 aware that you now need to also build the ogl, stc, xrc, and gizmos
261 libraries in addition to the main wx lib. [[TODO: update the
262 BUILD.*.txt files too!]]</p>
263 <p>The wxPython.h and other header files are now in
264 .../wxPython/include/wx/wxPython instead of in wxPython/src. You should
265 include it via the &quot;wx/wxPython/wxPython.h&quot; path and add
266 .../wxPython/include to your list of include paths. [[TODO: Install
267 these headers on Linux...]]</p>
268 <p>You no longer need to call wxClassInfo::CleanUpClasses() and
269 wxClassInfo::InitializeClasses() in your extensions or when embedding
270 wxPython.</p>
271 </div>
272 <div class="section" id="other-stuff">
273 <h1><a name="other-stuff">Other Stuff</a></h1>
274 <p>Instead of over a dozen separate extension modules linked together
275 into a single extension module, the &quot;core&quot; module is now just a few
276 extensions that are linked independently, and then merged together
277 later into the main namespace via Python code.</p>
278 <p>Because of the above, the &quot;internal&quot; module names have changed, but
279 you shouldn't have been using them anyway so it shouldn't bother
280 you. ;-)</p>
281 </div>
282 </div>
283 </body>
284 </html>