1\chapter{Porting from wxWidgets 1.xx}\label{porting} 2 3This addendum gives guidelines and tips for porting applications from 4version 1.xx of wxWidgets to version 2.0. 5 6The first section offers tips for writing 1.xx applications in a way to 7minimize porting time. The following sections detail the changes and 8how you can modify your application to be 2.0-compliant. 9 10You may be worrying that porting to 2.0 will be a lot of work, 11particularly if you have only recently started using 1.xx. In fact, 12the wxWidgets 2.0 API has far more in common with 1.xx than it has differences. 13The main challenges are using the new event system, doing without the default 14panel item layout, and the lack of automatic labels in some controls. 15 16Please don't be freaked out by the jump to 2.0! For one thing, 1.xx is still available 17and will be supported by the user community for some time. And when you have 18changed to 2.0, we hope that you will appreciate the benefits in terms 19of greater flexibility, better user interface aesthetics, improved C++ conformance, 20improved compilation speed, and many other enhancements. The revised architecture 21of 2.0 will ensure that wxWidgets can continue to evolve for the foreseeable 22future. 23 24{\it Please note that this document is a work in progress.} 25 26\section{Preparing for version 2.0}\label{portingpreparing} 27 28Even before compiling with version 2.0, there's also a lot you can do right now to make porting 29relatively simple. Here are a few tips. 30 31\begin{itemize} 32\item {\bf Use constraints or .wxr resources} for layout, rather than the default layout scheme. 33Constraints should be the same in 2.0, and resources will be translated. 34\item {\bf Use separate wxMessage items} instead of labels for wxText, wxMultiText, 35wxChoice, wxComboBox. These labels will disappear in 2.0. Use separate 36wxMessages whether you're creating controls programmatically or using 37the dialog editor. The future dialog editor will be able to translate 38from old to new more accurately if labels are separated out. 39\item {\bf Parameterise functions that use wxDC} or derivatives, i.e. make the wxDC 40an argument to all functions that do drawing. Minimise the use of 41wxWindow::GetDC and definitely don't store wxDCs long-term 42because in 2.0, you can't use GetDC() and wxDCs are not persistent. 43You will use wxClientDC, wxPaintDC stack objects instead. Minimising 44the use of GetDC() will ensure that there are very few places you 45have to change drawing code for 2.0. 46\item {\bf Don't set GDI objects} (wxPen, wxBrush etc.) in windows or wxCanvasDCs before they're 47needed (e.g. in constructors) - do so within your drawing routine instead. In 482.0, these settings will only take effect between the construction and destruction 49of temporary wxClient/PaintDC objects. 50\item {\bf Don't rely} on arguments to wxDC functions being floating point - they will 51be 32-bit integers in 2.0. 52\item {\bf Don't use the wxCanvas member functions} that duplicate wxDC functions, such as SetPen and DrawLine, since 53they are going. 54\item {\bf Using member callbacks} called from global callback functions will make the transition 55easier - see the FAQ 56for some notes on using member functions for callbacks. wxWidgets 2.0 will banish global 57callback functions (and OnMenuCommand), and nearly all event handling will be done by functions taking a single event argument. 58So in future you will have code like: 59 60{\small 61\begin{verbatim} 62void MyFrame::OnOK(wxCommandEvent& event) 63{ 64 ... 65} 66\end{verbatim} 67}% 68 69You may find that writing the extra code to call a member function isn't worth it at this stage, 70but the option is there. 71\item {\bf Use wxString wherever possible.} 2.0 replaces char * with wxString 72in most cases, and if you use wxString to receive strings returned from 73wxWidgets functions (except when you need to save the pointer if deallocation is required), there should 74be no conversion problems later on. 75\item Be aware that under Windows, {\bf font sizes will change} to match standard Windows 76font sizes (for example, a 12-point font will appear bigger than before). Write your application 77to be flexible where fonts are concerned. 78Don't rely on fonts being similarly-sized across platforms, as they were (by chance) between 79Windows and X under wxWidgets 1.66. Yes, this is not easy... but I think it is better to conform to the 80standards of each platform, and currently the size difference makes it difficult to 81conform to Windows UI standards. You may eventually wish to build in a global 'fudge-factor' to compensate 82for size differences. The old font sizing will still be available via wx\_setup.h, so do not panic... 83\item {\bf Consider dropping wxForm usage}: 84wxPropertyFormView can be used in a wxForm-like way, except that you specify a pre-constructed panel 85or dialog; or you can use a wxPropertyListView to show attributes in a scrolling list - you don't even need 86to lay panel items out. 87 88Because wxForm uses a number of features to be dropped in wxWidgets 2.0, it cannot be 89supported in the future, at least in its present state. 90\item {\bf When creating a wxListBox}, put the wxLB\_SINGLE, wxLB\_MULTIPLE, wxLB\_EXTENDED styles in the window style parameter, and put 91zero in the {\it multiple} parameter. The {\it multiple} parameter will be removed in 2.0. 92\item {\bf For MDI applications}, don't reply on MDI being run-time-switchable in the way that the 93MDI sample is. In wxWidgets 2.0, MDI functionality is separated into distinct classes. 94\end{itemize} 95 96\section{The new event system}\label{portingeventsystem} 97 98The way that events are handled has been radically changed in wxWidgets 2.0. Please 99read the topic `Event handling overview' in the wxWidgets 2.0 manual for background 100on this. 101 102\subsection{Callbacks} 103 104Instead of callbacks for panel items, menu command events, control commands and other events are directed to 105the originating window, or an ancestor, or an event handler that has been plugged into the window 106or its ancestor. Event handlers always have one argument, a derivative of wxEvent. 107 108For menubar commands, the {\bf OnMenuCommand} member function will be replaced by a series of separate member functions, 109each of which responds to a particular command. You need to add these (non-virtual) functions to your 110frame class, add a DECLARE\_EVENT\_TABLE entry to the class, and then add an event table to 111your implementation file, as a BEGIN\_EVENT\_TABLE and END\_EVENT\_TABLE block. The 112individual event mapping macros will be of the form: 113 114\begin{verbatim} 115BEGIN_EVENT_TABLE(MyFrame, wxFrame) 116 EVT_MENU(MYAPP_NEW, MyFrame::OnNew) 117 EVT_MENU(wxID_EXIT, MyFrame::OnExit) 118END_EVENT_TABLE() 119\end{verbatim} 120 121Control commands, such as button commands, can be routed to a derived button class, 122the parent window, or even the frame. Here, you use a function of the form EVT\_BUTTON(id, func). 123Similar macros exist for other control commands. 124 125\subsection{Other events} 126 127To intercept other events, you used to override virtual functions, such as OnSize. Now, while you can use 128the OnSize name for such event handlers (or any other name of your choice), it has only a single argument 129(wxSizeEvent) and must again be `mapped' using the EVT\_SIZE macro. The same goes for all other events, 130including OnClose (although in fact you can still use the old, virtual form of OnClose for the time being). 131 132\section{Class hierarchy}\label{portingclasshierarchy} 133 134The class hierarchy has changed somewhat. wxToolBar and wxButtonBar 135classes have been split into several classes, and are derived from wxControl (which was 136called wxItem). wxPanel derives from wxWindow instead of from wxCanvas, which has 137disappeared in favour of wxScrolledWindow (since all windows are now effectively canvases 138which can be drawn into). The status bar has become a class in its own right, wxStatusBar. 139 140There are new MDI classes so that wxFrame does not have to be overloaded with this 141functionality. 142 143There are new device context classes, with wxPanelDC and wxCanvasDC disappearing. 144See \helpref{Device contexts and painting}{portingdc}. 145 146\section{GDI objects}\label{portinggdiobjects} 147 148These objects - instances of classes such as wxPen, wxBrush, wxBitmap (but not wxColour) - 149are now implemented with reference-counting. This makes assignment a very cheap operation, 150and also means that management of the resource is largely automatic. You now pass {\it references} to 151objects to functions such as wxDC::SetPen, not pointers, so you will need to dereference your pointers. 152The device context does not store a copy of the pen 153itself, but takes a copy of it (via reference counting), and the object's data gets freed up 154when the reference count goes to zero. The application does not have to worry so much about 155who the object belongs to: it can pass the reference, then destroy the object without 156leaving a dangling pointer inside the device context. 157 158For the purposes of code migration, you can use the old style of object management - maintaining 159pointers to GDI objects, and using the FindOrCreate... functions. However, it is preferable to 160keep this explicit management to a minimum, instead creating objects on the fly as needed, on the stack, 161unless this causes too much of an overhead in your application. 162 163At a minimum, you will have to make sure that calls to SetPen, SetBrush etc. work. Also, where you pass NULL to these 164functions, you will need to use an identifier such as wxNullPen or wxNullBrush. 165 166\section{Dialogs and controls}\label{portingdialogscontrols} 167 168\wxheading{Labels} 169 170Most controls no longer have labels and values as they used to in 1.xx. Instead, labels 171should be created separately using wxStaticText (the new name for wxMessage). This will 172need some reworking of dialogs, unfortunately; programmatic dialog creation that doesn't 173use constraints will be especially hard-hit. Perhaps take this opportunity to make more 174use of dialog resources or constraints. Or consider using the wxPropertyListView class 175which can do away with dialog layout issues altogether by presenting a list of editable 176properties. 177 178\wxheading{Constructors} 179 180All window constructors have two main changes, apart from the label issue mentioned above. 181Windows now have integer identifiers; and position and size are now passed as wxPoint and 182wxSize objects. In addition, some windows have a wxValidator argument. 183 184\wxheading{Show versus ShowModal} 185 186If you have used or overridden the {\bf wxDialog::Show} function in the past, you may find 187that modal dialogs no longer work as expected. This is because the function for modal showing 188is now {\bf wxDialog:ShowModal}. This is part of a more fundamental change in which a 189control may tell the dialog that it caused the dismissal of a dialog, by 190calling {\bf wxDialog::EndModal} or {\bf wxWindow::SetReturnCode}. Using this 191information, {\bf ShowModal} now returns the id of the control that caused dismissal, 192giving greater feedback to the application than just true or false. 193 194If you overrode or called {\bf wxDialog::Show}, use {\bf ShowModal} and test for a returned identifier, 195commonly wxID\_OK or wxID\_CANCEL. 196 197\wxheading{wxItem} 198 199This is renamed wxControl. 200 201\wxheading{wxText, wxMultiText and wxTextWindow} 202 203These classes no longer exist and are replaced by the single class wxTextCtrl. 204Multi-line text items are created using the wxTE\_MULTILINE style. 205 206\wxheading{wxButton} 207 208Bitmap buttons are now a separate class, instead of being part of wxBitmap. 209 210\wxheading{wxMessage} 211 212Bitmap messages are now a separate class, wxStaticBitmap, and wxMessage 213is renamed wxStaticText. 214 215\wxheading{wxGroupBox} 216 217wxGroupBox is renamed wxStaticBox. 218 219\wxheading{wxForm} 220 221Note that wxForm is no longer supported in wxWidgets 2.0. Consider using the wxPropertyFormView class 222instead, which takes standard dialogs and panels and associates controls with property objects. 223You may also find that the new validation method, combined with dialog resources, is easier 224and more flexible than using wxForm. 225 226\section{Device contexts and painting}\label{portingdc} 227 228In wxWidgets 2.0, device contexts are used for drawing into, as per 1.xx, but the way 229they are accessed and constructed is a bit different. 230 231You no longer use {\bf GetDC} to access device contexts for panels, dialogs and canvases. 232Instead, you create a temporary device context, which means that any window or control can be drawn 233into. The sort of device context you create depends on where your code is called from. If 234painting within an {\bf OnPaint} handler, you create a wxPaintDC. If not within an {\bf OnPaint} handler, 235you use a wxClientDC or wxWindowDC. You can still parameterise your drawing code so that it 236doesn't have to worry about what sort of device context to create - it uses the DC it is passed 237from other parts of the program. 238 239You {\bf must } create a wxPaintDC if you define an OnPaint handler, even if you do not 240actually use this device context, or painting will not work correctly under Windows. 241 242If you used device context functions with wxPoint or wxIntPoint before, please note 243that wxPoint now contains integer members, and there is a new class wxRealPoint. wxIntPoint 244no longer exists. 245 246wxMetaFile and wxMetaFileDC have been renamed to wxMetafile and wxMetafileDC. 247 248\section{Miscellaneous} 249 250\subsection{Strings} 251 252wxString has replaced char* in the majority of cases. For passing strings into functions, 253this should not normally require you to change your code if the syntax is otherwise the 254same. This is because C++ will automatically convert a char* or const char* to a wxString by virtue 255of appropriate wxString constructors. 256 257However, when a wxString is returned from a function in wxWidgets 2.0 where a char* was 258returned in wxWidgets 1.xx, your application will need to be changed. Usually you can 259simplify your application's allocation and deallocation of memory for the returned string, 260and simply assign the result to a wxString object. For example, replace this: 261 262{\small 263\begin{verbatim} 264 char* s = wxFunctionThatReturnsString(); 265 s = copystring(s); // Take a copy in case it is temporary 266 .... // Do something with it 267 delete[] s; 268\end{verbatim} 269} 270 271with this: 272 273{\small 274\begin{verbatim} 275 wxString s = wxFunctionThatReturnsString(); 276 .... // Do something with it 277\end{verbatim} 278} 279 280To indicate an empty return value or a problem, a function may return either the 281empty string (``") or a null string. You can check for a null string with wxString::IsNull(). 282 283\subsection{Use of const} 284 285The {\bf const} keyword is now used to denote constant functions that do not affect the 286object, and for function arguments to denote that the object passed cannot be changed. 287 288This should not affect your application except for where you are overriding virtual functions 289which now have a different signature. If functions are not being called which were previously, 290check whether there is a parameter mismatch (or function type mismatch) involving consts. 291 292Try to use the {\bf const} keyword in your own code where possible. 293 294\section{Backward compatibility}\label{portingcompat} 295 296Some wxWidgets 1.xx functionality has been left to ease the transition to 2.0. This functionality 297(usually) only works if you compile with WXWIN\_COMPATIBILITY set to 1 in setup.h. 298 299Mostly this defines old names to be the new names (e.g. wxRectangle is defined to be wxRect). 300 301\section{Quick reference}\label{portingquickreference} 302 303This section allows you to quickly find features that 304need to be converted. 305 306\subsection{Include files} 307 308Use the form: 309 310\begin{verbatim} 311#include <wx/wx.h> 312#include <wx/button.h> 313\end{verbatim} 314 315For precompiled header support, use this form: 316 317\begin{verbatim} 318// For compilers that support precompilation, includes "wx.h". 319#include <wx/wxprec.h> 320 321#ifdef __BORLANDC__ 322 #pragma hdrstop 323#endif 324 325// Any files you want to include if not precompiling by including 326// the whole of <wx/wx.h> 327#ifndef WX_PRECOMP 328 #include <stdio.h> 329 #include <wx/setup.h> 330 #include <wx/bitmap.h> 331 #include <wx/brush.h> 332#endif 333 334// Any files you want to include regardless of precompiled headers 335#include <wx/toolbar.h> 336\end{verbatim} 337 338\subsection{IPC classes} 339 340These are now separated out into wxDDEServer/Client/Connection (Windows only) and wxTCPServer/Client/Connection 341(Windows and Unix). Take care to use wxString for your overridden function arguments, instead of char*, as per 342the documentation. 343 344\subsection{MDI style frames} 345 346MDI is now implemented as a family of separate classes, so you can't switch to MDI just by 347using a different frame style. Please see the documentation for the MDI frame classes, and the MDI 348sample may be helpful too. 349 350\subsection{OnActivate} 351 352Replace the arguments with one wxActivateEvent\& argument, make sure the function isn't virtual, 353and add an EVT\_ACTIVATE event table entry. 354 355\subsection{OnChar} 356 357This is now a non-virtual function, with the same wxKeyEvent\& argument as before. 358Add an EVT\_CHAR macro to the event table 359for your window, and the implementation of your function will need very few changes. 360 361\subsection{OnClose} 362 363The old virtual function OnClose is now obsolete. 364Add an OnCloseWindow event handler using an EVT\_CLOSE event table entry. For details 365about window destruction, see the Windows Deletion Overview in the manual. This is a subtle 366topic so please read it very carefully. Basically, OnCloseWindow is now responsible for 367destroying a window with Destroy(), but the default implementation (for example for wxDialog) may not 368destroy the window, so to be sure, always provide this event handler so it is obvious what's going on. 369 370\subsection{OnEvent} 371 372This is now a non-virtual function, with the same wxMouseEvent\& argument as before. However 373you may wish to rename it OnMouseEvent. Add an EVT\_MOUSE\_EVENTS macro to the event table 374for your window, and the implementation of your function will need very few changes. 375However, if you wish to intercept different events using different functions, you can 376specify specific events in your event table, such as EVT\_LEFT\_DOWN. 377 378Your OnEvent function is likely to have references to GetDC(), so make sure you create 379a wxClientDC instead. See \helpref{Device contexts}{portingdc}. 380 381If you are using a wxScrolledWindow (formerly wxCanvas), you should call 382PrepareDC(dc) to set the correct translation for the current scroll position. 383 384\subsection{OnMenuCommand} 385 386You need to replace this virtual function with a series of non-virtual functions, one for 387each case of your old switch statement. Each function takes a wxCommandEvent\& argument. 388Create an event table for your frame 389containing EVT\_MENU macros, and insert DECLARE\_EVENT\_TABLE() in your frame class, as 390per the samples. 391 392\subsection{OnPaint} 393 394This is now a non-virtual function, with a wxPaintEvent\& argument. 395Add an EVT\_PAINT macro to the event table 396for your window. 397 398Your function {\it must} create a wxPaintDC object, instead of using GetDC to 399obtain the device context. 400 401If you are using a wxScrolledWindow (formerly wxCanvas), you should call 402PrepareDC(dc) to set the correct translation for the current scroll position. 403 404\subsection{OnSize} 405 406Replace the arguments with one wxSizeEvent\& argument, make it non-virtual, and add to your 407event table using EVT\_SIZE. 408 409\subsection{wxApp definition} 410 411The definition of OnInit has changed. Return a bool value, not a wxFrame. 412 413Also, do {\it not} declare a global application object. Instead, use the macros 414DECLARE\_APP and IMPLEMENT\_APP as per the samples. Remove any occurrences of IMPLEMENT\_WXWIN\_MAIN: 415this is subsumed in IMPLEMENT\_APP. 416 417\subsection{wxButton} 418 419For bitmap buttons, use wxBitmapButton. 420 421\subsection{wxCanvas} 422 423Change the name to wxScrolledWindow. 424 425\subsection{wxDialogBox} 426 427Change the name to wxDialog, and for modal dialogs, use ShowModal instead of Show. 428 429\subsection{wxDialog::Show} 430 431If you used {\bf Show} to show a modal dialog or to override the standard 432modal dialog {\bf Show}, use {\bf ShowModal} instead. 433 434\wxheading{See also} 435 436\helpref{Dialogs and controls}{portingdialogscontrols} 437 438\subsection{wxForm} 439 440Sorry, this class is no longer available. Try using the wxPropertyListView or wxPropertyFormView class 441instead, or use .wxr files and validators. 442 443\subsection{wxPoint} 444 445The old wxPoint is called wxRealPoint, and wxPoint now uses integers. 446 447\subsection{wxRectangle} 448 449This is now called wxRect. 450 451\subsection{wxScrollBar} 452 453The function names have changed for this class: please refer to the documentation for wxScrollBar. Instead 454of setting properties individually, you will call SetScrollbar with several parameters. 455 456\subsection{wxText, wxMultiText, wxTextWindow} 457 458Change all these to wxTextCtrl. Add the window style wxTE\_MULTILINE if you 459wish to have a multi-line text control. 460 461\subsection{wxToolBar} 462 463This name is an alias for the most popular form of toolbar for your platform. There is now a family 464of toolbar classes, with for example wxToolBar95, wxToolBarMSW and wxToolBarSimple classes existing 465under Windows 95. 466 467Toolbar management is supported by frames, so calling wxFrame::CreateToolBar and adding tools is usually 468enough, and the SDI or MDI frame will manage the positioning for you. The client area of the frame is the space 469left over when the menu bar, toolbar and status bar have been taken into account. 470 471