\chapter{Introduction}
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{What is wxWindows?}

wxWindows is a class library for C++ providing GUI (Graphical User
Interface) and other facilities on more than one platform.  It currently
supports subsets of Open Look (XView), Motif and Windows 3.1 (including
Windows NT).  It contains around 60 classes, with 650 public functions.

wxWindows was originally developed at the Artificial Intelligence
Applications Institute, University of Edinburgh, for internal use on a
medium-sized project: a hypertext-based knowledge-acquisition
and diagramming tool called HARDY. wxWindows has been released into
the public domain in the hope that others will also find it useful.

This manual discusses wxWindows in the context of multi-platform
development. For more detail on the wxWindows version 1.60 API
(Application Programming Interface) please refer to the separate
wxWindows reference manual.

Please note that in the following, ``Windows 3.1" 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?}

wxWindows was developed to provide a cheap and flexible way to maximize
investment in GUI application development.  While a number of commercial
class libraries already exist for cross-platform development (such as
CommonView and XVT++), none met all of the following criteria:

\begin{enumerate}
\item low price
\item source availability
\item simplicity of programming
\item support for GCC (GNU C++)
\item support for interprocess communication
\end{enumerate}

As public domain software and a project open to everyone, wxWindows has
benefited from comments, ideas, bug fixes, enhancements and the sheer
enthusiasm of users, especially via the Internet. This gives wxWindows a
certain advantage over its commercial brothers, and 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. wxWindows is likely to evolve to allow
more sophisticated GUI use on an increasing number of platforms.

In writing wxWindows, completeness has inevitably been traded for
portability and simplicity of programming. For projects which do not
need uncompromisingly polished interfaces, this tradeoff seems well
worthwhile given the productivity benefits.

wxWindows currently maps to four native APIs: XView (Open Look), Motif,
Windows 3.1 and Windows NT. Under UNIX, wxWindows has been tested most
thoroughly on Sun workstations, but users have confirmed that it
compiles on other machines (including some running UNIX System V). This
covers a very large proportion of machines in use today. An Apple Macintosh
version is being worked on by an external contributor, and an early demonstrator
is expected around September 1994.

In addition to GUI needs, wxWindows also supports a subset of DDE
(Dynamic Data Exchange) on both the PC and UNIX. A simple
object-oriented model of clients, servers and connections is used,
making it easy to write programs which communicate synchronously. Under
Windows, other non-wxWindows programs may still communicate with
wxWindows programs and vice versa; under UNIX, non-wxWindows programs
just have to conform to a simple protocol when communicating via sockets
with wxWindows programs.

On the PC, the tested compilers for wxWindows are Microsoft C/C++
Version 7 and (to a lesser extent) Borland C++ 3.1 and Turbo C++ for
Windows. Makefiles for MS C++ (Windows 3.1 and NT), and some 
for Borland C++, are provided.

Under UNIX, Sun C++, GNU C++ (GCC) and AT\&T C++ are known to work with
wxWindows.  See also \helpref{Requirements}{requirements}.

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, it provides access to most of the functionality a
GUI program normally requires, plus some extras such as form
construction, interprocess communication and PostScript output, and
can of course be extended as needs dictate.  As a bonus, it provides
an arguably cleaner interface to XView, Motif and Windows 3.1 than the native
APIs. Programmers may find it worthwhile to use wxWindows even if they
are developing on only one platform.

Here is a summary of some of the advantages of wxWindows:

\begin{itemize}
\item Low cost (free, in fact!)
\item You get the source.
\item Several example programs.
\item Over 200 pages of printable and on-line documentation.
\item Simple-to-use, object-oriented API.
\item No more messing with arcane X window calls under XView or Motif.
\item Graphics calls include splines, polylines, rounded rectangles, etc.
\item XView-style panel item layout.
\item Status line facility.
\item Easy, object-oriented interprocess comms (DDE subset) under UNIX and
Windows 3.1.
\item Encapsulated PostScript generation under UNIX, normal Windows 3.1 printing on the
PC.
\item Virtually automatic MDI support under Windows.
\item Can be used to create DLLs under Windows, dynamic libraries on the Sun.
\item Support for Windows 3.1 printer and file common dialogs, with
equivalents for UNIX.
\item Under Windows 3.1, support for creating metafiles and copying
them to the clipboard.
\item Programmatic form facility for building form-like screens fast,
with constraints on values.
\item Hypertext help facility, with an API for invocation from applications.
\item wxBuilder for building simple interfaces interactively, and generating
C++ code.
\end{itemize}

And here are some of the important downsides, so you can assess wxWindows's
applicability to your needs:

\begin{itemize}
\item No commercial support (but Internet support can be better!)
\item XView-style separation of frames, panels, canvases and text.
\item No constraint-based panel item layout -- panel layout is
not especially pretty.
\item Minimal colourmap support.
\end{itemize}

Figure \ref{demo-x} shows a demo application (described in the tutorial chapter)
running under X.

Figure \ref{demo-ms} shows the demo application running under Microsoft Windows 3.1.

\begin{figure}
$$\image{11cm;0cm}{hellox.ps}$$
\caption{Demo program running under X}\label{demo-x}
\end{figure}

\begin{figure}
$$\image{11cm;0cm}{hellow.ps}$$
\caption{Demo program running under Windows 3.1}\label{demo-ms}
\end{figure}

\section{wxWindows requirements}\label{requirements}

To make use of wxWindows, you currently need one or both of the
following setups.

(a) PC:

\begin{enumerate}
\item A 386SX or higher PC running Windows 3.1 or Windows NT.
\item Microsoft C/C++ version 7 or above, or Borland C++
version 3.1 (other compilers may work).
\item At least 5 MB of disk space.
\end{enumerate}

(b) UNIX:

\begin{enumerate}
\item GNU C++ version 2.1 or later, or compatible compiler (such as
Sun C++ or AT\&T C++)
\item A Sun or other workstation supporting GNU C++ and either XView 3.x
or Motif 1.2.x
\item At least 5 MB of disk space.
\end{enumerate}

\section{Availability and location of wxWindows}

wxWindows is currently available from the Artificial Intelligence
Applications Institute by anonymous FTP. FTP to:

\begin{verbatim}
skye.aiai.ed.ac.uk,
\end{verbatim}

log on as `anonymous', and give your user ID as password. Change
directory into pub/wxwin/beta, change transmission method to binary, and get
wx160?.tar.Z or wx160?.tgz (UNIX) and/or wx160?\_1.zip, wx160?\_2.zip, wx160?\_3.zip (PC)
where ? represents the release letter (currently a). Both archives contain
the source code for both platforms. The executable demos are available
as demo\_ol.tar.Z (the Sun 4 Open Look version), demo\_motif.tar.Z (the
Sun 4 Motif version) and demo.zip (the Windows version).

\begin{comment}
wxWindows 1.40 is in the {\tt programr} directory the CICA Windows 3.1
archive at Indiana University (ftp.cica.indiana.edu). Version 1.20 is
available from the British HENSA public domain software archive at
pdsoft.lancs.ac.uk in the directory {\tt x/a/a103}.
\end{comment}

It is also available by post from:

Dr Julian Smart,\\
Artificial Intelligence Applications Institute,\\
University of Edinburgh,\\
80 South Bridge,\\
Edinburgh,\\
Scotland,\\
EH1 1HN.\\
Email J.Smart@ed.ac.uk, tel. 031-650-2746.

It is distributed in tar and/or zip format on a high-density 3.5" MS-DOS
disk, with on-line PostScript, LaTeX and DVI format documentation. We
regret we cannot supply printed documentation. Please supply your own disk
and return postage, or enclose something to cover distribution
costs.

\section{Acknowledgments}

Thanks are due to the AIAI for being willing to release wxWindows into
the public domain, and to my wife Harriet Smart for her patience while I
worked on wxWindows at weekends.

The Internet has been an essential prop when coming up against tricky
XView, Motif and Windows 3.1 problems. Thanks to those who answered my
queries or submitted bug fixes and enhancements; wxWindows is very
much a team effort (although the bugs are mine!). In particular I
would like to mention: Jamshid Afshar, Patrick Albert, C. Buckley,
Robin Corbet, Harco de Hilster, Josep Fortiana, Torsten Liermann, Tatu
M\"{a}nnist\"{o}, Ian Perrigo, Giordano Pezzoli, Petr Smilauer, Neil Smith,
Kari Syst\"{a}, Jyrki Tuomi, Edward Zimmermann, Ian Brown.

`Graphplace', the basis for the wxGraphLayout library, is copyright Dr. Jos
T.J. van Eijndhoven of Eindhoven University of Technology. The code has
been used in wxGraphLayout with his permission.

I also acknowledge the author of XFIG, the excellent UNIX drawing tool,
from the source of which I have pinched some spline drawing code.
His copyright is included below.

{\it XFig2.1 is copyright (c) 1985 by Supoj Sutanthavibul. Permission to
use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of M.I.T. not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.  M.I.T. makes no representations about the
suitability of this software for any purpose.  It is provided ``as is''
without express or implied warranty.}

wxCLIPS (now distributed separately) builds on NASA's CLIPS expert
system shell, a paradigm of portability and a wonderful piece of
(nearly) free software.

\chapter{Resource guide}\label{resguide}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This is a list of other sources of information and software
related to wxWindows. For information of supplementary libraries in
the wxWindows distribution, see \helpref{Utilities}{utilities}.

\section{wxCLIPS}

wxCLIPS is distributed separately from wxWindows. It is available
from the /pub/wxclips directory of the AIAI ftp site; CLIPS2C,
a partial CLIPS to C++ converter, will be made available at the
same location.

\section{WinSock for wxWindows}

Giordano Pezzoli has implemented a WinSock version of the
wxWindows DDE implementation. This code enables client-server
applications to be written linking UNIX and PC platforms.

