\documentstyle[a4wide,makeidx,verbatim]{report}
\input psbox.tex

% Remove this for processing with dvi2ps instead of dvips
%\special{!/@scaleunit 1 def}

\parskip=10pt

\title{Manual for wxWindows 1.40: a portable GUI toolkit for C++}
\author{Julian Smart\\Artificial Intelligence Applications Institute\\
University of Edinburgh\\EH1 1HN}
\date{April 1993}

% Function, e.g.
% e.g. to typeset
%
% void DoIt(char *string);
%
% write:
%
% \func{void}{DoIt}{\param{char *}{string}}
%

\newcommand{\func}[3]{\hangafter=1\noindent\hangindent=10mm
{\bf #1 #2\index{#2}}(#3)}

% For function/type definition where the name is a pointer,
% e.g. to typeset
%
% typedef void (*wxFunction)(wxObject&)
%
% write:
%
% \pfunc{typedef void}{wxFunction}{param{wxObject&}}

\newcommand{\membersection}[1]{\begin{flushleft} {\Large \bf #1} \end{flushleft}}

\newcommand{\helpignore}[1]{#1}

\newcommand{\cinsert}{$<<$}
\newcommand{\cextract}{$>>$}
\newcommand{\helpref}[1]{{\bf #1}}

\newcommand{\pfunc}[3]{\hangafter=1\noindent\hangindent=10mm
{\bf #1 (*#2)\index{#2}}(#3)}

% Member: a type and a name
\newcommand{\member}[2]{{\bf #1 \it #2}}

% Parameter: a type and a name
\newcommand{\param}[2]{{\bf #1}{\it #2}}

% Class: puts in index
\newcommand{\class}[1]{#1\index{#1}}

% Void type
\newcommand{\void}{{\bf void}}

% Typeset destructor
\newcommand{\destruct}[1]{{$\sim$}#1}

% Glossary entry
\newcommand{\gloss}[1]{\item[#1]\index{#1}}

% Headings consistent with generated ones
\newcommand{\myheading}[1]{\vspace*{25pt}
\begin{flushleft}
{\LARGE \bf #1}
\end{flushleft}
\vskip 20pt
}



\makeindex
\begin{document}
\vspace*{-8mm}%
\begin{center}
{\LARGE \bf Manual for wxWindows 1.40:\\A portable GUI toolkit for C++\\
}
\vspace*{15pt}
{\large
Julian Smart\\Knowledge Based Decision Support Group\\Artificial Intelligence Applications Institute\\80 South Bridge\\University of Edinburgh\\EH1 1HN\\
\vspace*{10pt}
April 1993
}
\end{center}
\newpage
% \maketitle

\tableofcontents
\newpage
\section*{Copyright notice}

\begin{center}
Copyright (c) 1993 Artificial Intelligence Applications Institute,
The University of Edinburgh\\
\end{center}

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice, author statement and this permission notice appear in
all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR THE
UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF
DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH
THE USE OR PERFORMANCE OF THIS SOFTWARE.

\chapter{Introduction}

\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.  It was originally developed at the Artificial Intelligence
Applications Institute, University of Edinburgh, for internal use on a
medium-sized project\footnote{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 describes in detail the wxWindows version 1.40 API
(Application Programmer's Interface). There is also a smaller, tutorial
document which discusses various aspects of wxWindows use.

\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 (for instance
CommonView, XVT++), none met all of the following criteria:

\begin{enumerate}
\item low price
\item source availability
\item ability to use Open Look on the Sun instead of or as well as Motif
\item simplicity of programming
\item support for GCC (GNU C++)
\item support for interprocess communication
\end{enumerate}

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 three native APIs: XView or Motif on the
Sun (and other platforms supporting XView or Motif) and Windows 3.1
and above on the PC.  This covers a very large proportion of machines
in use today: the Sun being an extremely popular workstation, and the
PC being the most popular personal and business computer. However,
there is nothing to prevent versions of the class library being
written for the Macintosh and other environments. A Windows NT version
is currently under development.

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.

Choice of C++ compiler is currently important for wxWindows (see {\bf
Requirements}, below). On the PC, the tested compilers for wxWindows
are Microsoft C/C++ Version 7 and (to a lesser extent) Borland C++
3.1, and currently the makefiles are for MS C7 only.

On the Sun, GNU C++ (GCC) and AT\&T C++ are known to work with wxWindows.

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 than the native
APIs. Programmers may find it worthwhile to use wxWindows even if they
are developing on only one platform.

When Windows NT becomes readily available, it should require very little
work to port wxWindows to it, and then wxWindows applications should
work on a much broader range of hardware (albeit using a subset of NT's
facilities).

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

\begin{itemize}
\item Low cost (free, in fact!)
\item You get the source
\item Several example programs, reasonable documentation
\item Simple-to-use, object-oriented API
\item No more messing with arcane X window calls under XView or Motif
\item Graphics calls include splines, polylines, rounded rectangles, etc.
\item XView-style panel item layout
\item Status line facility
\item Easy, object-oriented interprocess comms (DDE subset) under UNIX and
Windows 3
\item Encapsulated PostScript generation under UNIX, normal Windows 3 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 printer and file common dialogs, with
equivalents for UNIX
\item Under Windows 3, 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
\end{itemize}

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

\begin{itemize}
\item No commercial support (I or the net might help, though)
\item Restricted to large or huge models under Windows 3
\item Limited bitmap support
\item XView-style separation of frames, panels, canvases and text
\item Not many panel items (widgets/controls) yet
\end{itemize}

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

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

\begin{figure}
%$$\psboxto(11cm;0cm){hello_x.eps}
%$$
%\special{psfile='hello_x.ps' voffset = -350 hoffset = 30 vscale = 0.55 hscale = 0.55}
%\vspace{4.0in}
\caption{Demo program running under X}\label{demo-x}

\end{figure}
\begin{figure}
%$$\psboxto(11cm;0cm){hello_w.eps}
% $$
%\special{psfile='hello_w.eps' voffset = -400 hoffset = 10 vscale = 0.9 hscale = 0.9}
%\vspace{4.3in}
\caption{Demo program running under Windows 3}\label{demo-ms}
\end{figure}
\end{comment}

\section{wxWindows requirements}

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

(a) PC:

\begin{enumerate}
\item a 386SX or higher PC running Windows 3.1
\item Microsoft C/C++ version 7 (including the SDK) or Borland C++
version 3.1 (other compilers may work)
\end{enumerate}

(b) UNIX:

\begin{enumerate}
\item GNU C++ version 2.1 or later, or compatible compiler (such as
AT\&T C++)
\item a Sun or other workstation supporting GNU C++ and either XView 3.1
or Motif 1.1
\end{enumerate}

Note that these are the only tested tools; others may work. wxWindows
takes up between about two and five megabytes on both platforms,
depending on whether wxWindows is being recompiled or whether the
library file and header files are sufficient.

\section{Availability and location of wxWindows}

wxWindows is currently available from the Artificial Intelligence
Applications Institute by anonymous FTP. FTP to skye.aiai.ed.ac.uk, log
on as `anonymous', and give your user ID as password. Change directory
into pub/wxwin, change transmission method to binary, and get
wxwin130.tar.Z (UNIX) and/or wxwin130.zip (PC). Both archives contain the source
code for both platforms, but only the executable demos for the specific
platform (UNIX and Windows respectively).

wxWindows 1.40 is expected to be uploaded to the CICA Windows 3 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 x/a/a103.

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 jacs@aiai.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 online 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
finished off wxWindows at weekends.

The UseNet has been an essential prop when coming up against tricky
XView and Windows problems, so thanks to those who answered my queries, in particular
Kari, Jamshid Afshar, Josep Fortiana, Ian Perrigo, Neil Smith and Robin Corbet.

I also acknowledge the author of xfig, the excellent UNIX drawing tool, from
the source of which I have pinched some spline drawing code and a few
cursor definitions. His copyright is included below.

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.

\chapter{Overview and comparison with other GUI models}

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 where child
windows may be nested to any depth.  The frame method was chosen since
XView required it, and because it is a useful simplifying assumption,
imposing few restrictions in practise. Note that the splitting of views
beloved of the Open Look standard is not allowed in wxWindows.

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

In Xlib and Windows 3.1, canvases need to be painted using a handle
to a `device context'. The purpose of this is to enable more than one
device context to be used for painting a given window, and in Windows 3
to enable devices to include printers and other forms of display. 
wxWindows also has the notion of a device context, but all drawing commands
may also be directly issued to a canvas for convenience.

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 allow the selection of different
predefined `drawing tools' with certain characteristics (line
thickness, colour, fill style etc.). In X there are a limited range of
fonts, while in Windows 3 an infinite selection of sizes is available
thanks to the scaleable TrueType font system. Under XView, wxWindows
chooses the closest matching font.

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

\subsection{MDI vs. SDI}\label{mdi}

In Windows 3, 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.

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

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

\section{Dialog boxes}\label{dialogs}

A {\it dialog box} is like a panel, with an implicit frame surrounding
it. A dialog box may be {\it modal} (no other window in this application
is active and the calling program flow is suspended) or {\it modeless}
(any window may be interacted with and control returns immediately to
the program). With dialog boxes, creation of separate frames and panels
is not necessary, and under Windows 3, 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, modal dialogs have to be emulated using
modeless dialogs and a message loop. This is because Windows 3 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 mainly used in menu bars, but could also be used for popup
menus on panels (not yet implemented).  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 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,
but not XView, placing and ampersand before a letter in a menu name causes
it to be underscored and interpreted as a kind of hotkey. 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 when a menu item is
selected, the parent frame is notified using the {\bf OnMenuCommand}
member.

\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, events are {\it messages}
which are handled by a window procedure, or ignored.

In wxWindows, 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). These events are
handled by the application by deriving new window classes and
overriding the event-handling member functions.

Panel item notification has to be handled rather differently. In
Windows 3, 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 an 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.

\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 below for more information on repainting and scrolling.

\section{Scrolling}

Scrolling can be a tricky subject for a novice GUI programmer to tackle.
The Windows 3 API ensures that the suffering is as acute as possible
by requiring the application to program the scrollbar behaviour and to
check the scrollbar positions on repainting.  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 the horizontal direction is scrolled in
terms of pixels, not character widths, and so wxWindows can be left to
scroll the image smoothly, without having to clear before repainting.
This kind of control is avilable by using {\bf
wxCanvas::EnableScrolling}.

Scrolling panels have yet to be implemented in wxWindows.

\section{Printing}

Printing in Windows 3 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 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 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
screens of all types, to X windows, and to hundreds of different
printers.

\section{Programmatic versus interactive GUI building}

Interactive tools for rapidly building GUIs are all the rage, and
wxWindows does not at this point support this. Loading Windows 3 dialog
boxes from resource files will be possible in future in wxWindows, so
that dialogs may be constructed interactively. However, this will not
carry through to other platforms, so a more general solution is
required. One possibility is to translate Windows 3 resource scripts or
DevGuide descriptions into wxWindows code, or into a form that wxWindows
could load.  Using YACC and LEX such a project could be quite
straightforward, although there will not always be a mapping between the
dialog builder and wxWindows constructs.

Another consideration is that 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 such as the Microsoft dialog editor
are useless.

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

\section{Dimensions}

The graphics origin is always the top left hand corner of a window.
Dimensions are a problem in a multi-platform application, since display
and character widths will change from machine to machine, even more so
than for different PC display boards. At the moment wxWindows uses
pixels; Windows 3 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. Future
versions of wxWindows will support a change of graphics origin.

\section{Colour}

Under XView and Motif, the default palette is used for canvases, giving a limited
range of colours. More colours show up under Windows 3. Future versions
of wxWindows should improve upon colour and palette handling.

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.

\section{Online help}

Most modern GUI applications have on-line hypertext help. In Windows
3, 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 browseable
help.

From version 1.30, wxWindows comes with wxHelp, a hypertext help system
which may be invoked from 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{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, the
most fundamental 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 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.

\subsection{Principles of DDE}

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

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

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

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

To create a working server, the programmer must:

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

To create a working client, the programmer must:

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

\subsection{Data transfer}

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

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

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

\subsection{Examples}

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

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

\subsection{Remote Procedure Call}

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

PROLOGIO is expected to be available in the first quarter of 1993.

\chapter{Multi-platform development with wxWindows}

\section{Include files and libraries}

Under UNIX, use the library libwx.a.  Under DOS, use the library wx.lib.

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. The header files are as follows.

\begin{itemize}
\item common.h - important definitions and includes
\item wx.h - includes all wxWindows headers
\item wx\_canvs.h - drawing on canvases
\item wx\_dc.h - drawing on canvases and printers
\item wx\_dialg.h - user-defined and standard dialogs
\item wx\_event.h - used in conjunction with windows and panel items
\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\_item.h - panel items
\item wx\_list.h - linked list implementation, heavily used by wxWindows
\item wx\_main.h - application initialization
\item wx\_obj.h - base class for wxWindows classes
\item wx\_panel.h - panels
\item wx\_privt.h - some private wxWindows declarations
\item wx\_text.h - text subwindows
\item wx\_timer.h - timer object
\item wx\_utils.h - various utilities
\item wx\_win.h - abstract base class for frames, subwindows and items
\end{itemize}

Unfortunately, including specific header files for purposes of compiling
speed can be a problem on the PC if {\bf wx.h} is precompiled, since then
{\bf wx.h} must be mentioned in each source (see below). A tradeoff is
probably necessary between speed of compiling under UNIX versus on the
PC.

\section{Makefiles}

At the moment there is no attempt to make UNIX makefiles and
nmake makefiles compatible, i.e. one makefile is required for
each environment. If anyone knows how to avoid this duplication,
I would be interested!

Sample makefiles are included with the library and demos, but not for
Borland C++, so if anyone can send me some Borland makefiles I will
make them available with a future release.

\subsection{DOS makefiles}

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 {\bf xview} and {\bf motif}, which
build versions of a library or binary appropriate to desired GUI
toolkit. To change from one toolkit to another you must remember to
recompile anything using wxWindows, for example by using the {\bf
wxclean} target. Debugging information is usually included; you may
add DEBUG= on the command line to compile without it, or use the UNIX
{\bf strip} command to remove debugging information (faster and more
thorough).

\section{Windows-specific files}

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

\subsection{Resource file}\label{resources}

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

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

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

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

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

\subsection{Module definition file}


A module definition file (extension DEF) looks like the following:

\begin{verbatim}
; hello.def
;

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{memory-models}

Under UNIX, this 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 section \ref{large-data} 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.

\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 MSC 7, 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 MSC 7 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 identifers
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. See {\tt install.txt} and
the wxHelp documentation (in {\tt utils/wxhelp/docs}) 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 (MSC 7).

\subsection{Templates}

I have not investigated using the cut-down template facility in MSC 7;
probably it is best to avoid using templates for maximum portability.

\subsection{Definition of constructors}

GCC allows the user to omit constructor definitions where a parent class
provides a constructor with parameters. In MSC 7, 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{function-prob}

GCC is clever in its 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&, wxEvent&);
...
void mycallback(wxButton& button, wxEvent& 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 MSC 7, however, 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}

MSC 7 supports precompiled headers, which can save a great deal of
compiling time. However, if the header file to be compiled only appears
in the DOS environment (for example {\tt windows.h}), there is a problem. The
filename must appear in any source file including this header file, not
just in another header file; therefore any application using {\tt wx.h} and
requiring precompilation of {\tt windows.h} must include a reference to
{\tt windows.h} in all the source files.  It is not possible to
conditionally include this reference due to another MSC 7 restriction,
so the only solution seems to be to have a dummy {\tt windows.h} in the
UNIX environment.

If {\tt wx.h} is itself precompiled, this problem should go away
assuming all source files include {\tt wx.h}. Precompilation is useful
only for stable code and so precompiling the wxWindows headers is not
practical if wxWindows itself is being altered.

\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 section \ref{file-functions} for descriptions of miscellaneous
file handling functions.

\section{Large amounts of global data}\label{large-data}

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
MSC7, 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
above). 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}.


\chapter{Bugs and future developments for wxWindows}

\section{Bugs}

These are the known bugs:

\begin{enumerate}
\item Using {\bf SetClientSize}\/ before setting the menu bar on a frame
does not cause a menu bar to appear under X. Use {\bf SetClientSize} after changes
to the window which might affect its size.

\item Modal dialogs under XView do not treat some panel items correctly.
This XView problem is partially corrected with the list item scrollbar
fix supplied with wxWindows, but choice items (and probably other items)
still don't work properly.

\item MDI support is hampered by the inability to paint icons
dynamically onto the iconized window client area, thus limiting icons to
one image for all child windows.

\item Mapping mode support is patchy.

\item PostScript output control could be improved. Mapping mode ignored
by PostScript driver.

\item Some text window behaviour is not implemented in Windows (e.g.
character input).

\item Support for panel items such as radio buttons is absent.

\item On creation of a new frame, XView often appears to send too many repaint
events to subwindows.  I can't find a way around this, any suggestions
appreciated.

\end{enumerate}

\section{Future developments}

The following enhancements are under consideration, some of which have
been discussed earlier.

\begin{enumerate}
\item Ports to other windowing systems, such as Motif and NT. These are both
under way.
\item Better support for bitmap operations and image file loading.
\item a wxToolBar class.
\item interception of all wxWindows system events, for `meta-applications' such
as a special-needs interface.
\item More panel item types.
\item Changeable panel item fonts.
\item An enhanced text window for the Windows environment
\item Use of a tool such as DevGuide to generate wxWindows code.
\end{enumerate}

\section{Troubleshooting}

{\it Under Windows, dialog boxes refuse to appear.}

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

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

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

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

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

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

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

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

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

See sections \ref{memory-models} and \ref{large-data}. Also, try invoking
the MSC7 help compiler with the given error message.

\input classes.tex

\newpage
\myheading{Glossary}
\addcontentsline{toc}{chapter}{Glossary}

\begin{description}

\gloss{API}

Application Programmer's Interface - a set of calls and classes defining
how a library (in this case, wxWindows) can be used.

\gloss{Canvas}

A canvas in XView and wxWindows is a subwindow on which graphics (but
not panel items) can be drawn. It may be scrollable. A canvas has a
{\it device context}\/ associated with it.

\gloss{DDE}

Dynamic Data Exchange - Microsoft's interprocess communication protocol.
wxWindows provides an abstraction of DDE under both Windows and UNIX.

\gloss{Device context}

A device context is an abstraction away from devices such as windows,
printers and files. Code that draws to a device context is generic since
that device context could be associated with a number of different real
device. A canvas has a device context, although duplicate graphics calls
are provided for the canvas, so the beginner doesn't have to think in
terms of device contexts when starting out. wxWindows supports device
contexts for canvas, Windows printer, and Encapsulated PostScript files on UNIX.

\gloss{Dialog box}

In wxWindows a dialog box is a convenient way of popping up a window
with panel items, without having to explicitly create a frame and a
panel. A dialog box may be modal or modeless. A modal dialog does not
return control back to the calling program until the user has dismissed
it, and all other windows in the application are disabled until the
dialog is dismissed.  A modeless dialog is just like a normal window in
that the user can access other windows while the dialog is displayed.

\gloss{Frame}

Under XView (and wxWindows), a visible window usually consists of a
frame which contains zero or more subwindows, such as text subwindow,
canvas, and panel. Under Windows 3, windows can be nested arbitrarily,
but this is not currently supported in wxWindows.

\gloss{GNU C++}

A free, solid C++ compiler which may be used to compile the UNIX side of
wxWindows applications.

\gloss{GUI}

Graphical User Interface, such as Windows 3 or X.

\gloss{Menu bar}

A menu bar is a series of labelled menus, usually placed near the top
of a window. It is popular in Windows 3 and Motif applications, and as
such is a supported feature, but wxWindows has to `simulate' the menu
bar under XView by using a panel and several menu buttons.

\gloss{Metafile}

Microsoft Windows-specific object which may contain a restricted set of
GDI primitives. It is device independent, since it may be scaled without
losing precision, unlike a bitmap. A metafile may exist in a file or in
memory. wxWindows implements enough metafile functionality to use it to
pass graphics to other applications via the clipboard.

\gloss{Open Look}

A specification for a GUI `look and feel', initiated by Sun
Microsystems. XView is one toolkit for writing Open Look applications
under X, and wxWindows sits on top of XView.

\gloss{Panel}

A panel in XView and wxWindows terminology is a subwindow on which a
limited range of panel items (widgets or controls for user input) can be
placed. wxWindows allows panel items to be placed explicitly, or laid
out from left to right, top to bottom, which is a more platform
independent method since spacing is calculated automatically at run time.
Panel items cannot be placed on a canvas, which is specifically for
drawing graphics.

\gloss{RPC}

Remote Procedure Call - a method of interprocess communication akin to
procedure call, where the client process makes a call to a server, which
sends back a result. The AIAI-supplied PROLOGIO library supports a
simple RPC protocol based on DDE (but working under both UNIX and
Windows).

\gloss{Status line}

A status line is often found at the base of a window, to keep the user
informed (for instance, giving a line of description to menu items, as in the
{\bf hello} demo). XView has a status line (or footer) capability, but
wxWindows implements the feature explicitly under Windows 3 and Motif.

\gloss{Text subwindow}

In XView and Motif, a text subwindow is supplied for displaying and
retrieving text from a window. It has a rich set of features, only a
small subset of which is currently catered for by wxWindows.

\gloss{XView}

An X toolkit supplied by Sun Microsystems, initially just for porting
SunView applications to X, but which has become a popular toolkit in its
own right due to its simplicity of use. XView implements Sun's Open Look
`look and feel' for X, but is not the only toolkit to do so.

\end{description}

\addcontentsline{toc}{chapter}{Index}
\printindex
\end{document}
