\chapter{Introduction}\label{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.\helpignore{For more detail on the wxWindows version 1.62 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}\itemsep=0pt
\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}\itemsep=0pt
\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, plus a constraint-based layout option.
\item Print/preview and document/view architectures.
\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}\itemsep=0pt
\item No commercial support (but Internet support can be better!)
\item XView-style restrictions on parent-child relationships (though these
are being relaxed for non-XView platforms)
\item Minimal colourmap support.
\item No OLE-2 support as yet.
\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}\itemsep=0pt
\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}\itemsep=0pt
\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}
ftp.aiai.ed.ac.uk,
\end{verbatim}

log on as `anonymous', and give your user ID as password. Change
directory into /pub/packages/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 after hours.

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.

Hermann Dunkel contributed XPM support; Arthur Seaton wrote the memory
checking code; Olaf Klein and Patrick Halke wrote the ODBC classes;
Harri Pasanen and Robin Dunn wrote wxPython and contributed to the
wxExtend library.

Many thanks also to: 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, and many
others.

`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, adapted for wxWindows use by Hermann Dunkel, adds the
ability for wxWindows programs to read in XPM colour bitmaps under both
X and Windows. There's a neat little animation demo, and a large selection of
colour pixmaps.

It is available in the /pub/packages/wxwin/tools directory of the AIAI ftp
site, in wxxpm, and from 1.61 on, in the main wxWindows distribution
itself.

From wxWindows 1.61, support for using wxXPM is built into the wxBitmap
class (see the class reference). There is also a Windows-hosted tool,
xpmshow.exe, for showing and converting between XPM and BMP files.

By default, support for wxXPM is switched off. Edit {\tt wx\_setup.h} to
enable wxXPM support.

\section{CURSES port}

Harco de Hilster is working on a CURSES port of wxWindows. A beta is
available in the /pub/packages/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/packages/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/packages/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/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}\label{comparison}
\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/subwindow method was
chosen since XView required it, and because it is a useful simplifying
assumption, imposing few restrictions in practise. However, from version
1.61, wxWindows relaxes some of these restrictions for platforms that
allow it. Text windows and canvases may be placed on a panel under
Windows and Motif, and under Windows, Motif and XView wxPanel is a
subclass of wxCanvas, inheriting most of its properties including
the ability to draw to a device context. Work is underway to
simulate subwindow nesting under XView.

Note that the splitting of canvas views (as in the Open Look standard
and some other platforms) is not allowed in wxWindows. It is envisaged
that this will be eventually be introduced into 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.

Recent releases of wxWindows remove some of the limitations of
the panel/canvas separation, and now wxPanel inherits from
wxCanvas, and has its own panel device context for drawing
graphics on. XView does not directly support this model but
wxWindows uses lower-level X calls to implement the functionality.

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

An MDI toolbar is supported from release 1.61, by using the\rtfsp
{\bf wxFrame::SetToolBar} member function.

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.

From wxWindows 1.61, panel items that do not have callbacks defined for
them use their parent panel (or dialog box) to notify events, via
the {\bf OnCommand} virtual member function. This is essential when
loading dialogs and panels from resources, since callback functions
cannot be specified in a resource file. So in such cases, the programmer
must derive a new panel or dialog class in order to override this member
function and intercept events. The panel item calling the function
can be identified by giving each panel item a unique name, and using\rtfsp
{\bf wxWindow::GetName} inside the {\bf OnCommand} function.

From wxWindows 1.62, all window classes derive from wxEvtHandler, and a
window's event handler, which defaults to point to itself, can be changed
without the need for deriving a new class.
This decoupling of event handling code from the window object itself
makes it possible to override behaviour, perhaps temporarily; example
applications might be dialog editors and on-line tutorial systems
that need to intercept user input. It also gives another method of
handling panel item input, by setting an event handler object for the
panel item or panel item's parent.

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

\normalbox{Note that this event system has nothing to do with the decoupling
of windowing and event-handling classes using wxEvtHandler. However, 
both systems can allow interception of user input, albeit by different
mechanisms.}

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. From version 1.61, wxPanel receives
OnChar events, and wxTextWindow receives OnChar events under Motif and
Windows.

\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 are not implemented in wxWindows, and are not in general
desirable in user interfaces.