It is available in the /pub/wxwin/contrib directory of the AIAI ftp
site. as wxsocket.tar.Z or wxsocket.zip. Note that this is not
necessarily the most up-to-date version.

\section{GWX: DevGuide to wxWindows}\label{gwx}

This is a Sun DevGuide to wxWindows generator. It is available in the
/pub/wxwin/contrib directory of the AIAI ftp site, as gwx10.zip.
Note that this is not necessarily the most up-to-date
version.

\section{wxXPM}

This package adds the ability for wxWindows programs to read in
XPM colour bitmaps under both X and Windows. There's a neat
little animation, and a large selection of colour pixmaps.

It is available in the /pub/wxwin/contrib directory of the AIAI ftp
site, as wxxpm01.zip. Note that this is not necessarily the most up-to-date
version.

\section{CURSES port}

Harco de Hilster is working on a CURSES port of wxWindows. A beta is
available in the /pub/wxwin/contrib directory of the AIAI ftp site, as
wxcurs.tar.gz. Note that this is not necessarily the most up-to-date
version.

\section{Imakefiles}

Imakefiles are highly flexible in dealing with different sites
and configurations. It has been suggested that wxWindows
makefiles should be Imakefiles. Perhaps one day!

Meanwhile, Patrick Albert's Imake kit is in /pub/wxwin/contrib
as imake.zip. Note that it is not up to date with respect
to wxWindows, but should give a head start in using Imakefiles.

\section{QDB database}

QDB is a user-contributed database that can read and write DBASE files.
As the author points out, the interface has not had much time spent on it.
However, it could be a good basis for a student project.

QDB is available in the /pub/wxwin/contrib directory of the AIAI ftp site
as qdb.zip. The author, Dave Curtis, can be contacted at
dcurtis@hgmp.mrc.ac.uk.

\section{MEWEL}

MEWEL is a commercial library from Magma that allows Windows source code
to be compiled for DOS graphics, DOS text and OS/2 text mode. Magma use
wxWindows as one of their demonstrations; a beta of version 1.50
apparently compiled with no modifications.

See below for contact information.

\begin{verbatim}
                          The MEWEL Window System
Portable User Interface Library for Text and Graphics and Microsoft Windows

Magma Systems
15 Bodwell Terrace
Millburn, New Jersey 07041
(201) 912-0192 (voice)
(201) 912-0668 (24 hour BBS, USR HST Dual Standard, 9600-1200 baud, N-8-1)
(201) 912-0103 (fax for orders only)

CIS : 75300,2062. To get to our conference, GO MAGMA.
BIX : magma. Our conference is the 'magma' conference.
Internet : 75300.2062@compuserve.com (preferred) or magma@bix.com.

Thank you very much for expressing your interest in Magma Systems' MEWEL
user interface library. MEWEL 4.0 gives your application complete portability
between Microsoft Windows, DOS text, DOS graphics, OS/2 text, UNIX text,
VMS text, and soon, OSF Motif. Since MEWEL's API is compatible with the
standard Microsoft WIndows API, you can easily port programs between Win-
dows and any of the environments which MEWEL supports, even if you already
have existing Windows programs.

Programmers can develop new stand-alone applications using MEWEL, or can port
their existing Windows applications to any of the platforms which MEWEL
supports.
\end{verbatim}

\section{wxWindows mailing list}

There is an Internet mailing list for wxWindows discussion. Please
send email to:

\begin{verbatim}
wxwin-users-request@aiai.ed.ac.uk or J.Smart@ed.ac.uk
\end{verbatim}

to be added to either the discussion or the announcements list.
Announcements are generally posted to wxwin-users too, so
there is no need to be subscribed to both.

\section{World Wide Web}

You can view the documentation for wxWindows on the World Wide Web
using a viewer such as Mosaic.  The wxWindows home page is at:

\begin{verbatim}
 http://www.aiai.ed.ac.uk/~jacs/html/wxwin.html
\end{verbatim}

If you wish to set up a local HTML version of the wxWindows
documentation, to be viewed with Mosaic in preference to wxHelp, you can
compile Tex2RTF in order to produce the HTML files from the \LaTeX\ sources.
The target 'html' exists in the makefiles for most packages in the wxWindows
toolset, although they will need to be edited to copy the resulting HTML
files to a sensible place.

\begin{comment}
\section{Ongoing projects}

This is a list of wxWindows projects being undertaken
by Julian Smart and others.

{\small
\verbatiminput{projects.txt}
}
\end{comment}
%
\chapter{Overview and comparison with other GUI models}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

wxWindows takes elements of other GUI APIs, and adds some elements of
its own.  Of course, it cannot hope to cover every (or even one) native
API completely.  The following sections discuss different GUI models
and compare these with what wxWindows provides.

\section{Windows}

An application presents the user primarily with a series of windows. A
window can be made up of a {\it frame} with one or more subwindows. This
is like the XView model, rather than Motif or Windows 3.1 where child
windows may be nested to any depth.  The frame method was chosen since
XView required it, and because it is a useful simplifying assumption,
imposing few restrictions in practise. Note that the splitting of views
beloved of the Open Look standard is not allowed in wxWindows.

A frame window may be parentless or a child of another frame, and may
be iconized. It may have a {\it menu bar}, a row of pull-down menus
along the top of the frame.  Subwindows within a frame come in three
varieties: the {\it panel}, {\it canvas} and {\it text subwindow}.  A
panel is used for buttons, lists and other such user input items, while
a canvas is used for drawing graphics such as lines and shapes.  Panel
items pass high-level notification of user interaction to the program,
whereas any interaction with objects on a canvas must be programmed at a
lower level.

In Windows 3.1, canvases need to be painted using a handle to a `device
context'. The purpose of this is to enable the same code to draw into a
number of different devices, such as printers, windows, bitmaps and
metafiles. wxWindows also has the notion of a device context, but most
drawing commands may also be directly issued to a canvas for
convenience. An application which implements a function to draw into the
base device context, {\bf wxDC} will be able to pass any device context
object to this drawing function, including {\bf wxPostScriptDC}, {\bf wxCanvasDC},
{\bf wxMetaFileDC}, and {\bf wxMemoryDC}.

wxWindows defines several objects required for drawing on canvases:
colours, fonts, pens and brushes. Neither XView nor Motif provides pens
and brushes, which in Windows 3.1 allow the selection of different
predefined `drawing tools' with certain characteristics (line thickness,
colour, fill style etc.). Normally in X there is a limited range of
fonts (scaleable fonts are a recent addition), while in Windows 3.1 an
infinite selection of sizes is available thanks to the scaleable
TrueType font system. Under XView and Motif, wxWindows chooses the closest
matching font.

Windows 3.1 or Motif programmers may miss the ability to place panel items
in canvases (to use XView terminology), or to draw graphics in panels. A
future version of wxWindows may support drawing on panels, particularly
in the Motif and Windows versions, lifting these restrictions. Support
for displaying panel items and drawing graphics will probably be moved
up to the base {\bf wxWindow} class, maintaining compatibility with
existing wxWindows programs but allowing new programs more flexibility.

\subsection{MDI versus SDI}\label{mdi}

In Windows 3.1, a popular technique is to use the MDI (Multiple Document
Interface) style, where the application window has a number of
iconizable document windows which fit within it. This can save clutter
on the desktop since iconizing or moving the parent window iconizes or
moves all the child windows. MDI contrasts with SDI (Single Document
Interface) in which windows are not constrained within one parent
window, and normal practice is to run one instance of the application
per document. Since wxWindows uses the large model, and large model
programs may be limited to one instance at a time (unless only one data
segment is used), it makes sense to offer MDI support. See
\rtfsp\helpref{Memory Models}{memorymodels}.

I have decided to include largely automatic, albeit relatively
inflexible, support for MDI for these reasons:

\begin{itemize}
\item Since it is likely that wxWindows programmers are writing for
multiple platforms, and only Windows 3.1 supports MDI, they will not wish
to spend much or any time implementing MDI features.
\item The difference between writing MDI and SDI applications
has been reduced to almost zero so even the beginner
can easily produce MDI programs.
\item What wxWindows's auto-MDI cannot handle is hardly worth the extra
effort anyway.
\end{itemize}

In wxWindows, one argument of the frame constructor is used to
indicate whether the frame is an SDI frame, an MDI parent frame or an
MDI child frame. The default is to create an SDI frame. Once MDI
frames are created, everything else is automatic, including appending
the usual {\bf Window} menu option, and moving a child menu to the
parent frame when the child frame is activated.  The choice of menu
items for an MDI child frame will differ slightly, usually including
menus (such as Quit) which would normally be on the main SDI window,
but this only requires a small amount of extra application code.

The demo program {\bf mdi} shows how a program can easily be made
switchable between SDI and MDI - use the {\bf -mdi} command switch for
MDI operation.

\section{Dialog boxes}\label{dialogs}

