]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/porting/porting.tex
I've now added the documentation files.
[wxWidgets.git] / docs / latex / porting / porting.tex
1 \documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
2 \newcommand{\indexit}[1]{#1\index{#1}}%
3 \newcommand{\pipe}[0]{$\|$\ }%
4 \definecolour{black}{0}{0}{0}%
5 \definecolour{cyan}{0}{255}{255}%
6 \definecolour{green}{0}{255}{0}%
7 \definecolour{magenta}{255}{0}{255}%
8 \definecolour{red}{255}{0}{0}%
9 \definecolour{blue}{0}{0}{200}%
10 \definecolour{yellow}{255}{255}{0}%
11 \definecolour{white}{255}{255}{255}%
12 \input psbox.tex
13 \parskip=10pt
14 \parindent=0pt
15 \title{Guide to porting applications from wxWindows 1.xx to 2.0}
16 \author{Julian Smart}
17 \date{October 1997}
18 \makeindex
19 \begin{document}
20 \maketitle
21 \pagestyle{fancyplain}
22 \bibliographystyle{plain}
23 \setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
24 \setfooter{\thepage}{}{}{}{}{\thepage}%
25 \pagenumbering{roman}
26 \tableofcontents
27 %
28 \chapter{About this document}\label{about}
29 \pagenumbering{arabic}%
30 \setheader{{\it Porting guide}}{}{}{}{}{{\it Porting guide}}%
31 \setfooter{\thepage}{}{}{}{}{\thepage}%
32
33 This document gives guidelines and tips for porting applications from
34 version 1.xx of wxWindows to version 2.0.
35
36 The first section offers tips for writing 1.xx applications in a way to
37 minimize porting time. The following sections detail the changes and
38 how you can modify your application to be 2.0-compliant.
39
40 You may be worrying that porting to 2.0 will be a lot of work,
41 particularly if you have only recently started using 1.xx. In fact,
42 the wxWindows 2.0 API has far more in common with 1.xx than it has differences.
43 With backward compatibility mode on, much of the conversion can be
44 done gradually. The main challenges are doing without the default
45 panel item layout, and the lack of automatic labels in some controls.
46 However, if you already use resource files (.wxr), or application-specific positioning,
47 or constraints, then even this will be quite painless.
48
49 So please don't be freaked out by the jump to 2.0! For one thing, 1.xx is still available
50 and will be supported by the user community for some time. And when you have
51 changed to 2.0, we hope that you will appreciate the benefits in terms
52 of greater flexibility, better user interface aesthetics, improved C++ conformance,
53 improved compilation speed, and many other enhancements. The revised architecture
54 of 2.0 will ensure that wxWindows can continue to evolve for the forseeable
55 future.
56
57 {\it Please note that this document is a work in progress.}
58
59 \chapter{Preparing for version 2.0}\label{preparing}
60
61 Even before compiling with version 2.0, there's also a lot you can do right now to make porting
62 relatively simple. Here are a few tips.
63
64 \begin{itemize}
65 \item {\bf Use constraints or .wxr resources} for layout, rather than the default layout scheme.
66 Constraints should be the same in 2.0, and resources will be translated.
67 \item {\bf Use separate wxMessage items} instead of labels for wxText, wxMultiText,
68 wxChoice, wxComboBox. These labels will disappear in 2.0. Use separate
69 wxMessages whether you're creating controls programmatically or using
70 the dialog editor. The future dialog editor will be able to translate
71 from old to new more accurately if labels are separated out.
72 \item {\bf Parameterise functions that use wxDC} or derivatives, i.e. make the wxDC
73 an argument to all functions that do drawing. Minimise the use of
74 wxWindow::GetDC and definitely don't store wxDCs long-term
75 because in 2.0, you can't use GetDC() and wxDCs are not persistent.
76 You will use wxClientDC, wxPaintDC stack objects instead. Minimising
77 the use of GetDC() will ensure that there are very few places you
78 have to change drawing code for 2.0.
79 \item {\bf Don't set GDI objects} (wxPen, wxBrush etc.) in windows or wxCanvasDCs before they're
80 needed (e.g. in constructors) - do so within your drawing routine instead. In
81 2.0, these settings will only take effect between the construction and destruction
82 of temporary wxClient/PaintDC objects.
83 \item {\bf Don't rely} on arguments to wxDC functions being floating point - they will
84 be 32-bit integers in 2.0.
85 \item {\bf Don't use the wxCanvas member functions} that duplicate wxDC functions, such as SetPen and DrawLine, since
86 they are going.
87 \item {\bf Using member callbacks} called from global callback functions will make the transition
88 easier - see the FAQ
89 for some notes on using member functions for callbacks. wxWindows 2.0 will banish global
90 callback functions (and OnMenuCommand), and nearly all event handling will be done by functions taking a single event argument.
91 So in future you will have code like:
92
93 {\small\begin{verbatim}
94 void MyFrame::OnOK(wxCommandEvent& event)
95 {
96 ...
97 }
98 \end{verbatim}
99 }%
100
101 You may find that writing the extra code to call a member function isn't worth it at this stage,
102 but the option is there.
103 \item {\bf Use wxString wherever possible.} 2.0 will replace char * with wxString
104 in most cases, and if you use wxString to receive strings returned from
105 wxWindows functions (except when you need to save the pointer if deallocation is required), there should
106 be no conversion problems later on.
107 \item Be aware that under Windows, {\bf font sizes will change} to match standard Windows
108 font sizes (for example, a 12-point font will appear bigger than before). Write your application
109 to be flexible where fonts are concerned.
110 Don't rely on fonts being similarly-sized across platforms, as they were (by chance) between
111 Windows and X under wxWindows 1.66. Yes, this is not easy... but I think it's better to conform to the
112 standards of each platform, and currently the size difference makes it difficult to
113 conform to Windows UI standards. You may eventually wish to build in a global 'fudge-factor' to compensate
114 for size differences. The old font sizing will still be available via wx\_setup.h, so do not panic...
115 \item {\bf Consider dropping wxForm usage}: an alternative is to be found in utils/wxprop.
116 wxPropertyFormView can be used in a wxForm-like way, except that you specify a pre-constructed panel
117 or dialog; or you can use a wxPropertyListView to show attributes in a scrolling list - you don't even need
118 to lay panel items out.
119
120 Because wxForm uses a number of features to be dropped in wxWindows 2.0, it cannot be
121 supported in the future, at least in its present state.
122 \item {\bf When creating a wxListBox}, put the wxLB\_SINGLE, wxLB\_MULTIPLE, wxLB\_EXTENDED styles in the window style parameter, and put
123 zero in the {\it multiple} parameter. The {\it multiple} parameter will be removed in 2.0.
124 \item {\bf For MDI applications}, don't reply on MDI being run-time-switchable in the way that the
125 MDI sample is. In wxWindows 2.0, MDI functionality is separated into distinct classes.
126 \end{itemize}
127
128 \chapter{The new event system}\label{eventsystem}
129
130 The way that events are handled has been radically changed in wxWindows 2.0. Please
131 read the topic `Event handling overview' in the wxWindows 2.0 manual for background
132 on this.
133
134 \section{Callbacks}
135
136 Instead of callbacks for panel items, menu command events, control commands and other events are directed to
137 the originating window, or an ancestor, or an event handler that has been plugged into the window
138 or its ancestor. Event handlers always have one argument, a derivative of wxEvent.
139
140 For menubar commands, the {\bf OnMenuCommand} member function will be replaced by a series of separate member functions,
141 each of which responds to a particular command. You need to add these (non-virtual) functions to your
142 frame class, add a DECLARE\_EVENT\_TABLE entry to the class, and then add an event table to
143 your implementation file, as a BEGIN\_EVENT\_TABLE and END\_EVENT\_TABLE block. The
144 individual event mapping macros will be of the form:
145
146 \begin{verbatim}
147 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
148 EVT_MENU(MYAPP_NEW, MyFrame::OnNew)
149 EVT_MENU(wxID_EXIT, MyFrame::OnExit)
150 END_EVENT_TABLE()
151 \end{verbatim}
152
153 Control commands, such as button commands, can be routed to a derived button class,
154 the parent window, or even the frame. Here, you use a function of the form EVT\_BUTTON(id, func).
155 Similar macros exist for other control commands.
156
157 \section{Other events}
158
159 To intercept other events, you used to override virtual functions, such as OnSize. Now, while you can use
160 the OnSize name for such event handlers (or any other name of your choice), it has only a single argument
161 (wxSizeEvent) and must again be `mapped' using the EVT\_SIZE macro. The same goes for all other events,
162 including OnClose (although in fact you can still use the old, virtual form of OnClose for the time being).
163
164 \chapter{Class hierarchy}\label{classhierarchy}
165
166 The class hierarchy has changed somewhat. wxToolBar and wxButtonBar
167 classes have been split into several classes, and are derived from wxControl (which was
168 called wxItem). wxPanel derives from wxWindow instead of from wxCanvas, which has
169 disappeared in favour of wxScrolledWindow (since all windows are now effectively canvases
170 which can be drawn into). The status bar has become a class in its own right, wxStatusBar.
171
172 There are new MDI classes so that wxFrame does not have to be overloaded with this
173 functionality.
174
175 There are new device context classes, with wxPanelDC and wxCanvasDC disappearing.
176 See \helpref{Device contexts and painting}{dc}.
177
178 \chapter{GDI objects}\label{gdiobjects}
179
180 These objects - instances of classes such as wxPen, wxBrush, wxBitmap (but not wxColour) -
181 are now implemented with reference-counting. This makes assignment a very cheap operation,
182 and also means that management of the resource is largely automatic. You now pass {\it references} to
183 objects to functions such as wxDC::SetPen. The device context does not store a copy of the pen
184 itself, but takes a copy of it (via reference counting), and the object's data gets freed up
185 when the reference count goes to zero. The application does not have to worry so much about
186 who the object belongs to: it can pass the reference, then destroy the object without
187 leaving a dangling pointer inside the device context.
188
189 For the purposes of code migration, you can use the old style of object management - maintaining
190 pointers to GDI objects, and using the FindOrCreate... functions. However, it is preferable to
191 keep this explicit management to a minimum, instead creating objects on the fly as needed, on the stack,
192 unless this causes too much of an overhead in your application.
193
194 At a minimum, you will have to make sure that calls to SetPen, SetBrush etc. work. Some compilers
195 will do the conversion from pointer to reference automatically (via a constructor in the GDI
196 class) but you cannot rely on this being true for all compilers. Also, where you pass NULL to these
197 functions, you will need to either cast to the appropriate reference type, or instead
198 use an identifier such as wxNullPen or wxNullBrush.
199
200 \chapter{Dialogs and controls}\label{dialogscontrols}
201
202 \wxheading{Labels}
203
204 Most controls no longer have labels and values as they used to in 1.xx. Instead, labels
205 should be created separately using wxStaticText (the new name for wxMessage). This will
206 need some reworking of dialogs, unfortunately; programmatic dialog creation that doesn't
207 use constraints will be especially hard-hit. Perhaps take this opportunity to make more
208 use of dialog resources or constraints. Or consider using the wxPropertyListView class
209 which can do away with dialog layout issues altogether by presenting a list of editable
210 properties.
211
212 \wxheading{Constructors}
213
214 All window constructors have two main changes, apart from the label issue mentioned above.
215 Windows now have integer identifiers; and position and size are now passed as wxPoint and
216 wxSize objects. In addition, some windows have a wxValidator argument. wxWindows 2.0 may provide
217 old-style constructors in WXWIN\_COMPATIBILITY mode for limited backward compatibility.
218
219 \wxheading{Show versus ShowModal}
220
221 If you have used or overridden the {\bf wxDialog::Show} function in the past, you may find
222 that modal dialogs no longer work as expected. This is because the function for modal showing
223 is now {\bf wxDialog:ShowModal}. This is part of a more fundamental change in which a
224 control may tell the dialog that it caused the dismissal of a dialog, by
225 calling {\bf wxDialog::EndModal} or {\bf wxWindow::SetReturnCode}. Using this
226 information, {\bf ShowModal} now returns the id of the control that caused dismissal,
227 giving greater feedback to the application than just TRUE or FALSE.
228
229 If you overrode or called {\bf wxDialog::Show}, use {\bf ShowModal} and test for a returned identifier,
230 commonly wxID\_OK or wxID\_CANCEL.
231
232 \wxheading{wxItem}
233
234 This is renamed wxControl.
235
236 \wxheading{wxText, wxMultiText and wxTextWindow}
237
238 These classes no longer exist and are replaced by the single class wxTextCtrl.
239 Multi-line text items are created using the wxTE\_MULTILINE style.
240
241 \wxheading{wxButton}
242
243 Bitmap buttons are now a separate class, instead of being part of wxBitmap.
244
245 \wxheading{wxMessage}
246
247 Bitmap messages are now a separate class, wxStaticBitmap, and wxMessage
248 is renamed wxStaticText.
249
250 \wxheading{wxGroupBox}
251
252 wxGroupBox is renamed wxStaticBox.
253
254 \wxheading{wxForm}
255
256 Note that wxForm is no longer supported in wxWindows 2.0. Consider using the wxPropertyForm class
257 instead, which takes standard dialogs and panels and associates controls with property objects.
258 You may also find that the new validation method, combined with dialog resources, is easier
259 and more flexible than using wxForm.
260
261 \chapter{Device contexts and painting}\label{dc}
262
263 In wxWindows 2.0, device contexts are used for drawing into, as per 1.xx, but the way
264 they are accessed and constructed is a bit different.
265
266 You no longer use {\bf GetDC} to access device contexts for panels, dialogs and canvases.
267 Instead, you create a temporary device context, which means that any window or control can be drawn
268 into. The sort of device context you create depends on where your code is called from. If
269 painting within an {\bf OnPaint} handler, you create a wxPaintDC. If not within an {\bf OnPaint} handler,
270 you use a wxClientDC or wxWindowDC. You can still parameterise your drawing code so that it
271 doesn't have to worry about what sort of device context to create - it uses the DC it is passed
272 from other parts of the program.
273
274 You {\bf must } create a wxPaintDC if you define an OnPaint handler, even if you do not
275 actually use this device context, or painting will not work correctly under Windows.
276
277 If you used device context functions with wxPoint or wxIntPoint before, please note
278 that wxPoint now contains integer members, and there is a new class wxRealPoint. wxIntPoint
279 no longer exists.
280
281 \chapter{Miscellaneous}
282
283 \section{Strings}
284
285 wxString has replaced char* in the majority of cases. For passing strings into functions,
286 this should not normally require you to change your code if the syntax is otherwise the
287 same. This is because C++ will automatically convert a char* or const char* to a wxString by virtue
288 of appropriate wxString constructors.
289
290 However, when a wxString is returned from a function in wxWindows 2.0 where a char* was
291 returned in wxWindows 1.xx, your application will need to be changed. Usually you can
292 simplify your application's allocation and deallocation of memory for the returned string,
293 and simply assign the result to a wxString object. For example, replace this:
294
295 {\small\begin{verbatim}
296 char* s = wxFunctionThatReturnsString();
297 s = copystring(s); // Take a copy in case it's temporary
298 .... // Do something with it
299 delete[] s;
300 \end{verbatim}
301 }
302
303 with this:
304
305 {\small\begin{verbatim}
306 wxString s = wxFunctionThatReturnsString();
307 .... // Do something with it
308 \end{verbatim}
309 }
310
311 To indicate an empty return value or a problem, a function may return either the
312 empty string (``") or a null string. You can check for a null string with wxString::IsNull().
313
314 \section{Use of const}
315
316 The {\bf const} keyword is now used to denote constant functions that do not affect the
317 object, and for function arguments to denote that the object passed cannot be changed.
318
319 This should not affect your application except for where you are overriding virtual functions
320 which now have a different signature. If functions are not being called which were previously,
321 check whether there is a parameter mismatch (or function type mismatch) involving consts.
322
323 Try to use the {\bf const} keyword in your own code where possible.
324
325 \chapter{Backward compatibility}\label{compat}
326
327 Some wxWindows 1.xx functionality has been left to ease the transition to 2.0. This functionality
328 (usually) only works if you compile with WXWIN\_COMPATIBILITY set to 1.
329
330 TODO
331
332 OnMenuCommand, OnSize, OnActivate, OnPaint, others?? can all be prefixed with Old (e.g. OldOnMenuCommand)
333 and will work as before. You are encouraged to convert your code to the new forms, but
334 this will allow you to get your applications up and running a little more quickly.
335
336 OnClose can be used as-is without an 'Old' prefix, but officially the OnCloseWindow event table handler should be
337 used instead.
338
339 \chapter{Quick reference}\label{quickreference}
340
341 This section allows you to quickly find features that
342 need to be converted.
343
344 TODO
345
346 \section{OnActivate}
347
348 Rename to OldOnActivate, or replace arguments with one wxActivateEvent\& argument.
349
350 \wxheading{See also}
351
352 \helpref{Backward compatibility}{compat}
353
354 \section{OnClose}
355
356 This can either remain the same as before, or you can add an OnCloseWindow event
357 handler using an EVT\_CLOSE event table entry.
358
359 \wxheading{See also}
360
361 \helpref{Backward compatibility}{compat}
362
363 \section{OnMenuCommand}
364
365 Rename to OldOnMenuCommand, or replace with a series of functions, one for
366 each case of your old switch statement. Create an event table for your frame
367 containing EVT\_MENU macros, and insert DECLARE\_EVENT\_TABLE() in your frame class.
368
369 \wxheading{See also}
370
371 \helpref{Backward compatibility}{compat}
372
373 \section{OnSize}
374
375 Rename to OldOnSize, or replace arguments with one wxSizeEvent\& argument.
376
377 \wxheading{See also}
378
379 \helpref{Backward compatibility}{compat}
380
381 \section{wxDialog::Show}
382
383 If you used {\bf Show} to show a modal dialog, or to override the standard
384 modal dialog {\bf Show}, use {\bf ShowModal} instead.
385
386 \wxheading{See also}
387
388 \helpref{Dialogs and controls}{dialogscontrols}
389
390 \end{document}