From wxWindows 1.62, an {\bf OnScroll} member may be overridden to allow
and application deal directly will scroll events. The default wxCanvas::OnScroll
member implements the current scrolling behaviour.

\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 popular, and
wxWindows has a simple screen painter and code generator called
wxBuilder. wxBuilder can optionally generate wxWindows resource
files (suffix .WXR) which helps to separate out detailed GUI specification
from the code.

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.

From wxWindows 1.62, there is a facility for simple constraint-based
window layout, using the {\bf wxLayoutConstraints} class. This can be
a more powerful alternative to left-to-right panel item positioning, and
is a good method for laying out subwindows without the need to right
a complex {\bf OnSize} member function.

Recent improvements to wxWindows opens the prospect of wxWindows-based
`visual' editing tools: panels and dialog boxes can be switched into user-interface edit
mode, enabling panel items to be dragged and sized, and panel mouse clicks
intercepted. Since this functionality is built in, it becomes relatively
straightforward to construct dialog editors in any language linked to
wxWindows.

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

\helponly{See the \helpref{overview of DDE}{ipcoverview} for more detailed
information.}%
\helpignore{See the Interprocess communication overview in the reference manual for more detailed
information.}

\chapter{Multi-platform development with wxWindows}\label{multiplat}
\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, win.ini or .Xdefaults-style resource read/write code is compiled.}
\twocolitem{USE\_WX\_RESOURCES}{If 1, wxWindows resource file (.WXR) code is compiled.}
\twocolitem{USE\_CONSTRAINTS}{If 1, the constaint-based window layout system 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 Windows 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{The wxWindows resource system}\label{resourceformats}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

From version 1.61, wxWindows has an optional {\it resource file} facility,
which allows separation of dialog, menu, bitmap and icon specifications
from the application code.

It is similar in principle to the Windows resource file (whose ASCII form is
suffixed .RC and whose binary form is suffixed .RES). The wxWindows resource
file is currently ASCII-only, suffixed .WXR. Note that under Windows,
the .WXR file does not {\it replace} the native Windows resource file,
it merely supplements it. There is no existing native resource format in X
(except for the defaults file, which has limited expressive power).

Using wxWindows resources for panels and dialogs has an effect on how
you deal with panel item callbacks: you can't specify a callback function in
a resource file, so how do you achieve the same effect as with programmatic
panel construction? The solution is similar to that adopted by Windows, which
is to use the {\it parent} panel or dialog to intercept user events.

From 1.61, wxWindows routes panel item events that do not have a callback
to the {\bf OnCommand} member of the panel (or dialog). So, to use
panel or dialog resources, you need to derive a new class and override the
default (empty) {\bf OnCommand} member. The first argument is a reference
to a wxWindow, and the second is a reference to a wxCommandEvent. Check the
name of the panel item that's generating an event by using the {\bf wxWindow::GetName}\rtfsp
function and a string comparison function such as {\bf wxStringEq}.
You may need to cast the reference to an appropriate specific type to perform
some operations.

To obtain a pointer to a panel item when you only have the name (for example,
when you need to set a value of a text item from outside of the {\bf OnCommand} function),
use the function {\bf wxFindWindowByName}.

\helponly{For details of functions for manipulating resource files and loading
user interface elements, see \helpref{wxWindows resource functions}{resourcefuncs}.}

\section{The format of a .WXR file}

A wxWindows resource file may look a little odd at first. It's C++
compatible, comprising mostly of static string variable declarations with
PrologIO syntax within the string.

Here's a sample .WXR file:

\begin{verbatim}
/*
 * wxWindows Resource File
 * Written by wxBuilder
 *
 */

#include "noname.ids"

static char *aiai_resource = "bitmap(name = 'aiai_resource',\
  bitmap = ['aiai', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
  bitmap = ['aiai.xpm', wxBITMAP_TYPE_XPM, 'X']).";

static char *menuBar11 = "menu(name = 'menuBar11',\
  menu = \
  [\
    ['&File', 1, '', \
      ['&Open File', 2, 'Open a file'],\
      ['&Save File', 3, 'Save a file'],\
      [],\
      ['E&xit', 4, 'Exit program']\
    ],\
    ['&Help', 5, '', \
      ['&About', 6, 'About this program']\
    ]\
  ]).";

static char *project_resource = "icon(name = 'project_resource',\
  icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
  icon = ['project_data', wxBITMAP_TYPE_XBM, 'X']).";

static char *panel3 = "dialog(name = 'panel3',\
  style = '',\
  title = 'untitled',\
  button_font = [14, 'wxSWISS', 'wxNORMAL', 'wxBOLD', 0],\
  label_font = [10, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
  x = 0, y = 37, width = 292, height = 164,\
  control = [wxButton, 'OK', '', 'button5', 23, 34, -1, -1, 'aiai_resource'],\
  control = [wxMessage, 'A Label', '', 'message7', 166, 61, -1, -1, 'aiai_resource'],\
  control = [wxText, 'Text', 'wxVERTICAL_LABEL', 'text8', 24, 110, -1, -1]).";
\end{verbatim}

As you can see, C++-style comments are allowed, and apparently include files
are supported too: but this is a special case, where the included file
is a file of defines shared by the C++ application code and resource file
to relate identifiers (such as FILE\_OPEN) to integers.

Each {\it resource object} is of standard PrologIO syntax, that is,
an object name such as {\bf dialog} or {\bf icon}, then an open
parenthesis, a list of comma-delimited attribute/value pairs, a closing
parenthesis, and a full stop. Backslashes are required to escape newlines,
for the benefit of C++ syntax. If double quotation marks are used to
delimit strings, they need to be escaped with backslash within a C++ string
(so it's easier to use single quotation marks instead).

\normalbox{{\it A note on PrologIO string syntax:} A string that begins with
an alphabetic character, and contains only alphanumeric characters,
hyphens and underscores, need not be quoted at all. Single quotes and double
quotes may be used to delimit more complex strings. In fact, single-quoted
and no-quoted strings are actually called {\it words}, but are treated
as strings for the purpose of the resource system.}

A resource file like this is typically included in the application main file,
as if it were a normal C++ file. This eliminates the need for a separate
resource file to be distributed alongside the executable. However, the
resource file can be dynamically loaded if desired (for example by a non-C++
language such as CLIPS, Prolog or Python).

Once included, the resources need to be `parsed' (interpreted), because
so far the data is just a number of static string variables. The function\rtfsp
{\bf ::wxResourceParseData} is called early on in initialization of the application
(usually in {\bf wxApp::OnInit}) with a variable as argument. This may need to be
called a number of times, one for each variable. However, more than one
resource `object' can be stored in one string variable at a time, so you can
get all your resources into one variable if you want to.

{\bf ::wxResourceParseData} parses the contents of the resource, ready for use
by functions such as {\bf ::wxResourceCreateBitmap} and {\bf wxPanel::LoadFromResource}.

If a wxWindows resource object (such as a bitmap resource) refers to a
C++ data structure, such as static XBM or XPM data, a further call ({\bf
::wxResourceRegisterBitmapData}) needs to be made on initialization to tell
wxWindows about this data. The wxWindows resource object will refer to a
string identifier, such as `project\_data' in the example file above.
This identifier will be looked up in a table to get the C++ static data
to use for the bitmap or icon.

