\documentstyle[a4,texhelp,11pt,makeidx]{report}

\title{wx/FrameWork: the next generation of wxWindows\\Draft 1.0}
\author{Julian Smart and others}
\date{January 1995}
\parskip 12pt
\parindent 0pt
\begin{document}
\maketitle
\tableofcontents

\chapter{Introduction}

wxWindows is a free multi-platform GUI toolkit being used
internationally for developing portable C++ software. It currently
compiles on Windows 3.1, Windows NT, and on most variants of UNIX
supporting XView or Motif 1.2. A Mac port is in development.

It is felt that wxWindows can, and should, be developed into a
general-purpose portable programming environment that supports all major
platforms, and is capable of sophisticated user interface, operating
system and networking capabilities. Not only would this development
protect the investments of existing wxWindows users, but could make
wxWindows the best general-purpose multi-platform development solution
available, either free or commercially. This should be a valuable
service to software developers both inside and outside the Internet
community, approaching the significance of the free compiler GNU GCC.

This document attempts to plan the technical aspects of this future,
determining what platforms and technologies should be supported, and
what components must be added. The changes proposed are all incremental
and backward compatible, and do not require a rewrite of wxWindows or
applications that currently use wxWindows.

Please feel free to comment and contribute.

Throughout, the working name {\it wx/FrameWork} will be used for this `future'
wxWindows, and the name {\it wxWindows} will be used for the existing
software.

\chapter{Platforms}

As many popular platforms as possible should be supported. These must be
at least the following:

\begin{enumerate}
\item MS Windows in all forms (3.1, 95, NT, WIN32s, PenWindows).
\item Motif 1.2 and CDE (UNIX, VMS).
\item XView.
\item Mac.
\item OS/2 Presentation Manager.
\end{enumerate}

It would be highly desirable to support the following platforms:

\begin{enumerate}
\item NeXTSTEP/OpenStep.
\item CURSES (text-mode UNIX or DOS).
\end{enumerate}

Platforms which would be nice to support, but are by no means essential, include:

\begin{enumerate}
\item Xt (X toolkit) with Athena and other free widgets.
\item Graphic-mode DOS.
\item Acorn RiscOS.
\end{enumerate}

\chapter{Advanced GUI facilities}

\section{Widgets}

wxWindows has a limited range of widgets, which should be augmented by
such elements as:

\begin{itemize}
\item Combobox widget.
\item Individual radiobutton widget.
\item Spinbox widget.
\item Divider and shadow widgets.
\item Combined bitmap/text label widget.
\item Checkbox/listbox widget.
\item Virtual listbox (for very large lists).
\item Hierarchy widget.
\item Canvas splitter widget.
\item Tabbed dialog or folder widget.
\item Tear-off toolbars with tooltips.
\item Tear-off menus (if appropriate to platform).
\item Table or spreadsheet widget.
\item Advanced text editor widget (perhaps combine with hypertext
widget).
\item Advanced status line.
\end{itemize}

\section{Multimedia}

wx/FrameWork must support multimedia programming since the presentation
of information in a rich way will continue to become ever more important
in computing.

We would therefore like to see:

\begin{itemize}
\item wxImage class to allow file loading, saving and image-processing
operations for a variety of file formats.
\item RTF or other markup/hypertext widget (perhaps different on
different platforms).
\item An API for playing, manipulating and recording sounds.
\item An API for playing back video.
\item Sufficient GDI support for animation (or a special-purpose API).
\end{itemize}

\section{General capabilities}

Below is a list of some important GUI considerations that should be
applied to wxWindows.

\begin{itemize}
\item There should be as few arbitrary restrictions as possible on how
interface elements are used and combined.
\item Dialogs, panels and canvases should all be capable of being drawn
into, and event handling should be equally flexible for all subwindows
and widgets.
\item The ability to produce custom widgets should be provided for,
although the preferred solution is normally to use a freely-available
widget already written for each platform.
\item Mapping modes (coordinate space) should be improved for all
windows.
\item Printing, and previewing, should be well supported in
wx/FrameWork. It should be possible to generate default print
previewing facilities from wxBuilder.
\item GDI calls should be expanded to cover more drawing primitives such
as arcs and complex clipping areas.
\item Scrollbar manipulation should be improved so programmers can
write efficient code.
\item Drag and drop, clipboard support on all platforms.
\item Complete set of common dialogs (printer, font, colour etc.).
\item Internationalisation support.
\item A strategy for implementing undo/redo operations (in high-level class library).
\item Interface to 3D graphics API such as OpenGL. This is not necessarily a
wrapper around all 3D API functions, but just an ability to use the 3D
functionality within a wx/FrameWork window.
\end{itemize}

\chapter{A higher-level class library}

wxWindows has no concepts of document, view or persistant storage, which
higher-level class libraries (such as MFC) support. This should be
written as a (largely) platform-independent adjunct to the wx/FrameWork GUI core,
and will help wxBuilder support higher-level code generation facilities.

Also, wx/FrameWork requires better (optional) data structure classes to reduce
the need for third-party libraries.

\section{Document-centric classes}

These classes support very high-level and generic modelling of the
central architecture of most applications. They also represent a bridge
towards a degree of future OLE/OpenDoc compatibility: much of it can be
implemented in terms of non-OLE functionality (e.g. native drop and drop
capabilities), but some OLE (or OpenDoc) support can be implemented
later on as resources permit in the wx/FrameWork project. This requires
careful consideration of OLE-2 and OpenDoc requirements in the design,
to avoid later incompatibilities.

The goal is to give wx/FrameWork developers the advantages of
document-centric programming as soon as possible, and some OLE-2 or OpenDoc
support later without the need to for substantial (or any) rewriting of
application code. Obviously, OLE-2/OpenDoc support can only exist on
platforms that have this capability (e.g. Windows, Mac).

See Appendix A for more discussion on OLE-2 and OpenDoc.

\subsection{wxDocument}

Represents a document, with zero or more views onto it.

\subsection{wxDocTemplate}

Represents information generic to all documents of this type.

\subsection{wxView}

Represents a view onto a document. There is a one-to-one correspondence
between the window implementing the view, and the wxView object,
although there may be more than one wxView per wxDocument.

Should this inherit from wxCanvas, wxPanel or neither?

\subsection{wxPreviewView}

Represents a print preview.

\subsection{wxDocItem}

Represents an item within a document.

\subsection{wxDataItem}

Represents any kind of data that is being exchanged between applications or
within an application, such as clipboard data, or drag and drop data.

\subsection{wxDropSource}

Represents a drop source.

\subsection{wxDropTarget}

Represents a drop target.

\subsection{wxArchive}

Implements persistant storage. We also need some macros to assist with
dynamic object creation (how?)

\section{Error-handling classes, macros and functions}

\subsection{Redefining new}

We can redefine operator {\it new} in the base wxObject class:

\begin{verbatim}
void *operator new(size_t nSize, const char *filename, int nLine);
\end{verbatim}

and use this in wx\_setup.h:

\begin{verbatim}
#ifdef DEBUG
#define new DEBUGGING_NEW
#endif
\end{verbatim}

defining a macro for DEBUGGING\_NEW that calls this version of the operator.
DEBUGGING\_NEW can be defined as:

\begin{verbatim}
#define DEBUGGING_NEW(thing) new thing(__FILE__, __LINE__)
\end{verbatim}

(or similar syntax).

In turn, the definition for {\it new} cooperates with {\it delete} to detect
memory leaks and multiple pointer deletion.

This debugging code will then be used for all derived classes of wxObject.

\section{Data structure classes}

\subsection{wxCollection}

\subsection{wxMatrix}

\section{Geometry management classes}

This section will describe classes for automatically managing windows
according to a range of constraints. This declarative style will often
make it unnecessary to write specific code in an {\bf OnSize} handler,
and provide a clear mapping from wxBuilder features to generated code.

The aim is to fulfill the majority of needs with these classes, but for
very complex behaviour, code may need to be written.

\chapter{Interoperation}

The world of networking and component software is diverse and changing rapidly, and
so varying levels of support for interoperation should be supported by
wx/FrameWork.

It is proposed that three levels of support are provided:

\begin{enumerate}
\item {\bf Dynamic Data Exchange:} for lightweight networking and
single-platform data exchange. This is relatively easy to program, and
suitable for small applications. This already exists in wxWindows, and
will be better supported and documented in wx/FrameWork.
\item {\bf Component Software:} a wrapper for OLE or OpenDoc, probably limited
to specific platforms.
\item {\bf Networking:} a heavy-weight networking toolkit will be provided.
This overlaps with (2), in that some areas of this toolkit will allow
software components to be built, but it comes from a different tradition.
\end{enumerate}

It is possible that two or all of these could be merged if a suitably
generic framework could be found. CORBA should come into this group
somewhere, but I'm not sure at which level, 2 or 3.

\section{Dynamic Data Exchange: a lightweight mechanism}

The existing wxWindows IPC mechanism, consisting of the classes wxClient,
wxServer and wxConnection, should be retained for backward compatibility,
and as a suitable method for simple IPC tasks. It works under Windows,
UNIX networks, and (using WinSock) across UNIX and Windows networks.

\section{Component software}

OLE-2 will probably be the standard component technology for Windows
and Mac, but targetting OpenDoc may be more fruitful since it is
advertised as a cross-platform technology that is OLE-2 compatible. It
claims to simplify OLE-2 programming, which cannot be bad.

\section{Networking}

Possibly using ACE, especially STREAMS. Edward Zimmermann to expand
please! Where does this fit it with OpenDoc, OLE-2 and CORBA, if
anywhere?

\section{Email}

wx/FrameWork must be capable of being mail-aware.

\section{Structured Data storage}

In wxWindows we already have a general-purpose structured file format
with a convenient API, in the form of PrologIO. However, we need to take
on board the realities of efficient, binary storage schemes as used in
OLE-2, for example. Our higher-level class library will use this
facility, as will the component technology. A `standard' for data
storage enhances interoperation by facilitating object embedding and
examination of an application's data.