A {\it dialog box} is like a panel, with an implicit frame surrounding
it. A dialog box may be {\it modal} (no other window in this application
is active and the calling program flow is suspended) or {\it modeless}
(any window may be interacted with and control returns immediately to
the program). With dialog boxes, creation of separate frames and panels
is not necessary, and under Windows 3.1, additional functionality is added
`for free', such as tabbing between items. Any panel item may be
attached to a dialog box since wxDialogBox is derived from the wxPanel.

Note that under Windows 3.1, modal dialogs have to be emulated using
modeless dialogs and a message loop. This is because Windows 3.1 expects
the contents of a modal dialog to be loaded from a resource file or
created on receiving a dialog initialization message. This is too
restrictive for wxWindows, where any window may be created and possibly
displayed before its contents are created.

Standard dialogs are provided for printer settings, file selection,
short messages, single-line text string entry and scrolling
single-selection lists.

\section{Menus}

Menus are used in menu bars and popup menus. A menu bar is a sequence of
pull-down command menus near the top of the window, usually with a {\bf
File} menu as the first menu. In Windows 3.1 and Motif, the menu bar is
a standard user interface component. Under XView, wxWindows must
simulate a menu bar with a series of menu buttons. Under wxWindows for
Motif and Windows 3.1, but not XView, placing and ampersand before a
letter in a menu name causes it to be underscored and interpreted as a
keyboard shortcut. Under XView such underscores are ignored. The Motif
version of wxWindows automatically right-justifies the help menu, if
there is one.

Menu items are identified by integer identifiers, and for menu bars,
when a menu item is selected, the parent frame is notified using the\rtfsp
{\bf OnMenuCommand} member. For popup menus, a callback function is
executed.

\section{Events}

In XView and Motif, events (such as resizing, painting, mouse clicks, button
presses) are handled by a rather arbitrary collection of optional
XView and Xlib callbacks. In Windows 3.1, events are {\it messages}\rtfsp
which are handled by a window procedure, or ignored.

In wxWindows, an application's GUI objects mostly receive events by
wxWindows calling user-overridable handlers, such as {\bf OnEvent}, {\bf
OnChar} and {\bf OnSize}.  Frames can receive {\bf OnClose} events from
the window manager (X) or system control menu (Windows 3.1). These events
are handled by the application by deriving new frame classes and
overriding the event-handling member functions.

Panel item notification has to be handled rather differently. In
Windows 3.1, all panel item events (such as a button press) are sent to
the parent window (requiring large case statements to differentiate
the events), and all window events are sent to the relevant window. In
XView and Motif, different types of callback function have to be defined,
depending on the event.

In wxWindows, panel items have optional callback functions, but there is
only one callback type: the function takes the object and a command event
structure.  The class derivation approach cannot be extended to panel
items since it does not make sense to derive a new class for every
individual panel item created.

\subsection{The wxWindows event system}

From Version 1.5, wxWindows has its own event system. Event classes are
derived from the abstract base class wxEvent (which used to serve as a
holder for canvas and panel item events). An event {\it class}
encapsulates a range of similar event {\it types}. For example, the
instances of the {\bf wxMouseEvent} class may be generated for a number
of event types such as {\bf wxEVENT\_TYPE\_LEFT\_DOWN}.

There are several motivations for having an explicit representation
for events.

Firstly, encapsulating events in structures makes sense compared
with passing an event handler a large number of arguments.

Secondly, user input events may be simulated by sending events; this can
be used for automating GUI testing, and events could (in theory) be
stored for later playback. 

Thirdly, event handlers can be installed by programs or `meta-programs'
which want to override or examine program behaviour. For example, special-needs
access code could be written to enable GUI events to be expressed to the
user in a non-graphical form. Or, a meta-program could examine the
dialog structure of a running application and output a skeleton help file
corresponding to the application's hierarchy of menus and dialogs, taking
some of the donkey work out of preparing on-line help.

The event system is meant to be user-extensible so that any GUI-related
or application-specific events may be defined and used in a consistent
way. However, it is not yet completed and documented, and it is expected
to evolve over the next few releases. The eventual aim is an event
system which is comprehensive enough to enable wxWindows programs to be
tested automatically using scripts (possibly using NASA's CLIPS as the
scripting language -- see \helpref{CLIPS}{clips}).

\section{Keyboard input}

From Version 1.5, wxWindows defines platform-independent constants for
most common keys, including function and cursor keys. The virtual
keycodes for standard ASCII characters are the ASCII codes themselves,
unlike under Windows. Key presses are sent to the {\bf OnChar} member
of a window with a {\bf wxKeyEvent} argument, which can be used to
determine the state of the shift and control keys as well as finding the
virtual key code of the depressed key.

The {\bf wxCanvas} class has a default {\bf OnChar} handler which scrolls
the canvas using the cursor keys.

\section{Repainting of windows}

All windows except for the canvas are repainted by the system.  The
canvas requires a paint message handler to be defined (and therefore
canvas derivation is obligatory). Under XView and Motif, wxWindows
allows a canvas to be retained if desired, which means that fewer
paint messages are received and scrolling is fast. The Motif implementation
has a slight overhead in that drawing must be done both to the canvas
and to the backing pixmap, but this is usually made up for by the speed
of repainting.

The repaint procedure will obviously be written in such a way that the
minimum amount of work needs to be done (for example, positions of
objects on a canvas are only recalculated when the positions change).

See \helpref{Scrolling}{scrolling} for more information on repainting and scrolling.

\section{Scrolling}\label{scrolling}

Scrolling can be a tricky subject for a novice GUI programmer to tackle.
The Windows 3.1 API ensures that the suffering is as acute as possible by
requiring the application to program the scrollbar behaviour, to check
the scrollbar positions on repainting, and to reposition the scroll bars
on window resizing.  XView has the decency to provide a canvas event
with coordinates that reflect what the scrollbars are doing. In
wxWindows, the XView approach is taken, so that all the programmer has
to do is to create scrollbars with a given scroll length and increment,
and the repaint procedure automatically reflects scrollbar positions. 
Obviously this simple approach can be inefficient if the canvas doesn't
know what is actually in view, so the application can get the current
view in order to limit the amount of repainting required.

It is possible to tell a wxWindows canvas to be {\it retained} (though
this only has an effect in XView and Motif). In this case no repaint events will happen
when scrolling since the system remembers what was drawn and simply moves
a bitmap around.

Under Windows 3.1, wxWindows scrolls the bits of the canvas around
when the user generates a scroll event, so the canvas does not need to
be cleared and only the damaged areas need be repainted---so all the
application need do is redraw the whole image, and scrolling will appear to be
relatively smooth. This is the case in the {\tt hello.exe} demo.

However, there are times when we can't allow the system to scroll the
bits of the image, for example when a scroll increment will result in
an unpredictable actual movement of the image. This is true for wxHelp, since
scrolling is in terms of lines, and lines vary in height. If we left
it up to wxWindows to scroll without clearing the screen, the text
would then overlay some of the previous screen since the old and new
images will probably not exactly match.

In the wxHelp application (see \helpref{wxHelp}{wxhelp}) the horizontal
direction is scrolled in terms of pixels, not character widths, and so
wxWindows can be left to scroll the image smoothly, without having to
clear before repainting. This kind of control is avilable by using {\bf
wxCanvas::EnableScrolling}.

Scrolling panels have yet to be implemented in wxWindows.

\section{Printing}

Printing in Windows 3.1 is relatively easy, since all drawing is done to
a `device context' which could equally well be associated with a
printer as with a window. Windows 3.1 handles the plethora of printer
types that abound in the PC environment. In X under UNIX, the standard
is PostScript; X, XView and Motif provide no help at all. The solution
adopted in wxWindow is to use a device context for canvases and
printers, with Windows 3.1 printing supported on the PC and an
Encapsulated PostScript driver provided under X. Thus graphic code may
be extremely generic - the same piece of code can draw to Windows 3.1
screens of all types, to X windows, and to hundreds of different
printers.

\section{Programmatic versus interactive GUI building}

Interactive tools for rapidly building GUIs are all the rage, and
wxWindows has a simple screen painter and code generator called
wxBuilder.

A different solution is taken by \helpref{GWX}{gwx} which
translates DevGuide files into wxWindows code, which has
the advantages and disadvantages on relying on a third party
GUI-building tool. It is also possible to translate some
Windows .RC files into wxBuilder menus and dialog boxes,
although the quality of the translation varies from good
(with most menu bar definitions) to poor (for most dialogs).

It is not always possible to build GUI components interactively: the
`what you see is {\it all} you get' syndrome. When complex repositioning
of items depending on window size is required, then GUI builders
cannot be relied upon.

Using a toolkit with geometry management may be no panacea, either; for
example, the Motif constraint algorithm is difficult to understand and
much experimentation is necessary to make things work. The approach
taken by wxWindows is in keeping with the main goal of simplicity:
wxWindows has the ability to create panel items from left to right, top
to bottom with appropriate horizontal and vertical spacing; or the
programmer may position the panel items explicitly. The first method
gives resolution and font independence, and is less fiddly, and the
second method may be used for tidying up a display for a specific
platform.

\section{Dimensions}

The graphics origin is always the top left hand corner of a window.
Dimensions are a problem in a multi-platform application, since display
and character widths will change from machine to machine, even more so
than for different PC display boards. At the moment wxWindows uses
pixels; Windows 3.1 tackles the problem by using `dialog units' based on
the size of the standard system font.  To avoid this problem when
creating panel items, wxWindows provides automatic left to right, top to
bottom item layout (similar to XView), in addition to absolute
positioning, in which case, portability is up to the discretion of the
programmer.

A canvas has a {\it mapping mode}\/ associated with it, which determines
the meaning of dimensions in subsequent graphics operations. Drawing may
be done using various units including mm, 1/10 mm, pixels and points.
Mapping modes other than pixels cannot be relied upon, however; future
versions of wxWindows may support mapping modes better, and allow a
change of graphics origin.

\section{Colour}

The presence of a monochrome screen can be detected so the application
can change its use of colour accordingly. Currently, wxWindows tries to
choose appropriate pen and brush colours for a monochrome display. To
override this behaviour, set the device context {\bf Colour} member to
TRUE and choose custom colours for drawing graphics.

The \helpref{Colours}{coloursampler} utility can be useful for displaying
colours and their names.

Colourmaps (or palettes) are supported only for colourmaps that have
been created by platform-specific utilities such as the DIB and wxImage
utilties. So you can associate a colourmap with a window or device
context, but functions to create and manipulate colourmaps are lacking.
Future versions of wxWindows should improve upon colourmap handling.

\section{On-line help}

Most modern GUI applications have on-line hypertext help. In Windows
3.1, help is normally supplied in binary files which are read by an external
program, which is itself accessed from within the application using
Microsoft-supplied function calls. XView has provisions for simple
context sensitive help, but no equivalent of the Windows 3.1 browseable
help.

From version 1.30, wxWindows comes with wxHelp, a hypertext help
system which may be invoked from wxWindows applications. However, a
wxWindows program may specify that under Windows 3.1, WinHelp should
be used instead of wxHelp. wxHelp may be seen as a `last resort' if the
GUI system does not have a native help facility.