In the C++ fragment below, the WXR resource file is included,
and appropriate resource initialization is carried out in {\bf OnInit}.
Note that at this stage, no actual wxWindows dialogs, menus, bitmaps or
icons are created; their `templates' are merely being set up for later
use.

\begin{verbatim}
/*
 * File:    noname.cc
 * Purpose: main application module, generated by wxBuilder.
 */

#include "wx.h"
#include "wx_help.h"
#include "noname.h"

// Includes the dialog, menu etc. resources
#include "noname.wxr"

// Includes XBM data
#include "project.xbm"

// Declare an instance of the application: allows the program to start
AppClass theApp;

// Called to initialize the program
wxFrame *AppClass::OnInit(void)
{
#ifdef wx_x
  wxResourceRegisterBitmapData("project_data", project_bits, project_width, project_height);
#endif
  wxResourceParseData(menuBar11);
  wxResourceParseData(aiai_resource);
  wxResourceParseData(project_resource);
  wxResourceParseData(panel3);
  ...
}
\end{verbatim}

\section{Dialog resource format}

A dialog resource object may be used for either panels or dialog boxes, and
consists of the following attributes.

\begin{twocollist}
\twocolitemruled{Attribute}{Value}
\twocolitem{name}{The name of the resource.}
\twocolitem{style}{Optional dialog box or panel window style.}
\twocolitem{title}{The title of the dialog box (unused if a panel).}.
\twocolitem{button\_font}{The font used for control buttons: a list comprising point size (integer),
family (string), font style (string), font weight (string) and underlining (0 or 1).}
\twocolitem{label\_font}{The font used for control labels: a list comprising point size (integer),
family (string), font style (string), font weight (string) and underlining (0 or 1).}
\twocolitem{x}{The x position of the dialog or panel.}
\twocolitem{y}{The y position of the dialog or panel.}
\twocolitem{width}{The width of the dialog or panel.}
\twocolitem{height}{The height of the dialog or panel.}
\end{twocollist}

Then comes zero or more attributes named `control' for each control
(panel item) on the dialog or panel. The value is a list of further
elements. In the table below, the names in the first column correspond to
the first element of the value list, and the second column details the
remaining elements of the list.