\section{Database connectivity}

A generic database access API would be very attractive, perhaps a wrapper
for Microsoft's ODBC.

\chapter{Tools}

\section{wxBuilder}

wxBuilder should be able to capitalize on the high-level class library,
and take on board some of the developments in competing tools.

Here are some of the features that should be added to wxBuilder:

\begin{itemize}
\item Ability to generate high-level document/view classes, and print
previewer.
\item Ability to generate multiple files (e.g. one per class).
\item General interface improvements.
\end{itemize}

\subsection{CASE}

It is possible that the AIAI meta-CASE tool Hardy can provide an OOAD
adjunct to wxBuilder, perhaps generating a skeleton wxBuilder project file for
the designer to expand. This could make a good student project.

\section{Tex2RTF}

Improve Tex2RTF to allow better formatting, and ability to output to
all native help systems (new Windows 95 help system, OS/2 help system,
NeXTSTEP help system etc.). Possibly include tools to convert from other
formats, e.g. MS Word.

\section{wx/FrameWork installation}

A generic installation and configuration system for wx/FrameWork,
possibly with a multimedia guided tour, should be written, together with
an improved shell script to cater for situations where an executable
installation program does not exist for the target platform.

\section{Setup toolkit}

A generic setup toolkit for wx/FrameWork applications should be
provided, suitable for installation from network or CD-ROM. Smaller,
optimized installation toolkits can be provided on specific platforms
for floppy disk installation.