Please see \helpref{wxHelp}{wxhelp} and the separate wxHelp manual for
further details.

wxWindows programmers may wish to follow the example of the wxWindows
documentation, and prepare their manuals in a \LaTeX\ form. The supplied
\rtfsp\helpref{Tex2RTF}{textortf} utility may then be used to generate
online help in a variety of paper and on-line hypertext formats, including
wxHelp and Windows Help.

\section{User preferences}

In both X and Windows, there are mechanisms for handling user
preferences, or resources. Under X, there is a global .Xdefaults
file plus inidividual application defaults files. Under Windows,
either win.ini or application specific .ini files are used.

wxWindows unifies these with {\bf wxGetResource} and\rtfsp
{\bf wxWriteResource} functions: section, entry, value and
file arguments may be specified.

In X, a section is the first word in a resource specification; in
Windows, this is enclosed in square brackets on a line of its own.  In
X, an entry is taken to mean the rest of a resource specification, and
in Windows this is a name followed by an equals character.
The value is an arbitrary string in both cases, although wxWindows
overloads the resource functions for commonly used types.

If the resource filename is omitted, the main resource file is assumed
(.Xdefaults or win.ini). Under X, if an application class
(wxApp::wx\_class) has been defined, it is appended to the string
/usr/lib/X11/app-defaults/ to try to find an applications default
file when merging all resource databases.

\section{Interprocess Communication}\label{ipc}

\subsection{What wxWindows has}

Interprocess communication (IPC) has always been a tricky area, and the
plethora of techniques on different platforms has not helped. Microsoft
has laid down several standards for IPC under Windows 3.1, the most
established (if long in the tooth) being Dynamic Data Exchange (DDE).
DDE is the basis for wxWindows's IPC capability: the same, simple,
object-oriented interface is provided for a subset of DDE under both
Windows on the PC, and under XView and Motif on UNIX. The UNIX version
is implemented using sockets, and allows processes on the same or
different machines to talk to each other.

The benefits of wxWindows's DDE package are twofold: much greater
simplicity compared with raw DDE and UNIX sockets; and the considerable
advantage of keeping to platform-independence even in this notoriously
platform-dependent area. Currently only synchronous transactions are
handled; a later version of wxWindows may support asynchronous
transactions also.

A user-contributed package is available that replaces the wxWindows
implementation of DDE with a WinSock implementation, to allow
communication between Windows and UNIX. The API of that package is
identical to the one described in this manual. The WinSock implementation
will probably soon be incorporated into wxWindows.

\subsection{Principles of DDE}

The following describes how wxWindows implements DDE.  The following
three classes are crucial.

\begin{enumerate}
\item wxClient. This represents the client application, and is used
only within a client program.
\item wxServer. This represents the server application, and is used
only within a server program.
\item wxConnection. This represents the connection from the current
client or server to the other application (server or client), and can be used
in both server and client programs. Most DDE
transactions operate on this object.
\end{enumerate}

Messages between applications are usually identified by three variables:
connection object, topic name and item name.  A data string is a fourth
element of some messages. To create a connection (a conversation in
Windows parlance), the client application sends the message {\bf
MakeConnection} to the client object, with a string service name to
identify the server and a topic name to identify the topic for the
duration of the connection. Under UNIX, the service name must contain an
integer port identifier.

The server then responds and either vetos the connection or allows it.
If allowed, a connection object is created which persists until the
connection is closed.  The connection object is then used for subsequent
messages between client and server.

To create a working server, the programmer must:

\begin{enumerate}
\item Derive a class from wxServer.
\item Override the handler {\bf OnAcceptConnection} for accepting or rejecting a connection,
on the basis of the topic argument. This member must create and return a connection
object if the connection is accepted.
\item Create an instance of your server object, and call {\bf Create} to
activate it, giving it a service name.
\item Derive a class from wxConnection.
\item Provide handlers for various messages that are sent to the server
side of a wxConnection.
\end{enumerate}

To create a working client, the programmer must:

\begin{enumerate}
\item Derive a class from wxClient.
\item Override the handler {\bf OnMakeConnection} to create and return
an appropriate connection object.
\item Create an instance of your client object.
\item Derive a class from wxConnection.
\item Provide handlers for various messages that are sent to the client
side of a wxConnection.
\item When appropriate, create a new connection by sending a {\bf MakeConnection}
message to the client object, with arguments host name (processed in UNIX only),
service name, and topic name for this connection. The client object will call {\bf OnMakeConnection}
to create a connection object of the desired type.
\item Use the wxConnection member functions to send messages to the server.
\end{enumerate}

\subsection{Data transfer}

These are the ways that data can be transferred from one application to
another.

\begin{itemize}
\item {\bf Execute:} the client calls the server with a data string representing
a command to be executed. This succeeds or fails, depending on the
server's willingness to answer. If the client wants to find the result
of the Execute command other than success or failure, it has to explicitly
call Request.
\item {\bf Request:} the client asks the server for a particular data string
associated with a given item string. If the server is unwilling to
reply, the return value is NULL. Otherwise, the return value is a string
(actually a pointer to the connection buffer, so it should not be
deallocated by the application).
\item {\bf Poke:} The client sends a data string associated with an item
string directly to the server. This succeeds or fails.
\item {\bf Advise:} The client asks to be advised of any change in data
associated with a particular item. If the server agrees, the server will
send an OnAdvise message to the client along with the item and data.
\end{itemize}

The default data type is wxCF\_TEXT (ASCII text), and the default data
size is the length of the null-terminated string. Windows-specific data
types could also be used on the PC.

\subsection{Examples}

See the sample programs {\it server}\/ and {\it client}\/ in the IPC
samples directory.  Run the server, then the client. This demonstrates
using the Execute, Request, and Poke commands from the client, together
with an Advise loop: selecting an item in the server list box causes
that item to be highlighted in the client list box.

See also the source for wxHelp, which is a DDE server, and the files
wx\_help.h and wx\_help.cc which implement the client interface to
wxHelp.

\subsection{Remote Procedure Call}

DDE is quite a low level protocol, and all encoding and decoding of
messages must be done by the client and server applications. The
wxWindows extension {\it PROLOGIO}\/ implements a remote procedure call
protocol (RPC) so that a server can implement a library of functions for
a client to call.  PROLOGIO makes it easy for applications to pack and
unpack the arguments and return value(s) of procedure calls, and
provides a mechanism for the server to register its available calls and
automatically handle the routing of calls to appropriate server
callbacks, one to a procedure definition. All this makes calling or
implementing server facilities childishly simple. Since PROLOGIO sits on
top of the DDE wrapper, it is also platform independent. See the
separate PROLOGIO manual and \helpref{PROLOGIO}{prologio}.

\chapter{Multi-platform development with wxWindows}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This chapter describes the practical details of using wxWindows. Please
see the file install.txt for up-to-date installation instructions, and
changes.txt for differences between versions.

\section{Code structure}

Since version 1.50, the files have been split as much as possible into
command and platform-specific code. The {\tt include} and {\tt src} directories
each have a {\tt base} directory for the common code, plus a directory for
each platform, currently {\tt msw} and {\tt x}. Because much X functionality
is shared, the Motif and XView versions are contained in the same files, separated
by conditional compilation statements. This structure should make it easy
both to implement support for new platforms, and to edit the existing code.

In order to provide separate out the base functionality from the
platform-specific functionality, each wxWindows class is composed of two
classes: a base for the common code with prefix {\bf wxb}, and a derived
class for the platform with prefix {\bf wx}. Base files have a {\bf
wb\_} prefix whilst platform-specific files (or files which {\it never}
have corresponding platform-specific code) have a {\bf wx\_} prefix.

For example, the {\bf wxCanvas} class is declared for each platform, and
derives from {\bf wxbCanvas}. The relevant files for this class may
therefore be found as follows:

\begin{verbatim}
include\base\wb_canvs.h
include\msw\wx_canvs.h
include\x\wx_canvs.h
src\base\wb_canvs.cc
src\msw\wx_canvs.cc
src\x\wx_canvs.cc
\end{verbatim}

Each {\bf wx\_} header file includes the corresponding {\bf wb\_} header file.

\section{Include files}

Under both operating systems, include the file {\tt "wx.h"}, or to save
on compilation time, include only those header files relevant to the
source file. If you are using precompiled headers, you should include
{\tt "wx.h"} only. The main header files (omitting base class files) are
as follows.

\begin{itemize}
\item common.h - important definitions and includes (included by wx.h)
\item wx.h - includes all wxWindows headers
\item wx\_setup.h - configuration file for wxWindows optional features
\item wx\_buttn.h - button panel item
\item wx\_canvs.h - drawing on canvases
\item wx\_check.h - check box panel item
\item wx\_dc.h - drawing on canvases and printers
\item wx\_dccan.h - canvas device context
\item wx\_dcmem.h - memory device context
\item wx\_dcps.h - PostScript device context
\item wx\_dialg.h - user-defined and standard dialogs
\item wx\_form.h - forms allow succinct expression of panels with
constrained items
\item wx\_frame.h - frame window handling
\item wx\_gdi.h - graphics objects such as colours, pens, brushes and icons
\item wx\_help.h - API for invoking wxHelp
\item wx\_hash.h - hash table implementation
\item wx\_ipc.h - interprocess communication (using a subset of the DDE standard)
\item wx\_ipcob.h - client or server object class
\item wx\_item.h - panel item base class
\item wx\_lbox.h - list box panel item
\item wx\_list.h - linked list implementation, heavily used by wxWindows
\item wx\_main.h - application initialization
\item wx\_menu.h - menus
\item wx\_messg.h - message panel item
\item wx\_mf.h - metafile class
\item wx\_mgstr.h - language-specific strings (experimental)
\item wx\_mnuit.h - menu item (for internal use by menus only)
\item wx\_mtxt.h - multitext panel item
\item wx\_obj.h - base class for wxWindows classes
\item wx\_panel.h - panels
\item wx\_privt.h - some private wxWindows definitions
\item wx\_rbox.h - radio box panel item
\item wx\_stdev.h - standard event class definitions
\item wxstring.h - a simple string class
\item wx\_sysev.h - system event definitions
\item wx\_text.h - text subwindows
\item wx\_timer.h - timer object
\item wx\_txt.h - single-line text panel item
\item wx\_types.h - explicit type system
\item wx\_utils.h - various utilities
\item wx\_win.h - abstract base class for frames, subwindows and items
\end{itemize}

