\chapter{Porting from wxWidgets 1.xx}\label{porting}This addendum gives guidelines and tips for porting applications fromversion 1.xx of wxWidgets to version 2.0.The first section offers tips for writing 1.xx applications in a way tominimize porting time. The following sections detail the changes andhow you can modify your application to be 2.0-compliant.You may be worrying that porting to 2.0 will be a lot of work,particularly if you have only recently started using 1.xx. In fact,the wxWidgets 2.0 API has far more in common with 1.xx than it has differences.The main challenges are using the new event system, doing without the defaultpanel item layout, and the lack of automatic labels in some controls.Please don't be freaked out by the jump to 2.0! For one thing, 1.xx is still availableand will be supported by the user community for some time. And when you havechanged to 2.0, we hope that you will appreciate the benefits in termsof greater flexibility, better user interface aesthetics, improved C++ conformance,improved compilation speed, and many other enhancements. The revised architectureof 2.0 will ensure that wxWidgets can continue to evolve for the foreseeablefuture.{\it Please note that this document is a work in progress.}\section{Preparing for version 2.0}\label{portingpreparing}Even before compiling with version 2.0, there's also a lot you can do right now to make portingrelatively simple. Here are a few tips.\begin{itemize}\item {\bf Use constraints or .wxr resources} for layout, rather than the default layout scheme.Constraints should be the same in 2.0, and resources will be translated.\item {\bf Use separate wxMessage items} instead of labels for wxText, wxMultiText,wxChoice, wxComboBox. These labels will disappear in 2.0. Use separatewxMessages whether you're creating controls programmatically or usingthe dialog editor. The future dialog editor will be able to translatefrom old to new more accurately if labels are separated out.\item {\bf Parameterise functions that use wxDC} or derivatives, i.e. make the wxDCan argument to all functions that do drawing. Minimise the use ofwxWindow::GetDC and definitely don't store wxDCs long-termbecause in 2.0, you can't use GetDC() and wxDCs are not persistent.You will use wxClientDC, wxPaintDC stack objects instead. Minimisingthe use of GetDC() will ensure that there are very few places youhave to change drawing code for 2.0.\item {\bf Don't set GDI objects} (wxPen, wxBrush etc.) in windows or wxCanvasDCs before they'reneeded (e.g. in constructors) - do so within your drawing routine instead. In2.0, these settings will only take effect between the construction and destructionof temporary wxClient/PaintDC objects.\item {\bf Don't rely} on arguments to wxDC functions being floating point - they willbe 32-bit integers in 2.0.\item {\bf Don't use the wxCanvas member functions} that duplicate wxDC functions, such as SetPen and DrawLine, sincethey are going.\item {\bf Using member callbacks} called from global callback functions will make the transitioneasier - see the FAQfor some notes on using member functions for callbacks. wxWidgets 2.0 will banish globalcallback functions (and OnMenuCommand), and nearly all event handling will be done by functions taking a single event argument.So in future you will have code like:{\small\begin{verbatim}void MyFrame::OnOK(wxCommandEvent& event){        ...}\end{verbatim}}%You may find that writing the extra code to call a member function isn't worth it at this stage,but the option is there.\item {\bf Use wxString wherever possible.} 2.0 replaces char * with wxStringin most cases, and if you use wxString to receive strings returned fromwxWidgets functions (except when you need to save the pointer if deallocation is required), there shouldbe no conversion problems later on.\item Be aware that under Windows, {\bf font sizes will change} to match standard Windowsfont sizes (for example, a 12-point font will appear bigger than before). Write your applicationto be flexible where fonts are concerned.Don't rely on fonts being similarly-sized across platforms, as they were (by chance) betweenWindows and X under wxWidgets 1.66. Yes, this is not easy... but I think it is better to conform to thestandards of each platform, and currently the size difference makes it difficult toconform to Windows UI standards. You may eventually wish to build in a global 'fudge-factor' to compensatefor size differences. The old font sizing will still be available via wx\_setup.h, so do not panic...\item {\bf Consider dropping wxForm usage}:wxPropertyFormView can be used in a wxForm-like way, except that you specify a pre-constructed panelor dialog; or you can use a wxPropertyListView to show attributes in a scrolling list - you don't even needto lay panel items out.Because wxForm uses a number of features to be dropped in wxWidgets 2.0, it cannot besupported in the future, at least in its present state.\item {\bf When creating a wxListBox}, put the wxLB\_SINGLE, wxLB\_MULTIPLE, wxLB\_EXTENDED styles in the window style parameter, and putzero in the {\it multiple} parameter. The {\it multiple} parameter will be removed in 2.0.\item {\bf For MDI applications}, don't reply on MDI being run-time-switchable in the way that theMDI sample is. In wxWidgets 2.0, MDI functionality is separated into distinct classes.\end{itemize}\section{The new event system}\label{portingeventsystem}The way that events are handled has been radically changed in wxWidgets 2.0. Pleaseread the topic `Event handling overview' in the wxWidgets 2.0 manual for backgroundon this.\subsection{Callbacks}Instead of callbacks for panel items, menu command events, control commands and other events are directed tothe originating window, or an ancestor, or an event handler that has been plugged into the windowor its ancestor. Event handlers always have one argument, a derivative of wxEvent.For menubar commands, the {\bf OnMenuCommand} member function will be replaced by a series of separate member functions,each of which responds to a particular command. You need to add these (non-virtual) functions to yourframe class, add a DECLARE\_EVENT\_TABLE entry to the class, and then add an event table toyour implementation file, as a BEGIN\_EVENT\_TABLE and END\_EVENT\_TABLE block. Theindividual event mapping macros will be of the form:\begin{verbatim}BEGIN_EVENT_TABLE(MyFrame, wxFrame)    EVT_MENU(MYAPP_NEW, MyFrame::OnNew)    EVT_MENU(wxID_EXIT, MyFrame::OnExit)END_EVENT_TABLE()\end{verbatim}Control commands, such as button commands, can be routed to a derived button class,the parent window, or even the frame. Here, you use a function of the form EVT\_BUTTON(id, func).Similar macros exist for other control commands.\subsection{Other events}To intercept other events, you used to override virtual functions, such as OnSize. Now, while you can usethe OnSize name for such event handlers (or any other name of your choice), it has only a single argument(wxSizeEvent) and must again be `mapped' using the EVT\_SIZE macro. The same goes for all other events,including OnClose (although in fact you can still use the old, virtual form of OnClose for the time being).\section{Class hierarchy}\label{portingclasshierarchy}The class hierarchy has changed somewhat. wxToolBar and wxButtonBarclasses have been split into several classes, and are derived from wxControl (which wascalled wxItem). wxPanel derives from wxWindow instead of from wxCanvas, which hasdisappeared in favour of wxScrolledWindow (since all windows are now effectively canvaseswhich can be drawn into). The status bar has become a class in its own right, wxStatusBar.There are new MDI classes so that wxFrame does not have to be overloaded with thisfunctionality.There are new device context classes, with wxPanelDC and wxCanvasDC disappearing.See \helpref{Device contexts and painting}{portingdc}.\section{GDI objects}\label{portinggdiobjects}These objects - instances of classes such as wxPen, wxBrush, wxBitmap (but not wxColour) -are now implemented with reference-counting. This makes assignment a very cheap operation,and also means that management of the resource is largely automatic. You now pass {\it references} toobjects to functions such as wxDC::SetPen, not pointers, so you will need to dereference your pointers.The device context does not store a copy of the penitself, but takes a copy of it (via reference counting), and the object's data gets freed upwhen the reference count goes to zero. The application does not have to worry so much aboutwho the object belongs to: it can pass the reference, then destroy the object withoutleaving a dangling pointer inside the device context.For the purposes of code migration, you can use the old style of object management - maintainingpointers to GDI objects, and using the FindOrCreate... functions. However, it is preferable tokeep this explicit management to a minimum, instead creating objects on the fly as needed, on the stack,unless this causes too much of an overhead in your application.At a minimum, you will have to make sure that calls to SetPen, SetBrush etc. work. Also, where you pass NULL to thesefunctions, you will need to use an identifier such as wxNullPen or wxNullBrush.\section{Dialogs and controls}\label{portingdialogscontrols}\wxheading{Labels}Most controls no longer have labels and values as they used to in 1.xx. Instead, labelsshould be created separately using wxStaticText (the new name for wxMessage). This willneed some reworking of dialogs, unfortunately; programmatic dialog creation that doesn'tuse constraints will be especially hard-hit. Perhaps take this opportunity to make moreuse of dialog resources or constraints. Or consider using the wxPropertyListView classwhich can do away with dialog layout issues altogether by presenting a list of editableproperties.\wxheading{Constructors}All window constructors have two main changes, apart from the label issue mentioned above.Windows now have integer identifiers; and position and size are now passed as wxPoint andwxSize objects. In addition, some windows have a wxValidator argument.\wxheading{Show versus ShowModal}If you have used or overridden the {\bf wxDialog::Show} function in the past, you may findthat modal dialogs no longer work as expected. This is because the function for modal showingis now {\bf wxDialog:ShowModal}. This is part of a more fundamental change in which acontrol may tell the dialog that it caused the dismissal of a dialog, bycalling {\bf wxDialog::EndModal} or {\bf wxWindow::SetReturnCode}. Using thisinformation, {\bf ShowModal} now returns the id of the control that caused dismissal,giving greater feedback to the application than just true or false.If you overrode or called {\bf wxDialog::Show}, use {\bf ShowModal} and test for a returned identifier,commonly wxID\_OK or wxID\_CANCEL.\wxheading{wxItem}This is renamed wxControl.\wxheading{wxText, wxMultiText and wxTextWindow}These classes no longer exist and are replaced by the single class wxTextCtrl.Multi-line text items are created using the wxTE\_MULTILINE style.\wxheading{wxButton}Bitmap buttons are now a separate class, instead of being part of wxBitmap.\wxheading{wxMessage}Bitmap messages are now a separate class, wxStaticBitmap, and wxMessageis renamed wxStaticText.\wxheading{wxGroupBox}wxGroupBox is renamed wxStaticBox.\wxheading{wxForm}Note that wxForm is no longer supported in wxWidgets 2.0. Consider using the wxPropertyFormView classinstead, which takes standard dialogs and panels and associates controls with property objects.You may also find that the new validation method, combined with dialog resources, is easierand more flexible than using wxForm.\section{Device contexts and painting}\label{portingdc}In wxWidgets 2.0, device contexts are used for drawing into, as per 1.xx, but the waythey are accessed and constructed is a bit different.You no longer use {\bf GetDC} to access device contexts for panels, dialogs and canvases.Instead, you create a temporary device context, which means that any window or control can be drawninto. The sort of device context you create depends on where your code is called from. Ifpainting within an {\bf OnPaint} handler, you create a wxPaintDC. If not within an {\bf OnPaint} handler,you use a wxClientDC or wxWindowDC. You can still parameterise your drawing code so that itdoesn't have to worry about what sort of device context to create - it uses the DC it is passed