-\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
-\newcommand{\indexit}[1]{#1\index{#1}}%
-\newcommand{\pipe}[0]{$\|$\ }%
-\definecolour{black}{0}{0}{0}%
-\definecolour{cyan}{0}{255}{255}%
-\definecolour{green}{0}{255}{0}%
-\definecolour{magenta}{255}{0}{255}%
-\definecolour{red}{255}{0}{0}%
-\definecolour{blue}{0}{0}{200}%
-\definecolour{yellow}{255}{255}{0}%
-\definecolour{white}{255}{255}{255}%
-\input psbox.tex
-\parskip=10pt
-\parindent=0pt
-\title{Guide to porting applications from wxWindows 1.xx to 2.0}
-\author{Julian Smart}
-\date{March 1999}
-\makeindex
-\begin{document}
-\maketitle
-\pagestyle{fancyplain}
-\bibliographystyle{plain}
-\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
-\setfooter{\thepage}{}{}{}{}{\thepage}%
-\pagenumbering{roman}
-\tableofcontents
-%
-\chapter{About this document}\label{about}
-\pagenumbering{arabic}%
-\setheader{{\it Porting guide}}{}{}{}{}{{\it Porting guide}}%
-\setfooter{\thepage}{}{}{}{}{\thepage}%
-
-This document gives guidelines and tips for porting applications from
-version 1.xx of wxWindows to version 2.0.
-
-The first section offers tips for writing 1.xx applications in a way to
-minimize porting time. The following sections detail the changes and
-how 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 wxWindows 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 default
-panel 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 available
-and will be supported by the user community for some time. And when you have
-changed to 2.0, we hope that you will appreciate the benefits in terms
-of greater flexibility, better user interface aesthetics, improved C++ conformance,
-improved compilation speed, and many other enhancements. The revised architecture
-of 2.0 will ensure that wxWindows can continue to evolve for the forseeable
-future.
-
-{\it Please note that this document is a work in progress.}
-
-\chapter{Preparing for version 2.0}\label{preparing}
-
-Even before compiling with version 2.0, there's also a lot you can do right now to make porting
-relatively 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 separate
-wxMessages whether you're creating controls programmatically or using
-the dialog editor. The future dialog editor will be able to translate
-from old to new more accurately if labels are separated out.
-\item {\bf Parameterise functions that use wxDC} or derivatives, i.e. make the wxDC
-an argument to all functions that do drawing. Minimise the use of
-wxWindow::GetDC and definitely don't store wxDCs long-term
-because in 2.0, you can't use GetDC() and wxDCs are not persistent.
-You will use wxClientDC, wxPaintDC stack objects instead. Minimising
-the use of GetDC() will ensure that there are very few places you
-have to change drawing code for 2.0.
-\item {\bf Don't set GDI objects} (wxPen, wxBrush etc.) in windows or wxCanvasDCs before they're
-needed (e.g. in constructors) - do so within your drawing routine instead. In
-2.0, these settings will only take effect between the construction and destruction
-of temporary wxClient/PaintDC objects.
-\item {\bf Don't rely} on arguments to wxDC functions being floating point - they will
-be 32-bit integers in 2.0.
-\item {\bf Don't use the wxCanvas member functions} that duplicate wxDC functions, such as SetPen and DrawLine, since
-they are going.
-\item {\bf Using member callbacks} called from global callback functions will make the transition
-easier - see the FAQ
-for some notes on using member functions for callbacks. wxWindows 2.0 will banish global
-callback 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 wxString
-in most cases, and if you use wxString to receive strings returned from
-wxWindows functions (except when you need to save the pointer if deallocation is required), there should
-be no conversion problems later on.
-\item Be aware that under Windows, {\bf font sizes will change} to match standard Windows
-font sizes (for example, a 12-point font will appear bigger than before). Write your application
-to be flexible where fonts are concerned.
-Don't rely on fonts being similarly-sized across platforms, as they were (by chance) between
-Windows and X under wxWindows 1.66. Yes, this is not easy... but I think it's better to conform to the
-standards of each platform, and currently the size difference makes it difficult to
-conform to Windows UI standards. You may eventually wish to build in a global 'fudge-factor' to compensate
-for 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 panel
-or dialog; or you can use a wxPropertyListView to show attributes in a scrolling list - you don't even need
-to lay panel items out.
-
-Because wxForm uses a number of features to be dropped in wxWindows 2.0, it cannot be
-supported 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 put
-zero 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 the
-MDI sample is. In wxWindows 2.0, MDI functionality is separated into distinct classes.
-\end{itemize}
-
-\chapter{The new event system}\label{eventsystem}
-
-The way that events are handled has been radically changed in wxWindows 2.0. Please
-read the topic `Event handling overview' in the wxWindows 2.0 manual for background
-on this.
-
-\section{Callbacks}
-
-Instead of callbacks for panel items, menu command events, control commands and other events are directed to
-the originating window, or an ancestor, or an event handler that has been plugged into the window
-or 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 your
-frame class, add a DECLARE\_EVENT\_TABLE entry to the class, and then add an event table to
-your implementation file, as a BEGIN\_EVENT\_TABLE and END\_EVENT\_TABLE block. The
-individual 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.
-
-\section{Other events}
-
-To intercept other events, you used to override virtual functions, such as OnSize. Now, while you can use
-the 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).
-
-\chapter{Class hierarchy}\label{classhierarchy}
-
-The class hierarchy has changed somewhat. wxToolBar and wxButtonBar
-classes have been split into several classes, and are derived from wxControl (which was
-called wxItem). wxPanel derives from wxWindow instead of from wxCanvas, which has
-disappeared in favour of wxScrolledWindow (since all windows are now effectively canvases
-which 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 this
-functionality.
-
-There are new device context classes, with wxPanelDC and wxCanvasDC disappearing.
-See \helpref{Device contexts and painting}{dc}.
-
-\chapter{GDI objects}\label{gdiobjects}
-
-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} to
-objects to functions such as wxDC::SetPen, not pointers, so you will need to derefence your pointers.
-The device context does not store a copy of the pen
-itself, but takes a copy of it (via reference counting), and the object's data gets freed up
-when the reference count goes to zero. The application does not have to worry so much about
-who the object belongs to: it can pass the reference, then destroy the object without
-leaving a dangling pointer inside the device context.
-
-For the purposes of code migration, you can use the old style of object management - maintaining
-pointers to GDI objects, and using the FindOrCreate... functions. However, it is preferable to
-keep 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 these
-functions, you will need to use an identifier such as wxNullPen or wxNullBrush.
-
-\chapter{Dialogs and controls}\label{dialogscontrols}
-
-\wxheading{Labels}
-
-Most controls no longer have labels and values as they used to in 1.xx. Instead, labels
-should be created separately using wxStaticText (the new name for wxMessage). This will
-need some reworking of dialogs, unfortunately; programmatic dialog creation that doesn't
-use constraints will be especially hard-hit. Perhaps take this opportunity to make more
-use of dialog resources or constraints. Or consider using the wxPropertyListView class
-which can do away with dialog layout issues altogether by presenting a list of editable
-properties.
-
-\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 and
-wxSize 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 find
-that modal dialogs no longer work as expected. This is because the function for modal showing
-is now {\bf wxDialog:ShowModal}. This is part of a more fundamental change in which a
-control may tell the dialog that it caused the dismissal of a dialog, by
-calling {\bf wxDialog::EndModal} or {\bf wxWindow::SetReturnCode}. Using this
-information, {\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 wxMessage
-is renamed wxStaticText.
-
-\wxheading{wxGroupBox}
-
-wxGroupBox is renamed wxStaticBox.
-
-\wxheading{wxForm}
-
-Note that wxForm is no longer supported in wxWindows 2.0. Consider using the wxPropertyFormView class
-instead, 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 easier
-and more flexible than using wxForm.
-
-\chapter{Device contexts and painting}\label{dc}
-
-In wxWindows 2.0, device contexts are used for drawing into, as per 1.xx, but the way
-they 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 drawn
-into. The sort of device context you create depends on where your code is called from. If
-painting 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 it
-doesn't have to worry about what sort of device context to create - it uses the DC it is passed
-from other parts of the program.
-
-You {\bf must } create a wxPaintDC if you define an OnPaint handler, even if you do not
-actually use this device context, or painting will not work correctly under Windows.
-
-If you used device context functions with wxPoint or wxIntPoint before, please note
-that wxPoint now contains integer members, and there is a new class wxRealPoint. wxIntPoint
-no longer exists.
-
-wxMetaFile and wxMetaFileDC have been renamed to wxMetafile and wxMetafileDC.
-
-\chapter{Miscellaneous}
-
-\section{Strings}
-
-wxString has replaced char* in the majority of cases. For passing strings into functions,
-this should not normally require you to change your code if the syntax is otherwise the
-same. This is because C++ will automatically convert a char* or const char* to a wxString by virtue
-of appropriate wxString constructors.
-
-However, when a wxString is returned from a function in wxWindows 2.0 where a char* was
-returned in wxWindows 1.xx, your application will need to be changed. Usually you can
-simplify your application's allocation and deallocation of memory for the returned string,
-and simply assign the result to a wxString object. For example, replace this:
-
-{\small\begin{verbatim}
- char* s = wxFunctionThatReturnsString();
- s = copystring(s); // Take a copy in case it's temporary
- .... // Do something with it
- delete[] s;
-\end{verbatim}
-}
-
-with this:
-
-{\small\begin{verbatim}
- wxString s = wxFunctionThatReturnsString();
- .... // Do something with it
-\end{verbatim}
-}
-
-To indicate an empty return value or a problem, a function may return either the
-empty string (``") or a null string. You can check for a null string with wxString::IsNull().
-
-\section{Use of const}
-
-The {\bf const} keyword is now used to denote constant functions that do not affect the
-object, and for function arguments to denote that the object passed cannot be changed.
-
-This should not affect your application except for where you are overriding virtual functions
-which now have a different signature. If functions are not being called which were previously,
-check whether there is a parameter mismatch (or function type mismatch) involving consts.
-
-Try to use the {\bf const} keyword in your own code where possible.
-
-\chapter{Backward compatibility}\label{compat}
-
-Some wxWindows 1.xx functionality has been left to ease the transition to 2.0. This functionality
-(usually) only works if you compile with WXWIN\_COMPATIBILITY set to 1 in setup.h.
-
-Mostly this defines old names to be the new names (e.g. wxRectangle is defined to be wxRect).
-
-\chapter{Quick reference}\label{quickreference}
-
-This section allows you to quickly find features that
-need to be converted.
-
-\section{Include files}
-
-Use the form:
-
-\begin{verbatim}
-#include <wx/wx.h>
-#include <wx/button.h>
-\end{verbatim}
-
-For precompiled header support, use this form:
-
-\begin{verbatim}
-// For compilers that support precompilation, includes "wx.h".
-#include <wx/wxprec.h>
-
-#ifdef __BORLANDC__
- #pragma hdrstop
-#endif
-
-// Any files you want to include if not precompiling by including
-// the whole of <wx/wx.h>
-#ifndef WX_PRECOMP
- #include <stdio.h>
- #include <wx/setup.h>
- #include <wx/bitmap.h>
- #include <wx/brush.h>
-#endif
-
-// Any files you want to include regardless of precompiled headers
-#include <wx/toolbar.h>
-\end{verbatim}
-
-\section{IPC classes}
-
-These are now separated out into wxDDEServer/Client/Connection (Windows only) and wxTCPServer/Client/Connection
-(Windows and Unix). Take care to use wxString for your overridden function arguments, instead of char*, as per
-the documentation.
-
-\section{MDI style frames}
-
-MDI is now implemented as a family of separate classes, so you can't switch to MDI just by
-using a different frame style. Please see the documentation for the MDI frame classes, and the MDI
-sample may be helpful too.
-
-\section{OnActivate}
-
-Replace the arguments with one wxActivateEvent\& argument, make sure the function isn't virtual,
-and add an EVT\_ACTIVATE event table entry.
-
-\section{OnChar}
-
-This is now a non-virtual function, with the same wxKeyEvent\& argument as before.
-Add an EVT\_CHAR macro to the event table
-for your window, and the implementation of your function will need very few changes.
-
-\section{OnClose}
-
-The old virtual function OnClose is now obsolete.
-Add an OnCloseWindow event handler using an EVT\_CLOSE event table entry. For details
-about window destruction, see the Windows Deletion Overview in the manual. This is a subtle
-topic so please read it very carefully. Basically, OnCloseWindow is now responsible for
-destroying a window with Destroy(), but the default implementation (for example for wxDialog) may not
-destroy the window, so to be sure, always provide this event handler so it's obvious what's going on.
-
-\section{OnEvent}
-
-This is now a non-virtual function, with the same wxMouseEvent\& argument as before. However
-you may wish to rename it OnMouseEvent. Add an EVT\_MOUSE\_EVENTS macro to the event table
-for your window, and the implementation of your function will need very few changes.
-However, if you wish to intercept different events using different functions, you can
-specify specific events in your event table, such as EVT\_LEFT\_DOWN.
-
-Your OnEvent function is likely to have references to GetDC(), so make sure you create
-a wxClientDC instead. See \helpref{Device contexts}{dc}.
-
-If you are using a wxScrolledWindow (formerly wxCanvas), you should call
-PrepareDC(dc) to set the correct translation for the current scroll position.
-
-\section{OnMenuCommand}
-
-You need to replace this virtual function with a series of non-virtual functions, one for
-each case of your old switch statement. Each function takes a wxCommandEvent\& argument.
-Create an event table for your frame
-containing EVT\_MENU macros, and insert DECLARE\_EVENT\_TABLE() in your frame class, as
-per the samples.
-
-\section{OnPaint}
-
-This is now a non-virtual function, with a wxPaintEvent\& argument.
-Add an EVT\_PAINT macro to the event table
-for your window.
-
-Your function {\it must} create a wxPaintDC object, instead of using GetDC to
-obtain the device context.
-
-If you are using a wxScrolledWindow (formerly wxCanvas), you should call
-PrepareDC(dc) to set the correct translation for the current scroll position.
-
-\section{OnSize}
-
-Replace the arguments with one wxSizeEvent\& argument, make it non-virtual, and add to your
-event table using EVT\_SIZE.
-
-\section{wxApp definition}
-
-The definition of OnInit has changed. Return a bool value, not a wxFrame.
-
-Also, do {\it not} declare a global application object. Instead, use the macros
-DECLARE\_APP and IMPLEMENT\_APP as per the samples. Remove any occurrences of IMPLEMENT\_WXWIN\_MAIN:
-this is subsumed in IMPLEMENT\_APP.
-
-\section{wxButton}
-
-For bitmap buttons, use wxBitmapButton.
-
-\section{wxCanvas}
-
-Change the name to wxScrolledWindow.
-
-\section{wxDialogBox}
-
-Change the name to wxDialog, and for modal dialogs, use ShowModal instead of Show.
-
-\section{wxDialog::Show}
-
-If you used {\bf Show} to show a modal dialog or to override the standard
-modal dialog {\bf Show}, use {\bf ShowModal} instead.
-
-\wxheading{See also}
-
-\helpref{Dialogs and controls}{dialogscontrols}
-
-\section{wxForm}
-
-Sorry, this class is no longer available. Try using the wxPropertyListView or wxPropertyFormView class
-instead, or use .wxr files and validators.
-
-\section{wxPoint}
-
-The old wxPoint is called wxRealPoint, and wxPoint now uses integers.
-
-\section{wxRectangle}
-
-This is now called wxRect.
-
-\section{wxScrollBar}
-
-The function names have changed for this class: please refer to the documentation for wxScrollBar. Instead
-of setting properties individually, you will call SetScrollbar with several parameters.
-
-\section{wxText, wxMultiText, wxTextWindow}
-
-Change all these to wxTextCtrl. Add the window style wxTE\_MULTILINE if you
-wish to have a multi-line text control.
-
-\section{wxToolBar}
-
-This name is an alias for the most popular form of toolbar for your platform. There is now a family
-of toolbar classes, with for example wxToolBar95, wxToolBarMSW and wxToolBarSimple classes existing
-under Windows 95.
-
-Toolbar management is supported by frames, so calling wxFrame::CreateToolBar and adding tools is usually
-enough, and the SDI or MDI frame will manage the positioning for you. The client area of the frame is the space
-left over when the menu bar, toolbar and status bar have been taken into account.
-
-\end{document}
projects / wxWidgets.git / commitdiff