\section{Libraries}

Under UNIX, use the library libwx\_ol.a (XView) or libwx\_motif.a
(Motif).  Under DOS, use the library wx.lib for stand-alone Windows
applications, or wxdll.lib for creating DLLs.

\section{Configuration}

The following lists the options configurable in the file
\rtfsp{\tt include/base/wx\_setup.h.} 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.

\subsection{General features}

\begin{twocollist}
\twocolitem{USE\_POSTSCRIPT}{If 1, PostScript code is compiled.}
\twocolitem{USE\_METAFILE}{If 1, Windows Metafile code is compiled.}
\twocolitem{USE\_FORM}{If 1, wxForm code is compiled.}
\twocolitem{USE\_IPC}{If 1, interprocess communication code is compiled.}
\twocolitem{USE\_HELP}{If 1, interface to help system is compiled.}
\twocolitem{USE\_ENHANCED\_DIALOG}{If 1, enhanced dialog box code is compiled.}
\twocolitem{USE\_RESOURCES}{If 1, resource read/write code is compiled.}
\twocolitem{USE\_CLIPBOARD}{If 1, clipboard code is compiled (Windows only).}
\twocolitem{USE\_SPLINES}{If 1, spline code is compiled.}
\twocolitem{USE\_XFIG\_SPLINE\_CODE}{If 1, XFig-derived code is used for spline
drawing. If 0, AIAI code is used, which is slower.}
\twocolitem{USE\_DRAG\_AND\_DROP}{If 1, drag and drop code is compiled (Windows only).}
\twocolitem{USE\_PANEL\_IN\_PANEL}{If 1, experimental panel-in-panel code is used
for common dialog boxes. Not recommended, since tab traversal can suffer.}
\twocolitem{USE\_TYPEDEFS}{If 1, a typedef will be used for wxPoint instead of
a class declaration, to reduce overhead and avoid a Microsoft C++ memory bug.}
\twocolitem{ENHANCED\_FONTS}{Define to be 1 to have pre-defined fonts in wxEnhDialogBox.}
\end{twocollist}

\subsection{X features}

\begin{twocollist}
\twocolitem{PIXEL0\_DISABLE}{Define to disallow allocation of pixel 0 (wxXOR problem).}
\twocolitem{DEFAULT\_FILE\_SELECTOR\_SIZE}{Let Motif choose the size of
XmFileSelectionBox. Otherwise, size is 500x600.}
\twocolitem{USE\_GADGETS}{Use gadgets where possible rather than Widgets for items.
Default is to use Gadgets.}
\twocolitem{USE\_BUTTON\_GADGET}{Use gadgets for buttons. This can intefere with
default button selection, so the default is zero.}
\twocolitem{wxFSB\_WIDTH}{Width of file selector box, if fixed.}
\twocolitem{wxFSB\_HEIGHT}{Height of file selector box, if fixed.}
%\item[MOTIF\_MANAGE]%
%If defined, dialog are managed rather mapped by default.%
%A style flag controls map/manage dialog creation time.%
\end{twocollist}

\subsection{Windows and NT features}