\section{Testing and debugging}

Support should be provided within wx/FrameWork or in a separate library
for memory checking.

There should be the ability to write programs (in C++ and/or an
embedded, interpreted language such as CLIPS) to test wx/FrameWork
applications, programmatically emulating user interaction. Partial
support for this already exists within the event system.

\section{wxHelp}

For platforms that do not have a native help utility, wxHelp should be
optimized for best performance and display on that platform, for example using an
HTML widget under Motif. If an optimized hypertext widget with a standard API is
created, this can be used.

\chapter{Documentation}

The existing documentation should be improved:

\begin{itemize}
\item Give examples in reference, adopt a standard for describing parameters.
\item Better indexing including an up-to-date (possibly clickable) class
hierarchy.
\item Provide a tutorial (or series of tutorials).
\item Provide an implementation guide.
\end{itemize}

\chapter{Other languages}

Although it is not a major goal, wx/FrameWork should try to address
itself to languages besides C++. The more people using wx/FrameWork, in
whatever form, the more robust the software will become, and the more
support it will have. In addition, it can be useful to have embedded
languages within conventional C++ programs, to allow end-users to build
portable GUI applications.

The wxCLIPS library contains a substantial proportion of wxWindows
functionality in CLIPS and C form: the C functions could be extracted
into a separate module to help support other languages, such as Python
and Prolog (both in development).