\begin{twocollist}
\twocolitemruled{Control}{Values}
\twocolitem{wxButton}{title (string), window style (string), name (string), x, y, width, height, button bitmap resource (optional string)}
\twocolitem{wxCheckBox}{title (string), window style (string), name (string), x, y, width, height, default value (optional integer, 1 or 0)}
\twocolitem{wxChoice}{title (string), window style (string), name (string), x, y, width, height, values (optional list of strings)}
\twocolitem{wxGauge}{title (string), window style (string), name (string), x, y, width, height, value (optional integer), range (optional integer)}
\twocolitem{wxGroupBox}{title (string), window style (string), name (string), x, y, width, height}
\twocolitem{wxListBox}{title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), multiple (optional string, wxSINGLE or wxMULTIPLE)}
\twocolitem{wxMessage}{title (string), window style (string), name (string), x, y, width, height, message bitmap resource (optional string)}
\twocolitem{wxMultiText}{title (string), window style (string), name (string), x, y, width, height, default value (optional string)}
\twocolitem{wxRadioBox}{title (string), window style (string), name (string), x, y, width, height, values (optional list of strings)}
\twocolitem{wxSlider}{title (string), window style (string), name (string), x, y, width, height, value (optional integer), minimum (optional integer), maximum (optional integer)}
\twocolitem{wxText}{title (string), window style (string), name (string), x, y, width, height, default value (optional string)}
\end{twocollist}

\section{Menubar resource format}

A menubar resource object consists of the following attributes.

\begin{twocollist}
\twocolitemruled{Attribute}{Value}
\twocolitem{name}{The name of the menubar resource.}
\twocolitem{menu}{A list containing all the menus, as detailed below.}
\end{twocollist}

The value of the {\bf menu} attribute is a list of menu item specifications, where each menu
item specification is itself a list comprising:

\begin{itemize}\itemsep=0pt
\item title (a string)
\item menu item identifier (a string or non-zero integer, see below)
\item help string
\item optionally, further menu item specifications if this item is a pulldown menu.
\end{itemize}

If the menu item specification is the empty list ([]), this is interpreted as a menu separator.

If further (optional) information is associated with each menu item in a future release of wxWindows,
it will be placed after the help string and before the optional pulldown menu specifications.

Note that the menu item identifier must be an integer if the resource is being
included as C++ code and then parsed on initialisation. Unfortunately,
\verb$#$define substitution is not performed inside strings, and
therefore the program cannot know the mapping. However, if the .WXR file
is being loaded dynamically, wxWindows will attempt to replace string
identifiers with \verb$#$defined integers, because it is able to parse
the included \verb$#$defines.

\section{Bitmap resource format}

A bitmap resource object consists of a name attribute, and one or more {\bf bitmap} attributes.
There can be more than one of these to allow specification of bitmaps that are optimum for the
platform and display.

\begin{itemize}\itemsep=0pt
\item Bitmap name or filename.
\item Type of bitmap; for example, wxBITMAP\_TYPE\_BMP\_RESOURCE. See class reference under {\bf wxBitmap} for
a full list).
\item Platform this bitmap is valid for; one of WINDOWS, X, MAC and ANY.
\item Number of colours (optional).
\item X resolution (optional).
\item Y resolution (optional).
\end{itemize}

