X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d958c9bd1754393a2b2e35a95df4df4e74bcd3c4..933b675ed41f626e6573a0c9c402acbc0283d2da:/docs/latex/wx/body.tex

diff --git a/docs/latex/wx/body.tex b/docs/latex/wx/body.tex
index 19c62daf94..17111a9446 100644
--- a/docs/latex/wx/body.tex
+++ b/docs/latex/wx/body.tex
@@ -7,19 +7,17 @@
 
 wxWindows is a C++ framework providing GUI (Graphical User
 Interface) and other facilities on more than one platform.  Version 2 currently
-supports MS Windows (16-bit, Windows 95 and Windows NT), Unix with GTK+, Unix with Motif,
-and Mac. An OS/2 port is in progress.
+supports all desktop versions of MS Windows, Unix with GTK+, Unix with Motif,
+and MacOS. An OS/2 port is in progress.
 
 wxWindows was originally developed at the Artificial Intelligence
 Applications Institute, University of Edinburgh, for internal use,
-and was first made publicly available in 1993.
+and was first made publicly available in 1992.
 Version 2 is a vastly improved version written and maintained by
-Julian Smart, Robert Roebling, Vadim Zeitlin and many others.
+Julian Smart, Robert Roebling, Vadim Zeitlin, Vaclav Slavik and many others.
 