Users are encouraged to investigate bindings with languages such as Ada
and Pascal.

\appendix
\chapter{Application architectures: OLE-2 and OpenDoc}

This appendix summarizes the common goals of OLE-2 and OpenDoc, and
which parts will be relevant to wx/FrameWork.

These technologies are important not only for their technical strengths
but for the force they represent in the application market.
wx/FrameWork must take them on board if it is to remain relevant.

\section{What are they?}

Both Microsoft's OLE-2, and Apple, Novell and IBM's OpenDoc, consist of
a raft of `technologies' to support an object-oriented, component view
of applications. They provide, in slightly different ways, {\it
standards} which application programmers should follow in order to
maintain maximum interoperation and consistency between different
applications. In fact, under these schemes, an application changes its
nature and becomes a vehicle for whatever bits of component software the
user chooses to use. Vendors will sell `plug and play' components that
do not run in isolation, but can be used in conjunction with a
`container application' or `shell' (the user may only need one of these).

Areas covered in OLE-2 and OpenDoc include:

\begin{itemize}
\item Uniform data transfer. Enables data transfer of different types,
such as clipboard or drag and drop operations, to be handled in a
uniform and consistent fashion.
\item Compound documents. A compound document contains one or more
embedded or linked pieces of information that is associated with a piece of code
for editing or manipulating it.
\item Compound user interfaces. Both OLE-2 and OpenDoc allow for
constructing user interfaces from parts, essentially a special case of
compound document.
\item Structured storage. A standard for compound file layout is
imposed, making it easy to examine the contents of any application's files, and
providing enhanced features like undo and incremental saves. A uniform
notion of storage is also central to encapsulating an object's data,
allowing it to be manipulated by programs that know nothing about the
detail of the data format, and shunted around in compound document
operations.

In OpenDoc, the compound document architecture is called Bento.
\end{itemize}

\section{Limitations of OLE-2 and OpenDoc}

The basic assumption is that any part (component) has a
direct-manipulation interface that can handle all the part-specific
functionality required, independently of (or cooperating with) the
shell's user interface. This comes out of the requirement for any part
to be used in any container application. Presumably OpenDoc's
`scripting' mechanism and OLE-2's automation facilities will allow an
application to control non-user interface aspects of the component
without needing to delve into the component's data. However, it is
unclear whether this can handle all required cases, such as a container
application responding to callbacks from a part (it looks as though OpenDoc scripts can do
this, but I can find no equivalent in OLE Automation). All this takes a bit of
getting used to and one does wonder if all possible components are going
to fit the OLE or OpenDoc models, or whether a better component-software
model is going to be required. Certainly there needs to be more
attention given to standards that deal with functionality in addition
to visual appearance. However, it will no doubt be many years before a
remotely comprehensive set of `standard' APIs is available, if ever.

Perhaps this should be an aim for wx/FrameWork? (Semi-seriously).

\section{More on OpenDoc}

OpenDoc claims these additional advantages:

\begin{itemize}
\item Scriptability. Programmability of components; probably equivalent
to OLE-2 OLE Automation.
\item Collaboration support. Basically a versioning scheme.
\item Cross-platform support. The aim is to port OpenDoc to all major
platforms, using CORBA for UNIX implementations. Microsoft will support Apple and Windows, but relies on third
party companies for other platforms.
\item OLE-2 compatibility.
\item Multiple parts can be active simultaneously, unlike with OLE-2
where all objects but the currently active one are static snapshots.
\item Automatic inside-out activation for nested parts (you don't have
to unwrap one part to get to another inside it).
\item All OpenDoc parts are DLLs under Windows, meaning greater
efficiency (.EXEs require costly marshalling across process boundaries).
\item OpenDoc's developers will encourage the agreement on and
publication of standard APIs that extend standard OpenDoc part handler
APIs, allowing standards for e.g. spelling checkers, text search, etc.
\end{itemize}