\begin{twocollist}
\twocolitem{CTL3D}{It is recommended that CTL3D is used under Windows, since the 3D effects
are good-looking and will be standard with Windows 4.0.  Howver, the default for
wxWindows is not to use it. If you want to use it and don't already have
CTL3D installed, copy the files in contrib/ctl3d to appropriate places
(ctl3d.lib into your compiler lib directory, ctl3d.h into an include
directory, and ctl3dv2.dll into windows/system). ctl3d.lib {\it should} work
with all compilers. Define CTL3D to be 1 in wx\_setup.h and link your
executables with CTL3D.LIB.

If both CTL3D and FAFA are set to 1, then all controls except wxButton
will use CTL3D and have 3D appearances. wxButton will have the ability
to use bitmaps. This is the recommended configuration.}
\twocolitem{FAFA\_LIB}{Define this to be 1 if you wish to use the Fafa enhanced
control library (in the contrib directory). The Fafa library is mandatory for use of
bitmap buttons.

An application using the Fafa library must include fafa.rc in the
its RC file. Otherwise, some controls will not show up.}
\twocolitem{USE\_GREY\_BACKGROUND}{If 1, will use grey for panel and
dialog backgrounds (Julian Smart's preferred setting). Grey is used
by CTL3D anyway. If this is set to 0 and USE\_FAFA is set to 1,
you may see unsatisfactory display of some control backgrounds.

If both CTL3D and FAFA are set to 1, then all controls except wxButton
will use CTL3D and have 3D appearances. wxButton will have the ability
to use bitmaps. This is the recommended configuration.}
\end{twocollist}

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

Sample makefiles for UNIX (suffix .UNX), MS C++ (suffix .DOS and .NT), Borland
C++ (.BCC) and Symantec C++ (.SC) are included for the library, demos
and utilities. The NT, Borland and Symantec makefiles cannot be
guaranteed to be up-to-date since the author does not have
these compilers.

The controlling makefile for wxWindows is in the platform-specific
directory, such as {\tt src/msw} or {\tt src/x}. This makefile will
recursively execute the makefile in {\tt src/base}.

\subsection{DOS makefiles}

For Microsoft C++, normally it is only necessary to type {\tt nmake -f
makefile.dos} (or an alias or batch file which does this). By default,
binaries are made with debugging information, and no optimization. Use
FINAL=1 on the command line to remove debugging information (this only
really necessary at the link stage), and DLL=1 to make a DLL version of
the library, if building a library.

\subsection{UNIX makefiles}

All makefiles have the targets {\it xview}, {\it motif} and {\it hp}.

{\it xview} builds an Sun Open Look version of the library, {\it motif}
builds a Sun Motif version, and {\it hp} builds a Motif version for HP
workstations.

Remove object files, executables and libraries for the
current module with the {\it clean\_ol} and {\it clean\_motif} and
\rtfsp{\it clean\_hp} targets.

It is possible to maintain simultaneous Motif and Open Look versions
of an application, since object files are kept in separate directories
({\it objects\_ol} and {\it objects\_motif}).

Debugging information is included by default; you may add DEBUG= as an
argument to make to compile without it, or use the UNIX {\bf strip}
command to remove debugging information from an executable.

\normalbox{{\it Important note:} Most compiler flags are kept centrally in
src/make.env, which is included by all other makefiles. This is the
file to edit to tailor wxWindows compilation to your environment.}

\section{Windows-specific files}

wxWindows application compilation under Windows 3.1 requires at least two
extra files, resource and module definition files.

\subsection{Resource file}\label{resources}

The least that must be defined in the resource file (extension RC)
is the following statement:

\begin{verbatim}
rcinclude wx.rc
\end{verbatim}

which includes essential internal wxWindows definitions.  The resource script
may also contain references to icons, cursors, etc., for example:

\begin{verbatim}
wxicon icon wx.ico
\end{verbatim}

The icon can then be referenced by name when creating a frame icon. See
the Windows 3.1 SDK documentation.

\normalbox{Note: include wx.rc {\it after} any ICON statements
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) 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{Memory models and memory allocation}\label{memorymodels}

Under UNIX, memory allocation isn't a problem. Under Windows, the only
really viable way to go is to use the large model, which uses the global
heap instead of the local heap for memory allocation. Unless more than
one read-write data segment is used (see \helpref{large data}{largedata}\rtfsp
below), large model programs may still have multiple instances under MS
C/C++ 7. Microsoft give the following guidelines for producing
multiple-instance large model programs:

\begin{itemize}
\item Do not use {\tt /ND} to name extra data segments unless the segment is READONLY.
\item Use the .DEF file to mark extra data segments READONLY.
\item Do not use \_\_far or FAR to mark data items.
\item Use {\tt /PACKDATA} to combine data segments.
\item Use {\tt /Gt65500 /Gx} to force all data into the default data segment.
\end{itemize}

Even with the single-instance limitation, the productivity benefit is
worth it in the majority of cases. Note that some other multi-platform
class libraries also have this restriction. (If more than one instance
really is required, create several copies of the program with different
names.)

Having chosen the large model, just use C++ `new', `delete' (and if
necessary `malloc' and `free') in the normal way. The only restrictions
now encountered are a maximum of 64 KB for a single program segment and
for a single data item, unless huge model is selected.

For Borland users, use the data threshold switch, and the following is
also recommended:

\begin{itemize}
\item Check ``Automatic Far Data Segments"
\item Check ``Put Constant Strings into Code Segment"
\end{itemize}

See also the Frequently Asked Questions document for further details
on using Borland with wxWindows.

\section{Dynamic Link Libraries}

wxWindows may be used to produce DLLs which run under Windows 3.1. Note that
this is not the same thing as having wxWindows as a DLL, which is not
currently possible. For Microsoft C++, use the makefile with the argument DLL=1 to produce
a version of the wxWindows library which may be used in a DLL application.
There is a bug in Microsoft C++ which makes the compiler complain about returned floats,
which goes away when the {\tt /Os} option is used, which is why that flag is
set in the makefile.

For making wxWindows as a Sun dynamic library, there are comments in the
UNIX makefile for the appropriate flags for AT\&T C++. Sorry, I haven't
investigated the flags needed for other compilers.

\section{Conditional compilation}

One of the purposes of wxWindows is to reduce the need for conditional
compilation in source code, which can be messy and confusing to follow.
However, sometimes it is necessary to incorporate platform-specific
features (such as metafile use under Windows 3.1). The following identifiers
may be used for this purpose, along with any user-supplied ones:

\begin{itemize}
\item {\tt wx\_x} - for code which should work under any X toolkit
\item {\tt wx\_xview} - for code which should work under XView only
\item {\tt wx\_motif} - for code which should work under Motif only
\item {\tt wx\_msw} - for code which should work under Microsoft Windows only
\end{itemize}

For example:

\begin{verbatim}
  ...
#ifdef wx_x
  (void)wxMessageBox("Sorry, metafiles not available under X.");
#endif
#ifdef wx_msw
  wxMetaFileDC dc;
  DrawIt(dc);
  wxMetaFile *mf = dc.Close();
  mf->SetClipboard();
  delete mf;
#endif
  ...
\end{verbatim}

\section{Building on-line help}

wxWindows has its own help system from version 1.30: wxHelp. It can be
used to view the wxWindows class library reference, and also to provide
on-line help for your wxWindows applications. The API, made accessible
by including {\tt wx\_help.h}, allows you to load files and display
specific sections, using DDE to communicate between the application and
wxHelp.

wxHelp files can be marked up by hand from ASCII files within wxHelp,
or may be generated from other files, as is the case with the wxWindows
documentation.

From version 1.50, it is possible to use the platform-specific help
system (e.g. WinHelp) instead of wxHelp.

See {\tt install.txt}, the wxHelp documentation (in {\tt
utils/wxhelp/docs}) and \helpref{wxHelp}{wxhelp} for further details.

\section{C++ issues}

There are cases where a C++ program will compile and run fine under one
environment, and then fail to compile using a different compiler. Some
caveats are given below, from experience with the GNU C++ compiler (GCC)
and MS C/C++ compiler version 7.

\subsection{Templates}

wxWindows does not use templates for two main reasons: one, it is a
notoriously unportable feature, and two, the author is irrationally
suspicious of them and prefers to use casts. More compilers are
now implementing templates, and so it will probably be safe to use
them soon without fear of portability problems.

\subsection{Definition of constructors}

Some compilers allows the user to omit constructor definitions where a
parent class provides a constructor with parameters. In Microsoft C++,
all constructors with parameters must be defined in the derived class,
or the compiler cannot find the required constructor.  This may mean
defining dummy constructors which call parent constructors, for example:

\begin{verbatim}
MyClass::MyClass(int x, int y):ParentClass(x, y)
{
}
\end{verbatim}

This is not a problem where the constructor has no parameters.

\subsection{Pointers to functions}\label{functionprob}

Some compilers are clever in their matching of function pointer
arguments to the declaration of the function, and will not complain in
the following case:

\begin{verbatim}
typedef void (*wxFunction) (wxObject&, wxCommandEvent&);
...
void mycallback(wxButton& button, wxCommandEvent& event);
...
wxButton button(parent, &mycallback, label, 100, 200);
\end{verbatim}

Since wxButton is derived from wxObject, the function {\it mycallback}
is a subtype of {\bf wxFunction}.  In Microsoft C++, and most compilers
with a high warning level set, the function is not an exact match, and
the compiler complains. The solution is to place a cast in front of the
function address, thus:

\begin{verbatim}
wxButton button(parent, (wxFunction)&mycallback, label, 100, 200);
\end{verbatim}

\subsection{Precompiled headers}

Some compilers, such as Borland C++ and Microsoft C++, support
precompiled headers. This can save a great deal of compiling time. The
recommended approach is to precompile {\tt ``wx.h''}, using this
precompiled header for compiling both wxWindows itself and any
wxWindows applications. For Windows compilers, two dummy source files
are provided (one for normal applications and one for creating DLLs)
to allow initial creation of the precompiled header.

However, there are several downsides to using precompiled headers. One
is that to take advantage of the facility, you often need to include
more header files than would normally be the case. This means that
changing a header file will cause more recompilations (in the case of
wxWindows, everything needs to be recompiled since everything includes
{\tt ``wx.h''}!)

A related problem is that for compilers that don't have precompiled
headers, including a lot of header files slows down compilation
considerably. For this reason, you will find (in the common
X and Windows parts of the library) conditional
compilation that under UNIX, includes a minimal set of headers;
and when using Visual C++, includes {\tt wx.h}. This should help provide
the optimal compilation for each compiler, although it is
biassed towards the precompiled headers facility available
in Microsoft C++.

\section{File handling}

When building an application which may be used under different
environments, one difficulty is coping with documents which may be
moved to different directories on other machines. Saving a file which
has pointers to full pathnames is going to be inherently unportable. One
approach is to store filenames on their own, with no directory
information.  The application searches through a number of locally
defined directories to find the file. To support this, the class {\bf
wxPathList} makes adding directories and searching for files easy, and
the global function {\bf FileNameFromPath} allows the application to
strip off the filename from the path if the filename must be stored.
This has undesirable ramifications for people who have documents of the
same name in different directories.

As regards the limitations of DOS 8+3 single-case filenames versus
unrestricted UNIX filenames, the best solution is to use DOS filenames
for your application, and also for document filenames {\it if} the user
is likely to be switching platforms regularly. Obviously this latter
choice is up to the application user to decide.  Some programs (such as
YACC and LEX) generate filenames incompatible with DOS; the best
solution here is to have your UNIX makefile rename the generated files
to something more compatible before transferring the source to DOS.
Transferring DOS files to UNIX is no problem, of course, apart from EOL
conversion for which there should be a utility available (such as
dos2unix).

See also the File Functions section of the reference manual for
descriptions of miscellaneous file handling functions.

\section{Large amounts of global data}\label{largedata}

Under Windows, it is possible that the default data segment becomes
too large (for example, a large number of small, global data items
have been declared). This may be cured by using more than one data
segment. In Microsoft C++, specify the {\tt /Gt} compiler option with
a number representing the data size threshold for putting data items
in a separate segment. For example, {\tt /Gt8}.

The tradeoff is that using more than one data segment prevents you from
having more than one instance of the program running at a time
(see \helpref{Memory Models}{memorymodels}). Large model programs with one
data segment may still have multiple instances.

A separate problem sometimes occurs when the linker complains about too
many segments. This can be cured by using the {\tt /SEG} linker switch,
for example {\tt /SEG:256}.

For optimum Borland compilation, please the Frequently Asked
Questions guide (docs/faq.txt, docs/faq.ps and via the
wxWindows WWW home page).

\chapter{Utilities 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 larger user-contributed packages,
see the directory /pub/wxwin/contrib and \helpref{Resource Guide}{resguide}.

\section{wxBuilder}\label{wxbuilder}

wxBuilder is a start at an interactive GUI builder for wxWindows
applications. It allows the developer to quickly construct a fair amount
of the skeleton of a GUI program, before filling in the details by hand.
Presently wxBuilder runs best under Windows, but it will run under
Motif as well. The XView version is pending but there are problems
with modal dialogs that need to be ironed out.

wxBuilder is so far the largest freely-available program written in
wxWindows, totalling about 16,000 lines, and so may be of interest as a
sample application of reasonable complexity. However, I don't make any
claims about the C++ style -- it was written very quickly as a spare
time project.

Please see the printed and on-line documentation for wxBuilder.

\section{wxToolBar}\label{wxtoolbar}

wxToolBar implements a simple toolbar class, to help give wxWindows
applications a more graphical and intuitive look and feel. A wxToolBar
is a canvas with bitmaps either arranged automatically in rows and
columns, or spaced explicitly by the application. Individual tools can
be toggle or non-toggle, and toggle tools may have a second bitmap to
denote the on-state. Without a second bitmap, a distinguishable on-state
is supplied by wxToolBar. To supply further feedback for the user, the
application may override a member to intercept mouse movement over the
tools, typically using this to supply an explanatory string on the
status line.

A toolbar can be made to exist in its own frame, or (for example) below
the menu bar of the main application window. Both these types are shown
in the demo toolbar application {\tt test.cc}. wxToolBar works under Motif,
XView, Windows and NT.

Please refer to the separate manual for further details.

\section{wxHelp}\label{wxhelp}

wxHelp is a stand-alone program, written using wxWindows and \helpref{hyText}{hytext},
for displaying hypertext help. It is necessary since not all target
systems (notably X in the guise of XView and Motif) supply an adequate
standard for on-line help. wxHelp is modelled on the Windows 3.1 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.

Note that an application can be programmed to use Windows Help under
Windows 3.1, 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 wxHelpInstance} entry in the
reference section for how an application controls wxHelp.

\section{hyText}\label{hytext}

This is the hypertext library used by wxHelp to show text with mixed
fonts and colour, and manipulate blocks of text. It is supplied in
library form so it can be used by other applications (it is in fact used
by another application at AIAI).

See the separate manual and class reference for hyText.

\section{wxCLIPS}\label{clips}

C++ is all very well for applications that have to be fast, deliverable
and, above all, written in C++. But what about casual programmers,
prototypers, and those who want something a little more high-level?

Naturally, wxWindows, in collaboration with NASA, can supply the
answer---wxCLIPS. CLIPS is NASA's expert system shell consisting of a
LISP-like functional language, a rule interpreter, an object system, and
the crucial characteristic of portability. It's implemented as a C
library, can be embedded in any C or C++ application with no royalty
payments, and is free within the United States, available at low
cost elsewhere.

As a language, CLIPS has several advantages over C++. It requires no
explicit memory management, since it has garbage collection; it's
interpreted, so no long compilations; and it has a rule interpreter,
useful for knowledge based system projects, or just occasional pattern
matching and searching. So it's useful for prototyping applications,
or for non-C++ programmers. From the C++ developer's point of view,
it makes a great embedded language for user-extensible applications.

wxCLIPS adds a library of GUI CLIPS functions to CLIPS; the intention is
to cover all of wxWindows functionality eventually, though presently,
only the most important functionality is covered. wxCLIPS comes as both
a library and an executable, so it can be used straightaway to develop
GUI programs, and it can also be linked into applications to provide a
built-in language. Within AIAI, wxCLIPS has proven popular amongst
students and professionals for rapid-prototyping and customization.

A program called CLIPS2C has been written to translate a subset of CLIPS
into C++, to combine the advantages of interactive development
with efficient delivery. CLIPS2C knows about the wxCLIPS extensions.

See the wxCLIPS manual and NASA's CLIPS manuals for further details.

wxCLIPS and CLIPS2C are now distributed separately, to save
space in the wxWindows distribution. They are now available
from the /pub/wxclips directory of AIAI's ftp site.

\section{PROLOGIO}\label{prologio}

Much of a programmer's time can be spent in writing and modifying code
to load and save data files. PROLOGIO is a utility that makes life
easier, if your application's data needs look something like the
following:

\begin{itemize}
\item The data are complex, possibly involving linked records and
nested lists.
\item The application is under development, so the size and contents
of each record are liable to change.
\item Backward compatibility of data files is required.
\item Ability to read and edit data file is required.
\item Speed of application development is important, and speed of
data I/O is a lesser priority.
\end{itemize}

A PROLOGIO data file is an ASCII series of `objects'. In fact, each
object is a subset of the syntax for a term in the Prolog language, and
a PROLOGIO file can be read into Prolog with a single command, but this
is irrelevant for most purposes. Because these objects consist of a list
of attribute-value pairs, parsed by a YACC/LEX grammar, attributes can
be removed from or added to an object without `breaking' the data
format. A typical application will be written to deal with missing
attribute values, supplying defaults instead, and so data I/O can be
very robust, even though the application changes substantially over the
months and years. Very old data files are likely to be useable, even
though many bells and whistles have been added to the application.

Since the file is ASCII, and readable, it is possible to edit the data
file directly if something goes wrong---a very useful fallback position.
Also, one application's data file can be easily read by another's,
encouraging the separation of a complex application into a suite of
smaller tools.

PROLOGIO supplies a number of classes to manipulate these objects and
whole databases of objects. A PROLOGIO database can be built up
in memory and then dumped to a file with a single statement, and
conversely, a data file can be loaded into memory with a single
statement, and then picked apart.

Please refer to the separate PROLOGIO manual. \helpref{wxBuilder}{wxbuilder} is
a good example of a program that makes extensive use of PROLOGIO.

\section{Tex2RTF}\label{textortf}

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.

Directed graphs may also be drawn using this library, if cycles are
removed before the nodes and arcs are passed to the algorithm.

Tree displays are used in many applications: directory browsers,
hypertext systems, class browsers, and decision trees are a few
possibilities.

See the separate manual and the directory utils/wxtree.

\section{wxGraphLayout}

The wxGraphLayout class is based on a tool called `graphplace' by Dr.
Jos T.J. van Eijndhoven of Eindhoven University of Technology. Given a
(possibly cyclic) directed graph, it does its best to lay out the nodes
in a sensible manner. There are many applications (such as diagramming)
where it is required to display a graph with no human intervention. Even
if manual repositioning is later required, this algorithm can make a good
first attempt.

See the separate manual and the directory utils/wxgraph. 

\section{wxImage}\label{wximage}

This is a collection of GIF/BMP/XBM bitmap loading and displaying
routines for X, which may be used in conjunction with the
Windows-only \helpref{DIB}{dib} library for multi-platform bitmap display.

\section{DIB}\label{dib}

A Windows-only BMP loading and displaying library (see also\rtfsp
\helpref{wxImage}{wximage} for an equivalent for the X platform).

\section{rcParser}\label{rcparser}

This libary, written by Petr Smilauer, parses Windows resource files,
bitmaps, icons and cursors. The library is used in wxBuilder, but other
applications may find uses for it. Sorry, there isn't much documentation,
but the header files and wxBuilder sources should supply a few clues.

\section{MFUTILS}\label{mfutils}

A very modest step towards reading Windows metafiles on the
any platform. The ClockWorks program, available from AIAI, demonstrates
how extremely simple metafiles may be read and displayed (in this
case, to be used as clock hands).

\section{Colours}\label{coloursampler}

A colour sampler for viewing colours and their names on each
platform.

\chapter{Bugs and future directions}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{Bugs}

These are the known bugs (the contents of bugs.txt) plus a to-do list.

\verbatiminput{bugs.txt}
%
\section{Future directions}

wxWindows lacks some GUI features, such as the group box for
logically grouping panel items; it is anticipated that this will
be addressed quite soon.

At a higher level, wxWindows does not support a
document-oriented view of the world, as do class libraries
such as Microsoft's MFC. Such an enhancement could
eventually be merged with a future OLE-2 wrapper which will
increasingly be on programmer's shopping lists.

Users are invited to contribute ideas and code for a partial
OLE-2 wrapper (preferably one that can embrace a range of
similar technologies, including OpenDoc and CORBA).

In addition to coping with the major changes to the Windows
API (such as OLE-2 and Windows 94), wxWindows will also need
to adapt to changes in, or perhaps even the replacement of,
the Motif standard in coming years.

An Apple Macintosh version of wxWindows is currently under
development, but there is no planned OS/2 version as yet.

As ever, the future of wxWindows is largely in the hands of
its users, since no one person could cope with supporting
all platforms simultaneously. So, please don't be backward
in coming forward with project ideas and code contributions!

\chapter{Troubleshooting}

This chapter tries to address common problems with compiling
and using wxWindows. To some extent it is being superceded
by the Frequently Asked Questions document which is now
distributed with wxWindows.

\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{General}

\begin{flushleft}{\it wxWindows doesn't compile.}\end{flushleft}

Most UNIX environments that have Motif or XView installed, and a C++
compiler, should be capable of compiling wxWindows. However, there can
be small differences between platforms that have not been catered for:
these might be things such as differences in the way NULL is defined,
network or timer-specific function differences, changes in typedefs in
Motif, etc. Most people have been able to resolve these problems by
small changes to the source. wxWindows uses few, if any, unportable C++
constructs, such as templates or exceptions.

Some problems are caused by an incorrect compiler installation (for example,
an incomplete GNU GCC installation) so do try compiling a small, non-wxWindows
program before concluding wxWindows is at fault.

\begin{flushleft}{\it The program exits abnormally without initializing.}\end{flushleft}

You may be declaring a pen, brush, icon, cursor or colour globally.
These objects automatically add themselves to global lists which may
not be initialized before the object constructors are called, and so
only global pointers to these objects may be declared. After or during
\rtfsp{\bf OnInit} is called, these objects may be created with impunity.

\section{Motif-specific problems}

\begin{flushleft}{\it Panel items do not size or position correctly.}\end{flushleft}

Absolute positioning in Motif doesn't mix well with constraint-based positioning,
as used by wxWindows to implement left-to-right, top-to-bottom layout.

If you know that all your widgets are going to be positioned and sized explicitly,
you should pass the style flag {\bf wxABSOLUTE\_POSITIONING} to the panel constructor,
in which case a Motif bulletin board widget will be used instead of a form widget.

Another possibility is to try setting the widget sizes first, and finally setting the panel size.

\section{Windows-specific problems}

\begin{flushleft}{\it Dialog boxes refuse to appear.}\end{flushleft}

You probably forgot to include the file wx.rc in your resource script
(see \helpref{Resources}{resources}).

\begin{flushleft}{MDI child windows don't size properly.}\end{flushleft}

For some reason, it's not possible to programmatically resize an MDI
child frame just after creation, so using {\it Fit} to size an MDI
child frame around a subwindow does not work.

Also, it does not seem to be possible (on creation at least) to hide an
MDI child frame, resize its subwindows, then show it.

If you are using {\it Fit} to size the child window, you must
put up with seeing the windows repaint themselves: the child
window will come up already visible.

However, if you know the size of the window in advance, give it an
absolute size, create it with the wxMINIMIZE window style, draw
the contents, then call {\it Iconize(FALSE)} to restore the
window. This at least avoids seeing half-painted windows whilst
things get initialized.

\begin{flushleft}{\it I get a link error.}\end{flushleft}

See sections \helpref{Memory models}{memorymodels} and \helpref{Large Data}{largedata}. Also, try invoking
the Microsoft C++ help program (Quick Help) with the given error message.

Under Turbo C++ for Windows, you are likely to get an error which says
that there is too much debugging information. Unfortunately, this is a
fault of Borland's linker, and can only be solved by omitting some
sections of your program from the debugging process, or by buying a new
linker. Here is a message from the UseNet on the subject.

\begin{verbatim}
Article 34639 of comp.lang.c++:
>From: timh@loot01.demon.co.uk (Tim Hawkins)
Newsgroups: comp.lang.c++
Subject: Re: Turbo C++ 3.0 can't debug large programs!??
Date: 8 Aug 93 12:24:46 GMT
Reply-To: Timh@loot01.demon.co.uk

In article <5e0a8B2w165w@waffle.sns.com> billj@waffle.sns.com writes:

>zargon@leland.Stanford.EDU (Daniel Sommerfield) writes:
>> >However, I compiled my own class library (wxWindows) after much
>> >flicking of switches and fiddling with precompiled headers,
>> >only to find that linking with a small example program bombed
>> >the linker with "Debugging information overflow", and advice to
>> >reduce the number of modules with debugging information.
>> >
>Try downloading tdwin.zip from the Borland BBS.  Then unzip the file and 
>follow the procedures.  Probably you will end up renaming TDWIN.ZIP to 
>(TDWIN.DLL) to WINDEBUG.DLL.
>> 

This is a common problem with BC++, I get this on almost all of my projects

Using TDWIN will not help as the problem is during linking and not during
debugging sessions. 

The reason for the difficulty is that Borland limits the amount of symbolic
debug data to 256K, for "performance" reasons. However there is a fix,

SLR systems produce a linker which is fully compatable with the Tlink linker,
which does not suffer from this problem, it is called "optilink" and claims
to remove redundant methods as a bonus. If you get past the linker stage, and
still have problems, then this is because although TDW has a bigger symbol
limit than tlink, it is often still to small.. I have switched to using
the symantec "Multiscope" debugger which is also borland C++ compatable.

The link\debug system in BC++ is IMHO only suitable for small to medium
sized projects, and even then can bottle out at a suprisingly early stage.

Borland claim they have no plans to fix this problem. 
-- 
+--------------------------------------------------------------------------+
| Tim Hawkins  - timh@loot01.demon.co.uk     Loot Ltd Londons NoticeBoard  |
+--------------------------------------------------------------------------+
\end{verbatim}

\section{XView-specific problems}

\begin{flushleft}{\it Under XView, the menu bar does not appear, and a blank area of window
appears instead.}\end{flushleft}

You may be using {\bf SetClientSize} before the menu bar has been
created.  Call it after the whole window and its subwindows have been
created.

\begin{flushleft}{\it Under XView, the following message appears:}\end{flushleft}

{\tt XView warning: SERVER\_IMAGE\_BITMAP\_FILE: Server image creation failed (Server Image package)}

The application may be looking for an icon file which does not exist or
has been referenced by a relative icon pathname. Use an absolute path, or
include the icon image in the source file using conditional compilation
(see the {\bf wxIcon} class entry).

\chapter{Tutorial}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This short tutorial takes a look at some of the supplied demonstration
programs.  The tutorial is incomplete and may be expanded in later
releases.

\section{The demo programs}

\subsection{A minimal wxWindows program}

The best way to get a feel for how to use a tool is to see a small
example.  The supplied demo `minimal' (source file {\tt minimal.cc})
shows a rudimentary wxWindows program. It has a main window with a panel
inside it, displaying a message. There is a menu bar with a {\bf File} menu
which in turn has a {\bf Quit} option, and the program has its own icon. Under
Windows 3.1, the system menu shows the usual options including Minimize,
Maximize and Close, and under X, there is a similar pull-down system
menu provided by the current window manager. The window is resizeable,
and the panel automatically resizes to fit its parent.

Look at {\tt minimal.cc}.

{\small
\verbatiminput{../samples/minimal/minimal.cc}
}

The statement {\tt \#include "wx.h"} provides the program with access to
all the wxWindows classes and functions.

The first class declaration, {\bf MyApp}, declares a new application,
overriding one member function {\bf OnInit}. This is an essential part
of writing a wxWindows program, since {\bf OnInit} is the equivalent of
{\bf main} in a normal C++ program.

The class {\bf MyFrame} declares a constructor, and a message handler
for intercepting menu commands.

The definition of the global variable {\bf myApp} looks innocuous enough
but this starts the whole application going simply by being defined.

The {\bf OnInit} MyApp member function does the initialization of
the program. It creates a main frame, sets the icon,
creates a menu bar, a panel, and a panel item.

The {\bf MyFrame} constructor may seem a little pointless, but it
fulfils the requirements of C++ syntax in defining the constructor in
terms of its parent's constructor.

The {\bf OnMenuCommand} definition intercepts menu commands for the main
frame. If the option chosen is {\bf Quit}, the application terminates by
deleting the main frame. Normally any other existing frames should be
deleted (subframes are deleted automatically); these calls are usually put
in the frame's {\bf OnClose} handler so that a system-generated {\bf
OnClose} event will enable the program to clean itself up first.
System-generated {\bf OnClose} events delete the main frame after calling
{\bf OnClose}, so this should not be done from within {\bf OnClose}.

\subsection{More advanced features: the {\it hello} demo}

The `Hello wxWindows' demo (source files, {\tt hello.cc} and {\tt hello.h})
shows off some more wxWindows features\helpignore{ (see Figures
\ref{demo-x} and \ref{demo-ms})}.  When run, two windows pop up.
One is the `main window', with two subwindows - a panel containing
various `widgets', and a text window.  The other contains a canvas,
drawing some simple shapes, and allowing the user to doodle on it by
dragging with the left mouse button.  The canvas contents can be
scaled and printed out, either to a printer supported by Windows or to
PostScript, writing to a file or invoking the printer directly. Under
Windows, the graphic may be copied to the clipboard as a metafile.

Both frames can be resized, and the subwindows will be resized
in an appropriate manner. The text subwindow can be scrolled;
on the panel, a button can be pressed for the program to prompt the user
with text with which to set the status bar. Clicking on the
list box writes a line of text into the text window.

The {\bf File} menu has options for selecting the `mapping mode' (logical
dimensions) used in drawing graphics, a zoom option, and an option for
loading a file into the text subwindow using a file selector tool.