-This manual discusses wxWindows in the context of multi-platform
-development.\helpignore{For more detail on the wxWindows version 2.0 API
-(Application Programming Interface) please refer to the separate
-wxWindows reference manual.}
+This manual contains a class reference and topic overviews.
+For a selection of wxWindows tutorials, please see the documentation page on the \urlref{wxWindows web site}{http://www.wxwindows.org}.
 
 Please note that in the following, ``MS Windows" often refers to all
 platforms related to Microsoft Windows, including 16-bit and 32-bit
@@ -39,37 +37,41 @@ none met all of the following criteria:
 \item support for a wide range of compilers.
 \end{enumerate}
 
-Since wxWindows was started, several other free or almost-free GUI frameworks have
-emerged. However, none has the range of features, flexibility, documentation and the
-well-established development team that wxWindows has.
-
-As open source software, wxWindows has
-benefited from comments, ideas, bug fixes, enhancements and the sheer
-enthusiasm of users. This gives wxWindows a
-certain advantage over its commercial competitors (and over free libraries
-without an independent development team), plus a robustness against
-the transience of one individual or company. This openness and
-availability of source code is especially important when the future of
-thousands of lines of application code may depend upon the longevity of
-the underlying class library.
-
-Version 2 goes much further than previous versions in terms of generality and features,
-allowing applications to be produced
-that are often indistinguishable from those produced using single-platform
-toolkits such as Motif, GTK+ and MFC.
-
-The importance of using a platform-independent class library cannot be
-overstated, since GUI application development is very time-consuming,
-and sustained popularity of particular GUIs cannot be guaranteed.
-Code can very quickly become obsolete if it addresses the wrong
-platform or audience.  wxWindows helps to insulate the programmer from
-these winds of change. Although wxWindows may not be suitable for
-every application (such as an OLE-intensive program), it provides access to most of the functionality a
-GUI program normally requires, plus many extras such as network programming,
-PostScript output, and HTML rendering; and it can of course be extended as needs dictate.  As a bonus, it provides
-a far cleaner and easier programming interface than the native
-APIs. Programmers may find it worthwhile to use wxWindows even if they
-are developing on only one platform.
+Since wxWindows was started, several other free or almost-free
+GUI frameworks have emerged. However, none has the range of
+features, flexibility, documentation and the well-established
+development team that wxWindows has.
+
+As open source software, wxWindows has benefited from comments,
+ideas, bug fixes, enhancements and the sheer enthusiasm of
+users. This gives wxWindows a certain advantage over its
+commercial competitors (and over free libraries without an
+independent development team), plus a robustness against the
+transience of one individual or company. This openness and
+availability of source code is especially important when the
+future of thousands of lines of application code may depend upon
+the longevity of the underlying class library.
+
+Version 2 goes much further than previous versions in terms of
+generality and features, allowing applications to be produced
+that are often indistinguishable from those produced using
+single-platform toolkits such as Motif, GTK+ and MFC.
+
+The importance of using a platform-independent class library
+cannot be overstated, since GUI application development is very
+time-consuming, and sustained popularity of particular GUIs
+cannot be guaranteed. Code can very quickly become obsolete if
+it addresses the wrong platform or audience.  wxWindows helps to
+insulate the programmer from these winds of change. Although
+wxWindows may not be suitable for every application (such as an
+OLE-intensive program), it provides access to most of the
+functionality a GUI program normally requires, plus many extras
+such as network programming, PostScript output, and HTML
+rendering; and it can of course be extended as needs dictate.
+As a bonus, it provides a far cleaner and easier programming
+interface than the native APIs. Programmers may find it
+worthwhile to use wxWindows even if they are developing on only
+one platform.
 
 It is impossible to sum up the functionality of wxWindows in a few paragraphs, but
 here are some of the benefits:
@@ -143,7 +145,7 @@ To make use of wxWindows, you currently need one of the following setups.
 \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,
-Metrowerks CodeWarrior.
+MinGW, Metrowerks CodeWarrior.
 \item At least 60 MB of disk space.
 \end{enumerate}
 
@@ -151,7 +153,8 @@ Metrowerks CodeWarrior.
 
 \begin{enumerate}\itemsep=0pt
 \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, Motif 1.2 or higher, Lesstif.
+\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.
 \end{enumerate}
 
@@ -167,14 +170,14 @@ Metrowerks CodeWarrior.
 \section{Availability and location of wxWindows}
 
 \winhelponly{wxWindows is available by anonymous FTP and World Wide Web
-from ftp://www.remstar.com/pub/wxwin and/or http://www.wxwindows.org.}
+from ftp://biolpc22.york.ac.uk/pub and/or http://www.wxwindows.org.}
 \winhelpignore{wxWindows is available by anonymous FTP and World Wide Web
-from \urlref{ftp://www.remstar.com/pub/wxwin}{ftp://www.remstar.com/pub/wxwin} 
+from \urlref{ftp://biolpc22.york.ac.uk/pub}{ftp://biolpc22.york.ac.uk/pub} 
 and/or \urlref{http://www.wxwindows.org}{http://www.wxwindows.org}.}
 
 You can also buy a CD-ROM using the form on the Web site.
 
-\section{Acknowledgments}
+\section{Acknowledgements}
 
 Thanks are due to AIAI for being willing to release the original version of
 wxWindows into the public domain, and to our patient partners.
@@ -258,54 +261,56 @@ multi-megabyte .pch files.
 
 \section{Libraries}
 
-The GTK and Motif ports of wxWindow can create either a static library or a shared
-library on most Unix or Unix-like systems. The static library is called libwx\_gtk.a
-and libwx\_motif.a whereas the name of the shared library is dependent on the
-system it is created on and the version you are using. The library name for the
-GTK version of wxWindows 2.2 on Linux and Solaris will be libwx\_gtk-2.2.so.0.0.0,
-on HP-UX, it will be libwx\_gtk-2.2.sl, on AIX just libwx\_gtk.a etc.
-
-Under Windows, use the library wx.lib (release) or wxd.lib (debug) for stand-alone Windows
-applications, or wxdll.lib (wxdlld.lib) for creating DLLs.
+Most ports of wxWindows can create either a static library or a shared
+library. wxWindows can also be built in multilib and monolithic variants.
+See the \helpref{libraries list}{librarieslist} for more
+information on these.
 
 \section{Configuration}
 
-Options are configurable in the file
+When using project files and makefiles directly to build wxWindows,
+options are configurable in the file
 \rtfsp{\tt "wx/XXX/setup.h"} where XXX is the required platform (such as msw, motif, gtk, mac). Some 
 settings are a matter of taste, some help with platform-specific problems, and
 others can be set to minimize the size of the library. Please see the setup.h file
 and {\tt install.txt} files for details on configuration.
 
-Under Unix (GTK and Motif) the corresponding setup.h files are generated automatically
-when configuring the wxWindows using the "configure" script. When using the RPM packages
+When using the 'configure' script to configure wxWindows (on Unix and other platforms where
+configure is available), the corresponding setup.h files are generated automatically
+along with suitable makefiles. When using the RPM packages
 for installing wxWindows on Linux, a correct setup.h is shipped in the package and
 this must not be changed.
 
 \section{Makefiles}
 
-At the moment there is no attempt to make Unix makefiles and
-PC makefiles compatible, i.e. one makefile is required for
-each environment. The Unix ports use a sophisticated system based
-on the GNU autoconf tool and this system will create the
-makefiles as required on the respective platform. Although the
-makefiles are not identical in Windows, Mac and Unix, care has
-been taken to make them relatively similar so that moving from
-one platform to another will be painless.
-
-Sample makefiles for Unix (suffix .unx), MS C++ (suffix .DOS and .NT), Borland
-C++ (.BCC and .B32) and Symantec C++ (.SC) are included for the library, demos
-and utilities.
-
-The controlling makefile for wxWindows is in the MS-Windows
-directory {\tt src/msw} for the different Windows compiler and
-in the build directory when using the Unix ports. The build
-directory can be chosen by the user. It is the directory in
-which the "configure" script is run. This can be the normal
-base directory (by running {\tt ./configure} there) or any other
-directory (e.g. {\tt ../configure} after creating a build-directory
-in the directory level above the base directory).
-
-Please see the platform-specific {\tt install.txt} file for further details.
+On Microsoft Windows, wxWindows has a different set of makefiles for each
+compiler, because each compiler's 'make' tool is slightly different.
+Popular Windows compilers that we cater for, and the corresponding makefile
+extensions, include: Microsoft Visual C++ (.vc), Borland C++ (.bcc),
+OpenWatcom C++ (.wat) and MinGW/Cygwin (.gcc). Makefiles are provided
+for the wxWindows library itself, samples, demos, and utilities.
+
+On Linux, Mac and OS/2, you use the 'configure' command to
+generate the necessary makefiles. You should also use this method when
+building with MinGW/Cygwin on Windows.
+
+We also provide project files for some compilers, such as
+Microsoft VC++. However, we recommend using makefiles
+to build the wxWindows library itself, because makefiles
+can be more powerful and less manual intervention is required.
+
+On Windows using a compiler other than MinGW/Cygwin, you would
+build the wxWindows library from the build/msw directory
+which contains the relevant makefiles.
+
+On Windows using MinGW/Cygwin, and on Unix, MacOS X and OS/2, you invoke
+'configure' (found in the top-level of the wxWindows source hierarchy),
+from within a suitable empty directory for containing makefiles, object files and
+libraries.
+
+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}
 
@@ -318,7 +323,7 @@ The least that must be defined in the Windows resource file (extension RC)
 is the following statement:
 
 \begin{verbatim}
-rcinclude "wx/msw/wx.rc"
+#include "wx/msw/wx.rc"
 \end{verbatim}
 
 which includes essential internal wxWindows definitions.  The resource script
@@ -335,25 +340,6 @@ the MS Windows SDK documentation.
 so programs that search your executable for icons (such
 as the Program Manager) find your application icon first.}
 
-\subsection{Module definition file}
-
-A module definition file (extension DEF) is required for 16-bit applications, and
-looks like the following:
-
-\begin{verbatim}
-NAME         Hello
-DESCRIPTION  'Hello'
-EXETYPE      WINDOWS
-STUB         'WINSTUB.EXE'
-CODE         PRELOAD MOVEABLE DISCARDABLE
-DATA         PRELOAD MOVEABLE MULTIPLE
-HEAPSIZE     1024
-STACKSIZE    8192
-\end{verbatim}
-
-The only lines which will usually have to be changed per application are
-NAME and DESCRIPTION.
-
 \section{Allocating and deleting wxWindows objects}
 
 In general, classes derived from wxWindow must dynamically allocated
@@ -402,7 +388,7 @@ which is either wxBIG\_ENDIAN or wxLITTLE\_ENDIAN (in the future maybe wxPDP\_EN
 as well).
 
 The macros handling bit-swapping with respect to the applications endianness
-are described in the \helpref{Macros}{macros} section.
+are described in the \helpref{Byte order macros}{byteordermacros} section.
 
 \section{Conditional compilation}
 
@@ -419,18 +405,19 @@ The following documents some miscellaneous C++ issues.
 
 \subsection{Templates}
 
-wxWindows does not use templates since it is a notoriously unportable feature.
+wxWindows does not use templates (except for some advanced features that
+are switched off by default) since it is a notoriously unportable feature.
 
 \subsection{RTTI}
 
-wxWindows does not use run-time type information since wxWindows provides
+wxWindows does not use C++ run-time type information since wxWindows provides
 its own run-time type information system, implemented using macros.
 
 \subsection{Type of 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
-occurrences of NULL in the GTK port use an explicit conversion such 
+occurrences of NULL in the GTK+ port use an explicit conversion such 
 as
 
 {\small
@@ -498,90 +485,92 @@ dos2unix).
 See also the File Functions section of the reference manual for
 descriptions of miscellaneous file handling functions.
 
-\begin{comment}
-\chapter{Utilities supplied with wxWindows}\label{utilities}
+\chapter{Utilities and libraries supplied with wxWindows}\label{utilities}
 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 \setfooter{\thepage}{}{}{}{}{\thepage}%
 
-A number of `extras' are supplied with wxWindows, to complement
-the GUI functionality in the main class library. These are found
-below the utils directory and usually have their own source, library
-and documentation directories. For other user-contributed packages,
-see the directory ftp://www.remstar.com/pub/wxwin/contrib, which is
-more easily accessed via the Contributions page on the Web site.
-
-\section{wxHelp}\label{wxhelp}
-
-wxHelp is a stand-alone program, written using wxWindows,
-for displaying hypertext help. It is necessary since not all target
-systems (notably X) supply an adequate
-standard for on-line help. wxHelp is modeled on the MS Windows help
-system, with contents, search and browse buttons, but does not reformat
-text to suit the size of window, as WinHelp does, and its input files
-are uncompressed ASCII with some embedded font commands and an .xlp
-extension. Most wxWindows documentation (user manuals and class
-references) is supplied in wxHelp format, and also in Windows Help
-format. The wxWindows 2.0 project will presently use an HTML widget
-in a new and improved wxHelp implementation, under X.
-
-Note that an application can be programmed to use Windows Help under
-MS Windows, and wxHelp under X. An alternative help viewer under X is
-Mosaic, a World Wide Web viewer that uses HTML as its native hypertext
-format. However, this is not currently integrated with wxWindows
-applications.
-
-wxHelp works in two modes---edit and end-user. In edit mode, an ASCII
-file may be marked up with different fonts and colours, and divided into
-sections. In end-user mode, no editing is possible, and the user browses
-principally by clicking on highlighted blocks.
-
-When an application invokes wxHelp, subsequent sections, blocks or
-files may be viewed using the same instance of wxHelp since the two
-programs are linked using wxWindows interprocess communication
-facilities. When the application exits, that application's instance of
-wxHelp may be made to exit also.  See the {\bf wxHelpControllerBase} entry in the
-reference section for how an application controls wxHelp.
-
-\section{Tex2RTF}\label{textortf}
+In addition to the core wxWindows library, a number of further
+libraries and utilities are supplied with each distribution.
 
-Supplied with wxWindows is a utility called Tex2RTF for converting\rtfsp
-\LaTeX\ manuals to the following formats:
-
-\begin{description}
-\item[wxHelp]
-wxWindows help system format (XLP).
-\item[Linear RTF]
-Rich Text Format suitable for importing into a word processor.
-\item[Windows Help RTF]
-Rich Text Format suitable for compiling into a WinHelp HLP file with the
-help compiler.
-\item[HTML]
-HTML is the native format for Mosaic, the main hypertext viewer for
-the World Wide Web. Since it is freely available it is a good candidate
-for being the wxWindows help system under X, as an alternative to wxHelp.
-\end{description}
-
-Tex2RTF is used for the wxWindows manuals and can be used independently
-by authors wishing to create on-line and printed manuals from the same\rtfsp
-\LaTeX\ source.  Please see the separate documentation for Tex2RTF.
-
-\section{wxTreeLayout}
-
-This is a simple class library for drawing trees in a reasonably pretty
-fashion. It provides only minimal default drawing capabilities, since
-the algorithm is meant to be used for implementing custom tree-based
-tools.
+Some are under the 'contrib' hierarchy which mirrors the
+structure of the main wxWindows hierarchy. See also the 'utils'
+hierarchy. The first place to look for documentation about
+these tools and libraries is under the wxWindows 'docs' hierarchy,
+for example {\tt docs/htmlhelp/fl.chm}.
 
-Directed graphs may also be drawn using this library, if cycles are
-removed before the nodes and arcs are passed to the algorithm.
+For other user-contributed packages, please see the Contributions page
+on the \urlref{wxWindows Web site}{http://www.wxwindows.org}.
 
-Tree displays are used in many applications: directory browsers,
-hypertext systems, class browsers, and decision trees are a few
-possibilities.
+\begin{description}\itemsep=0pt
+\item[{\bf Helpview}]
+Helpview is a program for displaying wxWindows HTML
+Help files. In many cases, you may wish to use the wxWindows HTML
+Help classes from within your application, but this provides a
+handy stand-alone viewer. See \helpref{wxHTML Notes}{wxhtml} for more details.
+You can find it in {\tt samples/html/helpview}.
 
-See the separate manual and the directory utils/wxtree.
-
-\end{comment}
+\item[{\bf Tex2RTF}]
+Supplied with wxWindows is a utility called Tex2RTF for converting\rtfsp
+\LaTeX\ manuals HTML, MS HTML Help, wxHTML Help, RTF, and Windows
+Help RTF formats. Tex2RTF is used for the wxWindows manuals and can be used independently
+by authors wishing to create on-line and printed manuals from the same\rtfsp
+\LaTeX\ source. Please see the separate documentation for Tex2RTF.
+You can find it under {\tt utils/tex2rtf}.
+
+\item[{\bf Helpgen}]
+Helpgen takes C++ header files and generates a Tex2RTF-compatible
+documentation file for each class it finds, using comments as appropriate.
+This is a good way to start a reference for a set of classes.
+
+%\item[{\bf Dialog Editor}]
+%Dialog Editor allows interactive construction of dialogs using
+%absolute positioning, producing WXR output files. This tool is generally deprecated
+%in favour of sizer-based tools. You can find Dialog Editor
+%in {\tt utils/dialoged}.
+%
+\item[{\bf XRC resource system}]
+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}.
+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.
+The objects can be moved around and interacted with.
+You can find this in {\tt contrib/src/ogl}, {\tt contrib/include/wx/ogl}, and {\tt contrib/samples/ogl}.
+
+\item[{\bf Frame Layout library}]
+FL provides sophisticated pane dragging and docking facilities.
+You can find this in {\tt contrib/src/fl}, {\tt contrib/include/wx/fl}, and {\tt contrib/samples/fl}.
+
+\item[{\bf Gizmos library}]
+Gizmos is a collection of useful widgets and other classes. Classes include wxLEDNumberCtrl,
+wxEditableListBox, wxMultiCellCanvas.
+You can find this in {\tt contrib/src/fl}, {\tt contrib/include/wx/fl}, and {\tt contrib/samples/fl}.
+
+\item[{\bf Net library}]
+Net is a collection of very simple mail and web related classes. Currently
+there is only wxEmail, which makes it easy to send email messages via MAPI on Windows or sendmail on Unix.
+You can find this in {\tt contrib/src/net} and {\tt contrib/include/wx/net}.
+
+\item[{\bf Animate library}]
+Animate allows you to load animated GIFs and play them on a window. The library can be extended
+to use other animation formats.
+You can find this in {\tt contrib/src/animate}, {\tt contrib/include/wx/animate}, and {\tt contrib/samples/animate}.
+
+\item[{\bf MMedia library}]
+Mmedia supports a variety of multimedia functionality. The status of this library is currently unclear.
+You can find this in {\tt contrib/src/mmedia}, {\tt contrib/include/wx/mmedia}, and {\tt contrib/samples/mmedia}.
+
+\item[{\bf Styled Text Control library}]
+STC is a wrapper around Scintilla, a syntax-highlighting text editor.
+You can find this in {\tt contrib/src/stc}, {\tt contrib/include/wx/stc}, and {\tt contrib/samples/stc}.
+
+\item[{\bf Plot}]
+Plot is a simple curve plotting library.
+You can find this in {\tt contrib/src/plot}, {\tt contrib/include/wx/plot}, and {\tt contrib/samples/plot}.
+\end{description}
 
 \chapter{Programming strategies}\label{strategies}
 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
@@ -628,9 +617,8 @@ to avoid problems.
 
 \subsection{Use wxWindows resource files}
 
-Use .wrc (wxWindows resource files) where possible, because they can be easily changed
-independently of source code. Bitmap resources can be set up to load different
-kinds of bitmap depending on platform (see the section on resource files).
+Use .xrc (wxWindows resource files) where possible, because they can be easily changed
+independently of source code.
 
 \section{Strategies for debugging}\label{debugstrategies}
 
@@ -691,25 +679,3 @@ will save a surprising amount of time in the long run.
 
 See the \helpref{debugging overview}{debuggingoverview} for further information.
 
-\subsection{Check Windows debug messages}
-
-Under Windows, it is worth running your program with 
-\urlref{DbgView}{http://www.sysinternals.com} running or
-some other program that shows Windows-generated debug messages. It is
-possible it will show invalid handles being used. You may have fun seeing
-what commercial programs cause these normally hidden errors! Microsoft
-recommend using the debugging version of Windows, which shows up even
-more problems. However, I doubt it is worth the hassle for most
-applications. wxWindows is designed to minimize the possibility of such
-errors, but they can still happen occasionally, slipping through unnoticed
-because they are not severe enough to cause a crash.
-
-\subsection{Genetic mutation}
-
-If we had sophisticated genetic algorithm tools that could be applied
-to programming, we could use them. Until then, a common -- if rather irrational --
-technique is to just make arbitrary changes to the code until something
-different happens. You may have an intuition why a change will make a difference;
-otherwise, just try altering the order of code, comment lines out, anything
-to get over an impasse. Obviously, this is usually a last resort.
-