\section{Icon resource format}

An icon resource object consists of a name attribute, and one or more {\bf icon} attributes.
There can be more than one of these to allow specification of icons that are optimum for the
platform and display.

\begin{itemize}\itemsep=0pt
\item Icon name or filename.
\item Type of icon; for example, wxBITMAP\_TYPE\_ICO\_RESOURCE. See class reference under {\bf wxBitmap} for
a full list).
\item Platform this bitmap is valid for; one of WINDOWS, X, MAC and ANY.
\item Number of colours (optional).
\item X resolution (optional).
\item Y resolution (optional).
\end{itemize}


\section{Resource format design issues}

The .WXR file format is a recent addition and subject to change.
The use of an ASCII resource file format may seem rather inefficient, but this
choice has a number of advantages:

\begin{itemize}\itemsep=0pt
\item Since it is C++ compatible, it can be included into an application's source code,
eliminating the problems associated with distributing a separate resource file
with the executable. However, it can also be loaded dynamically from a file, which will be required
for non-C++ programs that use wxWindows.
\item No extra binary file format and separate converter need be maintained for the wxWindows project
(although others are welcome to add the equivalent of the Windows `rc' resource
parser and a binary format).
\item It would be difficult to append a binary resource component onto an executable
in a portable way.
\item The file format is essentially the PrologIO object format, for which
a parser already exists, so parsing is easy. For those programs that use PrologIO
anyway, the size overhead of the parser is minimal.
\end{itemize}

The disadvantages of the approach include:

\begin{itemize}\itemsep=0pt
\item Parsing adds a small execution overhead to program initialization.
\item Under 16-bit Windows especially, global data is at a premium.
Using a .RC resource table for some wxWindows resource data may be a partial solution,
although .RC strings are limited to 255 characters.
\item Without a resource preprocessor, it is not possible to substitute integers
for identifiers (so menu identifiers have to be written as integers in the resource
object, in addition to providing \verb$#$defines for application code convenience).
\end{itemize}

\section{Compiling the resource system}

To enable the resource system, set {\bf USE\_WX\_RESOURCES} to 1 in wx\_setup.h.
If your wxWindows makefile supports it, set the same name in the makefile to 1.

You will also need to compile the PrologIO utility (not always the easiest
task): you will need YACC, and LEX (or FLEX). DOS versions of these are
available on the AIAI ftp site under /pub/wxwin/tools.

\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 or user interface aesthetics.

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

\section{wxToolBar}\label{wxtoolbardescr}

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 samples/toolbar/test.cc}. wxToolBar works under Motif,
XView, Windows and NT.

New in wxWindows 1.61 is an adjunct to wxToolbar called {\bf
wxButtonBar}. This is almost identical in use to wxToolBar, but is
optimized to look and behave in a more sensible manner under Windows,
with 3D buttons that depress properly. Under X, behaviour is the same as
for wxToolBar.

Please refer to the class reference 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, and the
wxWindows resource system also relies on it.

\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}\label{bugs}
\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}

These are addressed in a separate wxWindows planning document,
available from AIAI and on the wxWindows World Wide Web pages.

The plans include:

\begin{itemize}
\itemsep=0pt
\item document/view library;
\item OLE-2 wrapper;
\item Database connectivity;
\item improved wxBuilder;
\item integration with an existing networking toolkit;
\item multimedia widget (under construction);
\item better makefiles and installation procedures;
\item ports: those in progress include Mac, NeXT and OS/2.
\end{itemize}

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{Tutorial}\label{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.

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


\chapter{Programming strategies}\label{strategies}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This chapter is intended to list strategies that may be useful when
writing and debugging wxWindows programs. If you have any good tips,
please submit them for inclusion here.

\section{Strategies for reducing programming errors}

\subsection{Use ASSERT}

Although I haven't done this myself within wxWindows, it is good
practice to use ASSERT statements liberally, that check for conditions that
should or should not hold, and print out appropriate error messages.
These can be compiled out of a non-debugging version of wxWindows
and your application. Using ASSERT is an example of `defensive programming':
it can alert you to problems later on.

\subsection{Use wxString in preference to character arrays}

Using wxString can be much safer and more convenient than using char *.
Again, I haven't practised what I'm preaching, but I'm now trying to use
wxString wherever possible. You can reduce the possibility of memory
leaks substantially, and it's much more convenient to use the overloaded
operators than functions such as strcmp. wxString won't add a significant
overhead to your program; the overhead is compensated for by easier
manipulation (which means less code).

The same goes for other data types: use classes wherever possible.

\section{Strategies for portability}

\subsection{Use relative positioning or constraints}

Don't use absolute panel item positioning if you can avoid it. Different GUIs have
very differently sized panel items. Consider using the constraint system, although this
can be complex to program. If you needs are simple, the default relative positioning
behaviour may be adequate (using default position values and wxPanel::NewLine).

Alternatively, you could use alternative .wrc (wxWindows resource files) on different
platforms, with slightly different dimensions in each. Or space your panel items out
to avoid problems.

\subsection{Use wxWindows resource files}

Use .wrc (wxWindows resource files) where possible, because they can be easily changed
independently of source code. Bitmap resources can be set up to load different
kinds of bitmap depending on platform (see the section on resource files).

\section{Strategies for debugging}

\subsection{Positive thinking}

It's common to blow up the problem in one's imagination, so that it seems to threaten
weeks, months or even years of work. The problem you face may seem insurmountable:
but almost never is. Once you have been programming for some time, you will be able
to remember similar incidents that threw you into the depths of despair. But
remember, you always solved the problem, somehow!

Perseverance is often the key, even though a seemingly trivial problem
can take an apparently inordinate amount of time to solve. In the end,
you will probably wonder why you worried so much. That's not to say it
isn't painful at the time. Try not to worry -- there are many more important
things in life.

\subsection{Simplify the problem}

Reduce the code exhibiting the problem to the smallest program possible
that exhibits the problem. If it is not possible to reduce a large and
complex program to a very small program, then try to ensure your code
doesn't hide the problem (you may have attempted to minimize the problem
in some way: but now you want to expose it).

