From: Václav Slavík Date: Sat, 25 Dec 1999 20:26:26 +0000 (+0000) Subject: moved 1.6X -> 2.X porting manual to main book X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/5eae411929abf27882cb9da8e20ef3b81664debd moved 1.6X -> 2.X porting manual to main book git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@5113 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/porting/back.gif b/docs/latex/porting/back.gif deleted file mode 100644 index 8a61076d3b..0000000000 Binary files a/docs/latex/porting/back.gif and /dev/null differ diff --git a/docs/latex/porting/books.bmp b/docs/latex/porting/books.bmp deleted file mode 100644 index cf1e148734..0000000000 Binary files a/docs/latex/porting/books.bmp and /dev/null differ diff --git a/docs/latex/porting/books.gif b/docs/latex/porting/books.gif deleted file mode 100644 index 036d016fb1..0000000000 Binary files a/docs/latex/porting/books.gif and /dev/null differ diff --git a/docs/latex/porting/bullet.bmp b/docs/latex/porting/bullet.bmp deleted file mode 100644 index 6481f5143b..0000000000 Binary files a/docs/latex/porting/bullet.bmp and /dev/null differ diff --git a/docs/latex/porting/contents.gif b/docs/latex/porting/contents.gif deleted file mode 100644 index 3dddfa3dd5..0000000000 Binary files a/docs/latex/porting/contents.gif and /dev/null differ diff --git a/docs/latex/porting/forward.gif b/docs/latex/porting/forward.gif deleted file mode 100644 index 88c3739ffb..0000000000 Binary files a/docs/latex/porting/forward.gif and /dev/null differ diff --git a/docs/latex/porting/porting.hpj b/docs/latex/porting/porting.hpj deleted file mode 100644 index 75e76d091b..0000000000 --- a/docs/latex/porting/porting.hpj +++ /dev/null @@ -1,16 +0,0 @@ -[OPTIONS] -TITLE=wxWindows Porting Guide -CONTENTS=Contents -COMPRESS=HIGH - -[FILES] -porting.rtf - -[CONFIG] -CreateButton("Up", "&Up", "JumpId(`porting.hlp', `Contents')") -BrowseButtons() - -[MAP] - -[BITMAPS] - diff --git a/docs/latex/porting/porting.tex b/docs/latex/porting/porting.tex deleted file mode 100644 index 6729f323eb..0000000000 --- a/docs/latex/porting/porting.tex +++ /dev/null @@ -1,498 +0,0 @@ -\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 -#include -\end{verbatim} - -For precompiled header support, use this form: - -\begin{verbatim} -// For compilers that support precompilation, includes "wx.h". -#include - -#ifdef __BORLANDC__ - #pragma hdrstop -#endif - -// Any files you want to include if not precompiling by including -// the whole of -#ifndef WX_PRECOMP - #include - #include - #include - #include -#endif - -// Any files you want to include regardless of precompiled headers -#include -\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} diff --git a/docs/latex/porting/tex2rtf.ini b/docs/latex/porting/tex2rtf.ini deleted file mode 100644 index 304529b8e4..0000000000 --- a/docs/latex/porting/tex2rtf.ini +++ /dev/null @@ -1,28 +0,0 @@ -;;; Tex2RTF initialisation file for 16-bit Winhelp -runTwice = yes -titleFontSize = 12 -authorFontSize = 10 -authorFontSize = 10 -chapterFontSize = 12 -sectionFontSize = 12 -subsectionFontSize = 12 -contentsDepth = 2 -headerRule = yes -footerRule = yes -useHeadingStyles = yes -listItemIndent=40 -generateHPJ = no -htmlBrowseButtons = bitmap -winHelpContents = yes -winHelpVersion = 3 ; 3 for Windows 3.x, 4 for Windows 95 -winHelpTitle = "wxWindows Porting Guide" -truncateFilenames = yes -combineSubSections = yes -\overview [2] {\rtfonly{See also }\settransparency{on}\sethotspotcolour{off}\sethotspotunderline{on}\winhelponly{\image{}{books.bmp}\settransparency{off}} -\htmlonly{\image{}{books.gif}}\helpref{#1}{#2} -\sethotspotcolour{on}\sethotspotunderline{on}} -\docparam [2]{\parskip{0}{\it #1}\par\parskip{10}\indented{1cm}{#2}} -\wxheading [1]{{\bf \fcol{blue}{#1}}} -\const [0] {{\bf const}} -\constfunc [3] {{\bf #1} {\bf #2}(#3) {\bf const}\index{#2}} - diff --git a/docs/latex/porting/texhelp.sty b/docs/latex/porting/texhelp.sty deleted file mode 100644 index 81704b0575..0000000000 --- a/docs/latex/porting/texhelp.sty +++ /dev/null @@ -1,289 +0,0 @@ -% LaTeX style file -% Name: texhelp.sty -% Author: Julian Smart -% -% Purpose -% ------- -% Style file to enable the simultaneous preparation of printed LaTeX and on-line -% hypertext manuals. -% Use in conjunction with Tex2RTF (see Tex2RTF documentation). -% -% Note that if a non-ASCII character starts a newline and there should be a space -% between the last word on the previous line and the first word on this line, -% you need to use \rtfsp to generate a space in Windows Help. \rtfsp is ignored -% in all other formats. -% -% Julian Smart -% Artificial Intelligence Applications Institute -% -% -% ============== C++/CLIPS Documentation Facilities ============== -% -% Each class definition should be typeset with e.g. -% -% \section{\class{Name}: Parent} -% -% followed by a description of the class. -% Each member should follow: -% -% \membersection{wxName::Member} -% -% with a description of what this member does. -% Then, one (or more if overloaded) member (function) in detail: -% -% \func{return type}{name}{args} -% or -% \member{type}{name} -% -% where args is a list of \param{type}{name}, ... - -% Function, e.g. -% e.g. to typeset -% -% void DoIt(char *string); -% -% write: -% -% \func{void}{DoIt}{\param{char *}{string}} -% - -\newcommand{\func}[3]{\hangafter=1\noindent\hangindent=10mm -{{\it #1} {\bf #2}\index{#2}}(#3)} - -% For function/type definition where the name is a pointer, -% e.g. to typeset -% -% typedef void (*wxFunction)(wxObject&) -% -% write: -% -% \pfunc{typedef void}{wxFunction}{param{wxObject&}} - -\newcommand{\pfunc}[3]{\hangafter=1\noindent\hangindent=10mm -{{\it #1} ({\bf *#2})\index{#2}}(#3)} - -% Use an ordinary \section command for class name definitions. - -% This is used for a member, such as wxBitmap: GetDepth -\newcommand{\membersection}[1]{\subsection*{#1}\index{#1}} - -% CLIPS function -\newcommand{\clipsfunc}[3]{\hangafter=1\noindent\hangindent=10mm -{{\bf #1} ({\bf #2}\index{#2}}#3)} - -\newcommand{\clipssection}[1]{\chapter{#1}} - -% This is used for a CLIPS function name -\newcommand{\functionsection}[1]{\subsection*{#1}} - -% Member: a type and a name -\newcommand{\member}[2]{{\bf #1 \it #2}} - -% C++ Parameter: a type and a name (no intervening space) -\newcommand{\param}[2]{{\it #1}{\bf #2}} - -% CLIPS Parameter: a type and a name (one intervening space) -\newcommand{\cparam}[2]{{\bf #1} {\it #2}} - -% Class: puts in index -\newcommand{\class}[1]{#1\index{#1}} - -% Void type -\newcommand{\void}{{\it void}} - -% Typeset destructor -\newcommand{\destruct}[1]{{$\sim$}#1} - -% Typeset insert/extract operators -\newcommand{\cinsert}{$<<$} -\newcommand{\cextract}{$>>$} - - -% =================== Hypertext facilities =================== -% -% To insert hyperlinks (or references, in Latex), \label the sections -% or membersections \label{ref-label} immediately after the section, on the same line, -% and use \helpref{text-to-show}{ref-label} to make a reference. -% - -% Type text with section reference -\newcommand{\helpref}[2]{{\it #1} (p.\ \pageref{#2}) } - -% Type text with URL in verbatim mode -\newcommand{\urlref}[2]{#1 (\verb$#2$)} - -% Don't typeset section number in LaTeX -\newcommand{\helprefn}[2]{{\it #1}} - -% Like helpref, but popup text in WinHelp instead of hyperlinked -\newcommand{\popref}[2]{{\it #1}} - -% Like footnote, but popup text. -\newcommand{\footnotepopup}[2]{{\it #1}\footnote{#2}} - -% =================== On-line help specific macros =================== -% - -% Global document font size/family, help only. -\newcommand{\helpfontsize}[1]{} -\newcommand{\helpfontfamily}[1]{} - -% Ignore in all on-line help -\newcommand{\helpignore}[1]{#1} -% Only print in all on-line help -\newcommand{\helponly}[1]{} - -% Ignore in LaTeX -\newcommand{\latexignore}[1]{} -% Only print in LaTeX -\newcommand{\latexonly}[1]{#1} - -% Ignore in linear RTF -\newcommand{\rtfignore}[1]{#1} -% Only print in linear RTF -\newcommand{\rtfonly}[1]{} - -% Ignore in WinHelp RTF -\newcommand{\winhelpignore}[1]{#1} -% Only print in WinHelp RTF -\newcommand{\winhelponly}[1]{} - -% Ignore in wxHelp -\newcommand{\xlpignore}[1]{#1} -% Only print in wxHelp -\newcommand{\xlponly}[1]{} - -% Ignore in HTML -\newcommand{\htmlignore}[1]{#1} -% Only print in HTML -\newcommand{\htmlonly}[1]{} - -% Input a file only for help system (binder thickness is not a limitation -% in help systems!) -\newcommand{\helpinput}[1]{} - -\newcommand{\rtfsp}{ } % Force a space in RTF, ignore in Latex - -% =================== Miscellaneous macros =================== -% -% Headings consistent with generated ones -\newcommand{\myheading}[1]{\vspace*{25pt} -\begin{flushleft} -{\LARGE \bf #1} -\end{flushleft} -\vskip 20pt -} - -% Heading with entry in contents page. -\newcommand{\chapterheading}[1]{\myheading{#1} -\addcontentsline{toc}{chapter}{#1}} - -\newcommand{\sectionheading}[1]{\myheading{#1} -\addcontentsline{toc}{section}{#1}} - -% Glossary environment -\newenvironment{helpglossary}{\newpage\chapterheading{Glossary}\begin{description}}{\end{description}} - -% Glossary entry -\newcommand{\gloss}[1]{\item[#1]\index{#1}} - -% Image: EPS in Latex, BMP or MF (whatever's available) in RTF. Requires psbox. -\newcommand{\image}[2]{\psboxto(#1){#2}} - -% Image, left aligned (HTML) -\newcommand{\imager}[2]{\psboxto(#1){#2}} - -% Image, right aligned (HTML) -\newcommand{\imagel}[2]{\psboxto(#1){#2}} - -% Imagemap: principally for HTML only. In Latex, -% acts like \image. -\newcommand{\imagemap}[3]{\psboxto(#1){#2}} - -% Headers and footers -% \setheader{EvenPageLeft}{EvenPageCentre}{EvenPageRight} -% {OddPageLeft}{OddPageCentre}{OddPageRight} -\newcommand{\setheader}[6]{ -\lhead[\fancyplain{}{#1}]{\fancyplain{}{#4}} -\chead[\fancyplain{}{#2}]{\fancyplain{}{#5}} -\rhead[\fancyplain{}{#3}]{\fancyplain{}{#6}} -} - -% \setfooter{EvenPageLeft}{EvenPageCentre}{EvenPageRight} -% {OddPageLeft}{OddPageCentre}{OddPageRight} -\newcommand{\setfooter}[6]{ -\lfoot[\fancyplain{#1}{#1}]{\fancyplain{#4}{#4}} -\cfoot[\fancyplain{#2}{#2}]{\fancyplain{#5}{#5}} -\rfoot[\fancyplain{#3}{#3}]{\fancyplain{#6}{#6}} -} - -% Needed for telling RTF where margin paragraph should go -% in mirrored margins mode. -\newcommand{\marginpareven}[1]{\hspace*{0pt}\marginpar{#1}} -\newcommand{\marginparodd}[1]{\hspace*{0pt}\marginpar{#1}} - -% Environment for two-column table popular in WinHelp and manuals. -\newcommand{\twocolwidtha}[1]{\def\twocolwidthaval{#1}} -\newcommand{\twocolwidthb}[1]{\def\twocolwidthbval{#1}} -\newcommand{\twocolspacing}[1]{\def\twocolspacingval{#1}} - -\twocolwidtha{3cm} -\twocolwidthb{8.5cm} -\twocolspacing{2} - -\newcommand{\twocolitem}[2]{#1 & #2\\} -\newcommand{\twocolitemruled}[2]{#1 & #2\\\hline} - -\newenvironment{twocollist}{\renewcommand{\arraystretch}{\twocolspacingval}\begin{tabular}{lp{\twocolwidthbval}}}% -{\end{tabular}\renewcommand{\arraystretch}{1}} - -% Specifying table rows for RTF compatibility -\newcommand{\row}[1]{#1\\} - -% Use for the last ruled row for correct RTF generation. -\newcommand{\ruledrow}[1]{#1\\\hline} - -% Indentation environment. Arg1 is left margin size -\newenvironment{indented}[1]{\begin{list}{}{\leftmargin=#1}\item[]}% -{\end{list}} - -% Framed box of text, normal formatting. -\newcommand{\normalbox}[1]{\fbox{\vbox{#1}}} -% Double-framed box of text. -\newcommand{\normalboxd}[1]{\fbox{\fbox{\vbox{#1}}}} - -% WITHDRAWN -- can't do in RTF, easily. -% Framed box of text, horizontally centred. Ragged right within box. -% \newcommand{\centeredbox}[2]{\begin{center}\fbox{\parbox{#1}{\raggedright#2}}\end{center}} -% Double-framed box of text, horizontally centred. Ragged right within box. -% \newcommand{\centeredboxd}[2]{\begin{center}\fbox{\fbox{\parbox{#1}{\raggedright#2}}}\end{center}} - -% toocomplex environment: simply prints the argument in LaTeX, -% comes out verbatim in all generated formats. -\newenvironment{toocomplex}{}{} - -% Colour: dummy commands since LaTeX doesn't support colour. -% \definecolour{name}{red}{blue}{green} -% \fcol{name}{text} ; Foreground -% \bcol{name}{text} ; Background -\newcommand{\definecolour}[4]{} -\newcommand{\definecolor}[4]{} -\newcommand{\fcol}[2]{#2} -\newcommand{\bcol}[2]{#2} -\newcommand{\sethotspotcolour}[1]{} -\newcommand{\sethotspotunderline}[1]{} -\newcommand{\settransparency}[1]{} -\newcommand{\backslashraw}[0]{} -\newcommand{\lbraceraw}[0]{} -\newcommand{\rbraceraw}[0]{} -\newcommand{\registered}[0]{(r)} -\newcommand{\background}[1]{} -\newcommand{\textcolour}[1]{} -\newcommand{\overview}[2]{See \helpref{#1}{#2}.} -\newcommand{\docparam}[2]{{\it #1}\begin{list}{}{\leftmargin=1cm}\item[] -#2% -\end{list}} -\newcommand{\wxheading}[1]{{\bf #1}} -\newcommand{\const}[0]{{\bf const}} -\newcommand{\constfunc}[3]{{\bf #1} {\bf #2}(#3) {\bf const}\index{#2}} - diff --git a/docs/latex/porting/up.gif b/docs/latex/porting/up.gif deleted file mode 100644 index f9e7031e64..0000000000 --- a/docs/latex/porting/up.gif +++ /dev/null @@ -1 +0,0 @@ -GIF87a \ No newline at end of file diff --git a/docs/latex/wx/manual.tex b/docs/latex/wx/manual.tex index aa15549152..c7c1ac9b17 100644 --- a/docs/latex/wx/manual.tex +++ b/docs/latex/wx/manual.tex @@ -661,7 +661,9 @@ That's all there is to it! \input{category.tex} \input{topics.tex} \input{wxhtml.tex} +\input{proplist.tex} \input{wxPython.tex} +\input{porting.tex} \begin{comment} \newpage diff --git a/docs/latex/wx/porting.tex b/docs/latex/wx/porting.tex new file mode 100644 index 0000000000..306260b397 --- /dev/null +++ b/docs/latex/wx/porting.tex @@ -0,0 +1,467 @@ +\chapter{Porting from wxWindows 1.xx}\label{porting} + +This addendum 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.} + +\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 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} + +\section{The new event system}\label{portingeventsystem} + +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. + +\subsection{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. + +\subsection{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). + +\section{Class hierarchy}\label{portingclasshierarchy} + +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}{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} 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. + +\section{Dialogs and controls}\label{portingdialogscontrols} + +\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. + +\section{Device contexts and painting}\label{portingdc} + +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. + +\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 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(). + +\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 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). + +\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 +#include +\end{verbatim} + +For precompiled header support, use this form: + +\begin{verbatim} +// For compilers that support precompilation, includes "wx.h". +#include + +#ifdef __BORLANDC__ + #pragma hdrstop +#endif + +// Any files you want to include if not precompiling by including +// the whole of +#ifndef WX_PRECOMP + #include + #include + #include + #include +#endif + +// Any files you want to include regardless of precompiled headers +#include +\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's 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. +