porting.tex

Wxpython Implemented on Windows CE, Source code

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.

\section{Miscellaneous}

\subsection{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 wxWidgets 2.0 where a char* was
returned in wxWidgets 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 is 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().

\subsection{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.

\section{Backward compatibility}\label{portingcompat}

Some wxWidgets 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).

\section{Quick reference}\label{portingquickreference}

This section allows you to quickly find features that
need to be converted.

\subsection{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}

\subsection{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.

\subsection{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.

\subsection{OnActivate}

Replace the arguments with one wxActivateEvent\& argument, make sure the function isn't virtual,
and add an EVT\_ACTIVATE event table entry.

\subsection{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.

\subsection{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 is obvious what's going on.

\subsection{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}{portingdc}.

If you are using a wxScrolledWindow (formerly wxCanvas), you should call
PrepareDC(dc) to set the correct translation for the current scroll position.

\subsection{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.

\subsection{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.

\subsection{OnSize}

Replace the arguments with one wxSizeEvent\& argument, make it non-virtual, and add to your
event table using EVT\_SIZE.

\subsection{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.

\subsection{wxButton}

For bitmap buttons, use wxBitmapButton.

\subsection{wxCanvas}

Change the name to wxScrolledWindow.

\subsection{wxDialogBox}

Change the name to wxDialog, and for modal dialogs, use ShowModal instead of Show.

\subsection{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}{portingdialogscontrols}

\subsection{wxForm}

Sorry, this class is no longer available. Try using the wxPropertyListView or wxPropertyFormView class
instead, or use .wxr files and validators.

\subsection{wxPoint}

The old wxPoint is called wxRealPoint, and wxPoint now uses integers.

\subsection{wxRectangle}

This is now called wxRect.

\subsection{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.

\subsection{wxText, wxMultiText, wxTextWindow}

Change all these to wxTextCtrl. Add the window style wxTE\_MULTILINE if you
wish to have a multi-line text control.

\subsection{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.