OpenDoc seems particularly suited to wx/FrameWork because of its
cross-platform nature, and its OLE-2 compatibility whilst being easier
to program, so it is claimed: the OpenDoc API is a set of C++
classes, and COM does not need to be learned. Another argument that is
cited in its favour is that OpenDoc supports more features and
flexibility, so going with it avoids a difficult transition and code
reworking as OLE-2 plays catch-up. In theory, most advances in OLE-2
will be supported automatically by OpenDoc.

OpenDoc makes the following assumptions about the platform it runs upon:

\begin{itemize}
\item There is an event based graphical user interface model for the platform.
\item There is a method of dispatching messages between separately compiled
executables. For encapsulation, OpenDoc expresses the boundaries between
executables in terms of objects and methods. When running on top of OLE-2,
Microsoft's COM (Common Object Model) is used, but IBM's SOM will be used in future.
\item There is a persistent storage system with stream based I/O.
available.
\end{itemize}
    
\section{How can we support them?}

The Microsoft Foundation Classes library (MFC) provides a very
high-level wrapper around OLE-2: it should be possible to provide a
similar wrapper for wx/FrameWork, either for OLE-2 or OpenDoc. The key
is probably to make explicit the representation of documents, views,
items, drop sites, data objects etc. in a standard and generic way, that
can be adapted to whatever underlying technology is actually available.

Although the programmer has to shift gear somewhat in adapting to this
regime, it will pay dividends because a standard application `model' can
have lots of default functionality built in, and can be made applicable
to platforms which do not have OLE or OpenDoc capabilities, as well as
those that do. On platforms such as Motif, some capabilities will be
`simulated' using existing API calls for e.g. drag and drop,
whilst under Windows, OLE/OpenDoc calls will be used.

The OpenDoc toolkit (alpha 7) says only a little about programming
container applications, and there are no container samples. We will
assume in the real release, it will be simpler to create an OpenDoc
container document than use OLE-2 facilities.

One scenario is to allow the option of compilation of the entire
application in one executable using a non-OpenDoc implementation of the
`OpenDoc' wrapper (e.g., standard Windows/other GUI drag-and-drop
calls). Much of the application-supplied OpenDoc functions will simply
not be called, or will be called from within the program space without using
OpenDoc. This way, the programmer can supply {\it parts} to some users,
and a {\it complete application} with no OpenDoc/OLE-2 dependence, to
others, with a only a recompile. This strategy obviously {\it must} be taken where
there is no OpenDoc implementation available.

This will require a significant amount of work in wx/FrameWork to
support this, but there is probably no alternative if code is to be
truly platform-independent.

Assuming we {\it have} to supply a OpenDoc/OLE-2-independent means of
supplying client-side functionality, i.e. a main window and documents to
put our parts (objects) into, then we have the {\it option} of creating
an OLE/OpenDoc container capability in wx/FrameWork, so that our OpenDoc parts can
interact with it, or not bothering with container capability at all.
If you have parts, there's not much point in supplying a
container application when something like MS Word would do, unless one
takes the view that the ultimate container application (shell) has yet
to be written; and perhaps not all of an application can be made to fit
into the container/part mould anyway.

To simplify matters, we might ignore linking initially as it complicates
matters, and concentrate on embedding. However, this will come unstuck
when we try representing a hypertext network of information, for example.

Finally, we have to bear in mind ease of use for programming in wx/FrameWork.
Can our high-level class library be designed to take these different modes of
implementation into account, and still be intuitive? It's worth a try!

\section{OpenDoc terminology}

\begin{itemize}
\item {\bf part:} a component, implemented in a DLL (under Windows).
The implementation contains part-specific data and functionality.
\item {\bf frame:} once several parts are competing for space on the display or the printed
page, layout can become complex and difficult. As a result, OpenDoc
defines  a concept called a frame to regularize the negotiation between parts for space.
Frames form the basis by which documents are composed from smaller parts.
The structure of the frames provides information about layout,
containment, and document context. There may be more than one frame per
part (e.g. different views onto the same part).
\item {\bf facet:} A frame has one or more facets, containing canvas, shape,
and transorm information. Additional facets might be used for
off-screen drawing (e.g. printing).
\end{itemize}


\section{Case study: Hardy as a component technology application}

(To be written).

\end{document}