X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6652e1a765385602430c604c7628a8fcd229d37c..2cfbeac8141db28d9a022cdf92c12f82631a3c82:/docs/latex/wx/body.tex?ds=sidebyside diff --git a/docs/latex/wx/body.tex b/docs/latex/wx/body.tex index 846866b95b..30f8f2dad1 100644 --- a/docs/latex/wx/body.tex +++ b/docs/latex/wx/body.tex @@ -3,7 +3,7 @@ \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% \setfooter{\thepage}{}{}{}{}{\thepage}% -\section{What is wxWidgets?} +\section{What is wxWidgets?}\label{whatis} wxWidgets is a C++ framework providing GUI (Graphical User Interface) and other facilities on more than one platform. Version 2 currently @@ -23,7 +23,7 @@ Please note that in the following, ``MS Windows" often refers to all platforms related to Microsoft Windows, including 16-bit and 32-bit variants, unless otherwise stated. All trademarks are acknowledged. -\section{Why another cross-platform development tool?} +\section{Why another cross-platform development tool?}\label{why} wxWidgets was developed to provide a cheap and flexible way to maximize investment in GUI application development. While a number of commercial @@ -141,11 +141,13 @@ To make use of wxWidgets, you currently need one of the following setups. (a) MS-Windows: \begin{enumerate}\itemsep=0pt -\item A 486 or higher PC running MS Windows. -\item A Windows compiler: most are supported, but please see {\tt install.txt} for -details. Supported compilers include Microsoft Visual C++ 4.0 or higher, Borland C++, Cygwin, -MinGW, Metrowerks CodeWarrior. -\item At least 60 MB of disk space. +\item A 32-bit or 64-bit PC running MS Windows. +\item A Windows compiler: MS Visual C++ (embedded Visual C++ for wxWinCE +port), Borland C++, Watcom C++, Cygwin, MinGW, Metrowerks CodeWarrior, +Digital Mars C++. See {\tt install.txt} for details about compiler +version supported. +\item At least 100 MB of disk space for source tree and additional space for +libraries and application building (depends on compiler and build settings). \end{enumerate} (b) Unix: @@ -154,7 +156,8 @@ MinGW, Metrowerks CodeWarrior. \item Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above). \item Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif 1.2 or higher, Lesstif. If using the wxX11 port, no such widget set is required. -\item At least 60 MB of disk space. +\item At least 100 MB of disk space for source tree and additional space for +libraries and application building (depends on compiler and build settings). \end{enumerate} (c) Mac OS/Mac OS X: @@ -162,11 +165,12 @@ If using the wxX11 port, no such widget set is required. \begin{enumerate}\itemsep=0pt \item A PowerPC Mac running Mac OS 8.6/9.x (eg. Classic) or Mac OS X 10.x. \item CodeWarrior 5.3, 6 or 7 for Classic Mac OS. -\item The Apple Developer Tools (eg. GNU C++) or CodeWarrior 7 for Mac OS X. -\item At least 60 MB of disk space. +\item The Apple Developer Tools (eg. GNU C++), CodeWarrior 7 or above for Mac OS X. +\item At least 100 MB of disk space for source tree and additional space for +libraries and application building (depends on compiler and build settings). \end{enumerate} -\section{Availability and location of wxWidgets} +\section{Availability and location of wxWidgets}\label{where} \winhelponly{wxWidgets is available by anonymous FTP and World Wide Web from ftp://biolpc22.york.ac.uk/pub and/or http://www.wxwidgets.org.} @@ -176,7 +180,7 @@ and/or \urlref{http://www.wxwidgets.org}{http://www.wxwidgets.org}.} You can also buy a CD-ROM using the form on the Web site. -\section{Acknowledgements} +\section{Acknowledgements}\label{acknowledgements} Thanks are due to AIAI for being willing to release the original version of wxWidgets into the public domain, and to our patient partners. @@ -232,7 +236,7 @@ This chapter describes the practical details of using wxWidgets. Please see the file install.txt for up-to-date installation instructions, and changes.txt for differences between versions. -\section{Include files} +\section{Include files}\label{includefiles} The main include file is {\tt "wx/wx.h"}; this includes the most commonly used modules of wxWidgets. @@ -259,25 +263,18 @@ the following section before any other includes: The file {\tt "wx/wxprec.h"} includes {\tt "wx/wx.h"}. Although this incantation may seem quirky, it is in fact the end result of a lot of experimentation, -and several Windows compilers to use precompilation (those tested are Microsoft Visual C++, Borland C++ -and Watcom C++). +and several Windows compilers to use precompilation which is largely automatic for +compilers with necessary support. Currently it is used for Visual C++ (including +embedded Visual C++), Borland C++, Open Watcom C++ and newer versions of GCC. -Borland precompilation is largely automatic. Visual C++ requires specification of {\tt "wx/wxprec.h"} as -the file to use for precompilation. Watcom C++ is automatic apart from the specification of -the .pch file. Watcom C++ is strange in requiring the precompiled header to be used only for -object files compiled in the same directory as that in which the precompiled header was created. -Therefore, the wxWidgets Watcom C++ makefiles go through hoops deleting and recreating -a single precompiled header file for each module, thus preventing an accumulation of many -multi-megabyte .pch files. - -\section{Libraries} +\section{Libraries}\label{libraries} Most ports of wxWidgets can create either a static library or a shared library. wxWidgets can also be built in multilib and monolithic variants. See the \helpref{libraries list}{librarieslist} for more information on these. -\section{Configuration} +\section{Configuration}\label{configuration} When using project files and makefiles directly to build wxWidgets, options are configurable in the file @@ -292,7 +289,7 @@ along with suitable makefiles. When using the RPM packages for installing wxWidgets on Linux, a correct setup.h is shipped in the package and this must not be changed. -\section{Makefiles} +\section{Makefiles}\label{makefiles} On Microsoft Windows, wxWidgets has a different set of makefiles for each compiler, because each compiler's 'make' tool is slightly different. @@ -323,7 +320,7 @@ For details on using makefiles, configure, and project files, please see docs/xxx/install.txt in your distribution, where xxx is the platform of interest, such as msw, gtk, x11, mac. -\section{Windows-specific files} +\section{Windows-specific files}\label{windowsfiles} wxWidgets application compilation under MS Windows requires at least two extra files, resource and module definition files. @@ -351,7 +348,7 @@ the MS Windows SDK documentation. so programs that search your executable for icons (such as the Program Manager) find your application icon first.} -\section{Allocating and deleting wxWidgets objects} +\section{Allocating and deleting wxWidgets objects}\label{allocatingobjects} In general, classes derived from wxWindow must dynamically allocated with {\it new} and deleted with {\it delete}. If you delete a window, @@ -381,7 +378,7 @@ make calls like wxDC::SetPen(wxNullPen) or wxDC::SelectObject(wxNullBitmap) befo a drawing object that may be in use. Code that doesn't do this will probably work fine on some platforms, and then fail under Windows. -\section{Architecture dependency} +\section{Architecture dependency}\label{architecturedependency} A problem which sometimes arises from writing multi-platform programs is that the basic C types are not defined the same on all platforms. This holds true @@ -401,7 +398,7 @@ as well). The macros handling bit-swapping with respect to the applications endianness are described in the \helpref{Byte order macros}{byteordermacros} section. -\section{Conditional compilation} +\section{Conditional compilation}\label{conditionalcompilation} One of the purposes of wxWidgets is to reduce the need for conditional compilation in source code, which can be messy and confusing to follow. @@ -410,21 +407,21 @@ features (such as metafile use under MS Windows). The symbols listed in the file {\tt symbols.txt} may be used for this purpose, along with any user-supplied ones. -\section{C++ issues} +\section{C++ issues}\label{cpp} The following documents some miscellaneous C++ issues. -\subsection{Templates} +\subsection{Templates}\label{templates} wxWidgets does not use templates (except for some advanced features that are switched off by default) since it is a notoriously unportable feature. -\subsection{RTTI} +\subsection{RTTI}\label{rtti} wxWidgets does not use C++ run-time type information since wxWidgets provides its own run-time type information system, implemented using macros. -\subsection{Type of NULL} +\subsection{Type of NULL}\label{null} Some compilers (e.g. the native IRIX cc) define NULL to be 0L so that no conversion to pointers is allowed. Because of that, all these @@ -440,7 +437,7 @@ as It is recommended to adhere to this in all code using wxWidgets as this make the code (a bit) more portable. -\subsection{Precompiled headers} +\subsection{Precompiled headers}\label{precompiledheaders} Some compilers, such as Borland C++ and Microsoft C++, support precompiled headers. This can save a great deal of compiling time. The @@ -466,7 +463,7 @@ the optimal compilation for each compiler, although it is biased towards the precompiled headers facility available in Microsoft C++. -\section{File handling} +\section{File handling}\label{filehandling} When building an application which may be used under different environments, one difficulty is coping with documents which may be @@ -547,7 +544,7 @@ development can be done. The program can be found in {\tt utils/configtool}. This is the sizer-aware resource system, and uses XML-based resource specifications that can be generated by tools such as \urlref{wxDesigner}{http://www.roebling.de} and XRC's own wxrcedit. -You can find this in {\tt contrib/src/xrc}, {\tt contrib/include/wx/xrc}, {\tt contrib/samples/xrc}, and {\tt contrib/utils/wxrcedit}. +You can find this in {\tt src/xrc}, {\tt include/wx/xrc}, {\tt samples/xrc}, and {\tt utils/wxrcedit}. For more information, see the \helpref{XML-based resource system overview}{xrcoverview}. \item[{\bf Object Graphics Library}] OGL defines an API for applications that need to display objects connected by lines. @@ -587,9 +584,9 @@ This chapter is intended to list strategies that may be useful when writing and debugging wxWidgets programs. If you have any good tips, please submit them for inclusion here. -\section{Strategies for reducing programming errors} +\section{Strategies for reducing programming errors}\label{reducingerrors} -\subsection{Use ASSERT} +\subsection{Use ASSERT}\label{useassert} Although I haven't done this myself within wxWidgets, it is good practice to use ASSERT statements liberally, that check for conditions that @@ -598,7 +595,7 @@ These can be compiled out of a non-debugging version of wxWidgets and your application. Using ASSERT is an example of `defensive programming': it can alert you to problems later on. -\subsection{Use wxString in preference to character arrays} +\subsection{Use wxString in preference to character arrays}\label{usewxstring} Using wxString can be much safer and more convenient than using char *. Again, I haven't practiced what I'm preaching, but I'm now trying to use @@ -610,9 +607,9 @@ manipulation (which means less code). The same goes for other data types: use classes wherever possible. -\section{Strategies for portability} +\section{Strategies for portability}\label{portability} -\subsection{Use relative positioning or constraints} +\subsection{Use relative positioning or constraints}\label{userelativepositioning} Don't use absolute panel item positioning if you can avoid it. Different GUIs have very differently sized panel items. Consider using the constraint system, although this @@ -622,14 +619,14 @@ Alternatively, you could use alternative .wrc (wxWidgets resource files) on diff platforms, with slightly different dimensions in each. Or space your panel items out to avoid problems. -\subsection{Use wxWidgets resource files} +\subsection{Use wxWidgets resource files}\label{useresources} Use .xrc (wxWidgets resource files) where possible, because they can be easily changed independently of source code. \section{Strategies for debugging}\label{debugstrategies} -\subsection{Positive thinking} +\subsection{Positive thinking}\label{positivethinking} It is common to blow up the problem in one's imagination, so that it seems to threaten weeks, months or even years of work. The problem you face may seem insurmountable: @@ -643,7 +640,7 @@ you will probably wonder why you worried so much. That's not to say it isn't painful at the time. Try not to worry -- there are many more important things in life. -\subsection{Simplify the problem} +\subsection{Simplify the problem}\label{simplifyproblem} Reduce the code exhibiting the problem to the smallest program possible that exhibits the problem. If it is not possible to reduce a large and @@ -656,14 +653,14 @@ to go from functioning to non-functioning state. This should give a clue to the problem. In some cases though, such as memory leaks or wrong deallocation, this can still give totally spurious results! -\subsection{Use a debugger} +\subsection{Use a debugger}\label{usedebugger} This sounds like facetious advice, but it is surprising how often people don't use a debugger. Often it is an overhead to install or learn how to use a debugger, but it really is essential for anything but the most trivial programs. -\subsection{Use logging functions} +\subsection{Use logging functions}\label{uselogging} There is a variety of logging functions that you can use in your program: see \helpref{Logging functions}{logfunctions}. @@ -672,7 +669,7 @@ Using tracing statements may be more convenient than using the debugger in some circumstances (such as when your debugger doesn't support a lot of debugging code, or you wish to print a bunch of variables). -\subsection{Use the wxWidgets debugging facilities} +\subsection{Use the wxWidgets debugging facilities}\label{usedebuggingfacilities} You can use wxDebugContext to check for memory leaks and corrupt memory: in fact in debugging mode, wxWidgets will