The {\bf Timer} menu allows the user to switch a timer on and off; when on,
some text gets written to the text subwindow every five seconds.

The {\bf Cursor} menu enables the canvas cursor to be changed, and lets
the potential wxWindows programmer view the available standard cursors.

The {\bf About} option of the Help menu pops up a dialog box with some
information.

This represents a fair amount of GUI functionality for a relatively
small program. This is because wxWindows calls are high level (creating
a working text window is a single call) and because an object-oriented
approach is taken, where much default functionality is provided.

Note also the lack of explicit coordinates or sizes in the panel item
creation calls. This is the preferred approach, leaving wxWindows to lay
out the items from left to right and top to bottom, with the user
interjecting the occasional {\bf NewLine} call.  Explicit positioning is
not recommended since it is less device independent, but can be achieved
by using more parameters to the creation calls, or by using {\bf
SetSize} after an item has been created.  Coordinates and sizes default
to -1, which tells wxWindows to choose appropriate positioning and
sizing.  In this example, the windows are explicitly sized, but you may
size a frame or panel to fit around its contents by calling {\bf Fit}.

{\bf MyFrame's} {\bf OnSize} member sizes each subwindow in proportion
to the new size of the frame. {\bf MyCanvas's} {\bf OnPaint} draws a
couple of lines, a rectangle and a spline whenever the canvas requires
repainting (e.g. on creation, and when exposed). The {\bf OnEvent}
member checks for mouse dragging, and draws a line from the last point
to the current position.  Scrolling the canvas and subsequent
repainting is handled automatically by wxWindows.

Finally, two callback functions demonstrate popping up dialog boxes,
setting the status line, and inserting text into a text window.

This demo can provide a template for your own application.
Gradually modify it for your own needs, and you will rapidly be
writing portable X and Windows 3.1 programs!

\subsection{The MDI demo}

As explained in the manual (see \helpref{MDI versus SDI}{mdi}), wxWindows takes an
automated view of Microsoft Windows's MDI (Multiple Document Interface)
since it is a very platform-specific feature. The special MDI `Window'
menu, allowing the user to switch between child windows, is provided
automatically, though without any accelerators and without a choice of
position. Also, instead of deriving frames from distinct classes for MDI
versus SDI, the approach taken in Microsoft's class library, wxWindows
uses an option in the frame constructor to switch between styles. This
allows the programmer to delay the MDI/SDI decision, perhaps even
providing a command-line switch to let the user decide.

The {\bf mdi} example program shows this run-time switching. Invoked
without a command line switch, it defaults to SDI. Invoked with the
switch {\tt -mdi} it runs as an MDI program, but only under Windows 3.1.

There are a few extra considerations when programming an MDI
applications. One is the choice of menu items. An SDI program might have
a main window and several child windows, where the main window menu has
options for quitting the program and other global matters, while child
window menus have child-specific options. In MDI, the child window menu
visually replaces the main window menu when activated, and so it must
duplicate some main window menu options. One solution is to
include logic to add extra menu items depending on whether MDI or
SDI is specified, as the {\bf mdi} example does.

Also, for programs which must be both SDI and MDI (on non-Windows 3.1
platforms SDI mode is mandatory), the main window must not have
subwindows (i.e. panels, canvases or text subwindows) since the client
area may be occupied with child MDI windows under Windows 3.1.

MDI icons pose a small technical difficulty, in that for some reason it
is not possible to use the same technique of dynamically painting the
icon onto the iconized frame client area as with SDI frames.
Consequently the programmer must insert some lines into the resource
file for providing icons (see mdi.rc) as well as using the SetIcon call
in the program for non-Windows 3.1 platforms. Only one icon image for child
MDI frames may be provided.

\subsection{The IPC demo}

The demo in the {\tt directory samples/ipc} shows how processes
may easily talks to each other synchronously (i.e. when A sends a message
to B, A waits for an answer). If you start {\tt server}, then {\tt client},
a new window should appear on top of the server window, which represents
the connection between server and client. Quitting the client causes
the connection to be broken and this window to disappear.

To illustrate `hot linking', click on the server's listbox. This sends
an {\it advise} message to the client, telling it to update its own
listbox. The reverse is not true, however.

A client may request information from the server. Select the {\bf Request}
menu item from the client's {\bf File} menu. The window which pops up
is created by the client and contains a message that the server sent back.

Selecting {\bf Execute} from the client's menu makes the server pop up a window.
Normally this would execute some command that the client wishes the server to run.

The {\bf Poke} menu item sends a {\it poke} message to the server; normally
this would insert some data into the server's memory.

Interprocess communication in wxWindows uses a subset of DDE (Dynamic Data Exchange)
which is Microsoft's standard for low-level IPC under Windows. wxWindows
gives you DDE under UNIX as well as Windows, and makes it easier to program
into the bargain by using an intuitive object-oriented model of communication.