With luck, you can add a small amount of code that causes the program
to go from functioning to non-functioning state. This should give a clue
to the problem. In some cases though, such as memory leaks or wrong
deallocation, this can still give totally spurious results!

\subsection{Genetic mutation}

If we had sophisticated genetic algorithm tools that could be applied
to programming, we could use them. Until then, a common -- if rather irrational --
technique is to just make arbitrary changes to the code until something
different happens. You may have an intuition why a change will make a difference;
otherwise, just try altering the order of code, comment lines out, anything
to get over an impasse. Obviously, this is usually a last resort.

\subsection{Use a debugger}

This sounds like facetious advice, but it's surprising how often people
don't use a debugger. Often it's an overhead to install or learn how to
use a debugger, but it really is essential for anything but the most
trivial programs.

\subsection{Use tracing code}

You can use wxDebugMsg statements (or the wxDebugStreamBuf class) to
output to a debugging window such as DBWIN under Windows, or standard
error under X. If compiling in DEBUG mode, you can use TRACE statements
that will be compiled out of the final build of your application.

Using tracing statements may be more convenient than using the debugger
in some circumstances (such as when your debugger doesn't support a lot
of debugging code, or you wish to print a bunch of variables).

\subsection{Use wxObject::Dump and the wxDebugContext class}

It's good practice to implement the Dump member function for all
classes derived from wxObject. You can then make use of wxDebugContext
to dump out information on all objects in the program, if DEBUG is
defined to be more than zero. You can use wxDebugContext to check for
memory leaks and corrupt memory. See the debugging topic in the
reference manual for more information.

\subsection{Check Windows debug messages}

Under Windows, it's worth running your program with DBWIN running or
some other program that shows Windows-generated debug messages. It's
possible it'll show invalid handles being used. You may have fun seeing
what commercial programs cause these normally hidden errors! Microsoft
recommend using the debugging version of Windows, which shows up even
more problems. However, I doubt it's worth the hassle for most
applications. wxWindows is designed to minimize the possibility of such
errors, but they can still happen occasionally, slipping through unnoticed
because they are not severe enough to cause a crash.