%***********************************************************************
%***********************************************************************
%***********************************************************************

\chapter{Release Notes}
\index{release notes}

\V\ is usually found in one of several archives: \code{v-1.00.tar.gz},
the full distribution of all current versions of V; \code{vx-1.00.tar.gz},
the X only distribution; and \code{vwin100.zip}, the MS-Windows only distribution.
Note the version (1.00) will change as V is updated.

\section {X Window System}
\index{X Window System}

The current X implementation of \V\ uses the Athena widget set with
some modified versions of some widgets from the Xaw3d widget set. 
The code has about 95\% of what is needed to work on Motif, but this
effort has been largely abandoned. If someone out there \emph{really} wants
Motif, please work on it.

The latest plan is to port \V to the \code{gtk} tool kit for Linux. Eventually,
the Athena version will be partially abandoned (new features provided by
gtk will not be added to the Athena version), and \code{gtk} will become
the new \V standard.

\subsection*{Directories}

The \V\ directory structure has been designed to allow you to either
install \V\ in a personal directory, or at a higher system level.
By defining an appropriate search path in the \code{Makefile}, your
applications can find the required \V\ files.

You should download the standard distribution file
\code{vx-1.00.tar.gz}\footnote{Or whatever the latest version is...},
which is a \code{gzip} GNU Zipped tar file (or the full combined version,
\code{v-1.00.tar.gz}). After you unzip the file
(with \code{gunzip}, or the -z switch on some versions of \code{tar}),
you can extract the file to wherever you want it. It will build
a \code{/v} subdirectory from the directory containing the \code{vx-1.00.tar}
file. The file hierarchy is:

\begin{description}
\item[/v] The main \V\ directory.

\item[/v/appgen] V application generator program.

\item[/v/bccide] MS-Windows build files for Borland C++. (Not included
in X only distribution.)

\item[/bmp2vbm] Source for a simple MS-Windows and OS/2 \code{.bmp} bitmap
format to \code{.vbm} V bit map format converter.

\item[/v/bin] The \code{/bin} directory is used to hold the binaries
of \V\ sample programs. No binaries are included on the distribution,
but at least the subdirectories \code{/intel} for Linux and \code{/sun4} for
Suns are included. There may be other subdirectories for other architectures.

\item[/v/doc] The sources for \V\ documentation. The documentation
is in \LaTeX format. The standard distribution includes only the source
\LaTeX files. Other versions, including dvi and Postscript, are available from
the \V\ ftp site.

\item[/v/draw] Source for the VDraw example program. Examples that
are identical across platforms use a \code{.cpp} file extension.

\item[/v/drawex] Very simple V draw example from C/C++ Users Journal
article.

\item[/v/examp] Source for a simple \V\ example.

\item[/v/includex/v] Source for the X \code{*.h} \V\ header files.

\item[/v/includew/v] Source for the MS-Windows \code{*.h} \V\ header files.
(Not included on X only version.)

\item[/v/lib] Compiled version of the \V\ library will be placed
under appropriate subdirectories here. No precompiled libraries are
included in the standard distribution.

\item[/v/msvc] Project and make files for Microsoft VC++.

\item[/v/obj] Compile object code is saved under here.

\item[/v/srcx] The full C++ source for the X \V\ library. The files
use a \code{.cxx} extension.

\item[/v/srcwin] The full C++ source for the Ms-Windows \V\ library. The files
use a \code{.cxx} extension. (Not on X only version.)

\item[/v/test] The test program used to test \V\ functionality.

\item[/v/texted] Source for a simple editor based on vTextEdit class.

\item[/v/tutor] The source code for the tutorial example.

\item[/v/vxgl] Source for V canvas class that interfaces to X
version of OpenGL.

\item[/v/watcom] Project and make files for Watcom C++ compiler.

\end{description}

\subsection* {Compilers}

The \code{makefile} provided with \V\ uses the GNU C++ compiler,
\code{g++}. \V\ does not use templates or other C++ features that
can cause portability problems. The current version has been
built and tested using \code{g++} Version 2.7.2.3, although it
did work with Version 2.6.3, but
not earlier versions. There is no inherent reason that \V\ should
not compile with other C++ compilers.

\subsection*{The X Makefile}
\index{makefile}

The \code{Makefile} is the main way to build X versions of \V.
It has comments that should help you to build the X version of \V.
See the file README.TXT for more instructions for installing \V
on a *nix platform. All of the customizations for a given platform
have been isolated into the file \code[Config.mk].

To date, \V\ has successfully been compiled on several platforms,
including Linux, SunOS, Solaris, AIX, SGIs, and DEC Alphas. The standard distribution
includes a \code{Makefile}
that can be easily configured for several platforms. The makefile requires
GNU make! The secret is to examine \code{Config.mk} and add and modify
the definitions at the beginning as needed for your platform. (For Linux,
this will usually be a no op, since Linux is the default configuration.)
Examine the definitions already there, and then add a section with
the locations defined as needed for your platform. Then use an \code{ARCH=}
definition on the \code{make} line (or make your platform the default.)

\subsection*{X Resources}
\index{X Resources}

\V\ makes limited used of X resources. The main use is to define
the basic color schemes for controls and dialogs. The following
resources are used:

\begin{description}

\item[vDialogBG] The color used for the background of dialogs and
command bars.

\item[vStatusBarBG] The color used for the background of the status
bar.

\item[vMenuBarBG] The background color of the menu bar and menu drop
downs.

\item[vControlBG] The background color for some controls, such as
sliders and scroll bars.

\item[vControlFace] The color used for the faces of various
controls such as buttons.

\item[vLightControlShadow] The color used for the light shadow
on 3D controls.

\item[vDarkControlShadow] The color used for the dark shadow on
3D controls.

\end{description}

By varying just the above X resources, you can really change
the visual look of your \V\ app.
The \code{/v/srcx} directory contains several files of the
form \code{vRes*} that contain various color schemes.
The default color scheme is contained in \code{vResDefault}
(but you don't need to load it -- it is the default).
The file \code{vResBlueMtf} contains the color scheme similar
to Motif. This is the contents of \code{vResDefault}:

\begin{verbatim}
*vDialogBG: gray75
*vStatusBarBG: gray80
*vMenuBarBG: gray70
*vControlBG: gray80
*vControlFace: gray70
*vLightControlShadow: gray87
*vDarkControlShadow: gray50
\end{verbatim}

To use one of these, or your own, resource files, you can
use the command \code{xrdb -merge vResColorscheme}. You
can also add the lines to your \code{.Xresources} file.

The X program name is the name you supply to the \code{vApp} constructor.

\subsection* {X Bugs}

The PostScript print driver does not draw shapes with hatched
brushes.

The PostScript drawing canvas does not support \code{CopyFromMemoryDC}.

Source code uses two naming conventions - \code{.cxx} and
\code{.cpp}. Gnu g++ version 2.6 and later support both
file extensions. G++ version 2.5 doesn't like \code{.cpp},
so you might have to rename those files to \code{.cxx},

There seems to be problems with colors on X Pseudocolor systems.

\section{Microsoft Windows}
\index{Microsoft Windows}\index{Windows}

The current implementation of \V\ for MS-Windows is for Windows 3.1
and WIN32 (Windows 95 and NT). We will refer to this version as \code{Vwin} in this
description. Eventually some native Windows 95 controls will
be used, but for now the WIN32 version works fine for Win95.
The Windows version of \V\ is available at as 
\code[vwin100.zip] (a MS-Windows Zip format file). on the \V\ ftp
site. You will need a version of \code{ZIP} or \code{gunzip} and
\code{tar} to extract \V. The MS-Windows version does not include
documentation. Documentation is available as both \LaTeX files in
the X distribution, or split into a pair of Postscript or
DVI files on the \V\ ftp directory.

\subsection* {Directories}

The directory structure of \V\ under MS-Windows is similar to the X version.
On the distribution, the MS-Windows hierarchy is found under the \code{/v}
directory. (We will use Unix / notation for files instead of the
usual MS-Windows backslash notation. Most MS-Windows compilers handle
the / correctly, and / is used throughout the \V\ source files.)
When you unzip the archive, a subdirectory \code{/v} will be
built.

Under \code{/v} are \code{/bin/win} for the example \V\ MS-Windows
binaries, \code{/draw} for the VDraw example program, \code{/examp}
for a simple example program, \code{/includew/v} for the \V\
\code{.h} header files, \code{/lib/win} for the MS-Windows compiled
library, \code{/obj/win*} for the object files, \code{/srcwin}
for the MS-Windows version of the source code, \code{/test} for the
test driver program, and \code{/tutor} for the source code to the
tutorial included in this reference manual.

For MS-Windows, the \V\ library source files use a \code{.cpp} extension.
The example programs also use \code{.cpp}. The source for most of the
example programs is identical for the MS-Windows and X versions! However,
the source for the library \code{.cpp} and \code{.h} files are different
for each platform, so you must be careful not to mix the X and MS-Windows
versions of source code and header files.

\subsection* {Compilers}

\V has been successfully been compiled using Borland C++ 4.5 for
Win3.1 and WIN32; Borland C++ 5.02 for WIN32; Watcom 10.6 for Win3.1 and WIN32;
the GNU-WIN32 gnu g++ compiler; and Microsoft VisualC++ under several versions.

Several Borland \code{.ide} files are included on the directory 
\code{/vwin/bccide}. The \code{.ide} files assume \V\ is built on
drive C:, so you may have to modify it if you want to build \V\
on your own system. If you are using another compiler, then you
need to compile \emph{every} \code{.cpp} file found on the
\code{/srcwin} directory.

Project files for compiling with Watcom C++ are included in
the directory \code{v/watcom}. Unlike the Borland versions,
the object code and libraries are built directly on these
\code{watcom} directories.

The required changes and makefiles required for the \code{mingw32} compiler
will be made available on the \V web site.

\subsection* {MDI/SDI Models}
\index{MDI model}

\V\ for MS-Windows supports both the MS-Windows MDI and SDI models. 
By default, \V\ uses MDI, and will bring up the main MDI window,
and open the first MDI child window. There currently is no way to
have a main MDI window with no active MDI child windows -- when
you exit the last window, the application closes. The menu,
command bar, and status bars will change to the ones defined by
each child window as each child window is activated.

\V\ will automatically append a \code{Window} menu item to the main
menu. The built in \code{Window} menu supports the standard cascade
and tile MDI operations, as well as showing a list of MDI children.

\index{SDI model}
You can also get MS-Windows applications to look like the standard
SDI model. If you want an SDI app, you control this in the
static declaration of the \code{vApp} object:

\begin{verbatim}
  static testApp* tApp = new testApp("Vtest",1);
\end{verbatim}

The second parameter controls MDI or SDI. A default parameter
is defined by \V as 0 to indicate the MDI model. If you specify
a 1, then \V will take an SDI look. It actually does this
by using the MDI code, but maximizing the canvas window,
removing the extra buttons from the menu bar, and not
adding the \code{Window} menu. It is impossible for the
user to tell that this is really an MDI application, but
\V does not strictly enforce this. If you create more than
a single \code{vCmdWindow} object, unpredictable things will
happen under the SDI simulation. It is up to you to not do that.

Since X doesn't have an MDI/SDI equivalent, it is harmless
to specify SDI to an X version of your app.

\subsection* {Icons}

As stated in the main part of this manual, \V\ does not use resource files.
This is true for the MS-Windows versions. However, there is one reason you
might want to include a \code{.RC} file with a \V\ MS-Windows application,
and that is to allow you to define the icons used with the application.
(These are MS-Windows icons, and are \emph{not} the same things as
\code{vIcons}.)

Typical MS-Windows MDI applications use two icons - one for when the whole application
is iconized, and one when each child window is iconized. If you don't supply a
\code{.RC} file, you will get the default MS-Windows icons. The \V\ distribution
supplies two default icons of its own, called \code{vapp.ico} and \code{vwindow.ico}.
By including the definitions \code{vAppIcon} \code{ICON} \code{vapp.ico} and
\code{vWindowIcon} \code{ICON} \code{vwindow.ico} in the \code{.RC} file,
\V\ will load and use those icons for the application and each child window
respectively. You can substitute whatever two icons you want for your application
by specifying different \code{.ico} files for
the \code{vAppIcon} and \code{vWindowIcon} names in the \code{.RC} file.

\subsection* {DEF File}

MS-Windows applications are typically compiled using a \code{.DEF} file. You
can modify any of the \code{.DEF} files included with \V\ sample programs.

\subsection* {Bugs on MS-Windows}

\section{V Versions}

\begin{description}
\item[Version 1.00]
This version was local to the University of New Mexico on January 10, 1996.
Versions 1.01, 1.02, and 1.03 were local maintenance releases.

\item[Version 1.04]
This was the first major public release of \V, and was announced
to the world on February 14, 1996.

\item[Version 1.05]
This version had several bug fixes obtained from feedback of the
public release.

\item[Version 1.06]

This was an X only release, and added 3D controls.

\item[Version 1.07]

This release was never formally announced, and included some
of the changes listed for version 1.07.

\item[Version 1.08]

The 4/15/96 release added several significant features to \V:

\begin{itemize}

\item The \code{vMemoryDC} drawing canvas, including new methods
\code{CopyFromMemoryDC} and \code{DrawColorPoints}.

\item Internal revisions for handling of color, including adding
\code{vColor::ResetColor} to allow reuse of color maps, and 
\code{vColor::BitsOfColor} to get color capability. These
revisions allow \V apps to make more effective use of default
color maps.

\item \code{vPen::SetColor(r,g,b)} and \code{vBrush::SetColor(r,g,b)}
are being dropped in favor of the \code{vColor} forms. These calls
break the hidden management of color maps, and while still included
in the code, should \emph{not} be used. Support for the \code{(r,g,b)}
form will be dropped entirely in future versions of \V.

\item \code{C\_ToggleIconButton} was added to allow a pressed in
button interface look in place of check boxes and radio buttons.

\item Documentation for \code{ChangeColor} and \code{C\_ColorLabel}
was added, although the functionality has been there for a while.

\item The WIN32 port was finished, and the X and MS-Windows versions
are now in sync.

\end{itemize}

\item[Version 1.09]
Added \code{C\_ToggleButton} and
\code{C\_ToggleFrame} controls. It also includes a large
number of \V icons suitable for building command pane
tool bars.

\item[Version 1.10]
The 5/29/96 release of \V\ includes the following enhancements
and changes:

\begin{itemize}

\item The \V\ Icon Editor - an icon editor to
create icons for various \V\ controls.

\item Inclusion of accelerator key support in menus.

\item Addition of the \code{ChangeListPtr} set type to allow
completely dynamic lists, combo boxes, and spinners.

\item Addition of \code{DrawLines}, \code{DrawPoints}, and
\code{DrawRectangles} to \code{vCanvas}.

\item Several bug fixes for both MS-Windows and X, some relatively
major.

\item The canvas page scroll messages were changed
on the X version to correspond to the behavior of the MS-Windows version.
A page scroll message is sent only at the completion of
a scroll, not continuously as before. It is usually rather
difficult to implement nice continuous scrolling, so this
approach seems more useful to more people. This is the only
known change that might affect compatibility with previous
\V applications.

\item Addition of a directory for outside contributions.

\end{itemize}

\item[Version 1.11]

The 7/4/96 release of \V\ has several minor bug fixes for the
MS-Windows and X versions. It also adds the \code{WorkSlice} methods
to support applications that require computations to continue
even if the user is not entering commands to the application.

\item[Version 1.12]

This was a bug fix release for MS-Windows. The X version was
unchanged, but renumbered for consistency.

\item[Version 1.13]

This 8/24/1996 release of \V\ is a major release with several
new features, and some significant bug fixes that can change
the behavior of existing \V applications. The following includes
a list of changes:

\begin{itemize}

\item The \V\ Application Generator, \code{vgen} is now included
with the standard distribution. It will generate a simple
\V\ application as a starting skeleton for new apps.

\item The values being passed by \V\ to \code{vCanvasPane::VPage} and
\code{HPage} were incorrect on the X version. The documentation states
that the values for \code{Top} should be in the range 0 to 100.
The MS-Windows version worked correctly, but the X version was
passing a range of 0 to (100-Shown). This bug actually has
been in the X version since the switch to 3D Controls. With
version 1.13, both MS-Windows and X work the same.

\item The MS-Windows version of \code{vDC::DrawText} was fixed to
work according to the documentation. It had been drawing text
with the x,y as the upper left corner of the text. Beginning
with 1.13, it now draws at the lower left corner as specified
in the documentation.

\item Two functions, \code{GetHScroll} and \code{GetVScroll},
were added to \code{vCanvasPane} to make dealing with
scroll bars easier.

\item A new standard using \code{enums} for generating IDs for
controls has been adopted beginning with 1.13.

\item \code{C\_TextIn} controls now allow you to specify the
width of the control in characters using the \code{size} field.
This is described in Chapter 6.

\item In \code{vCanvasPane}, new parameters (with default
values for backward compatibility) were added to
\code{CopyFromMemoryDC} to allow subregions to be copied.

\item Using a \code{vTransparent} pen when drawing text
now results in leaving the existing background when drawing, and
a \code{vSolid} pen overwrites with the current background
color.

\item There was a conflict on MS-Windows with using \code{VK\_} for
key names. The MS-Windows version was changed long ago, and now
the X version also uses lower case letters (e.g., \code{vk\_Tab}).


\end{itemize}

\item[Version 1.14]

The major addition to 10/6/96 \V Release 1.14 is the addition of
the \code{vTextEditor} class, which is a very good first pass at
a complete editing canvas. The editor is complete, can be
extended to support custom command sets or file management.
It is missing cut, copy, and paste, which will be implemented
as general support for these is added to \V. The code for
\code{vTextEditor} is based on \code{vTextCanvasPane}, and
is identical for the X and MS-Windows versions.

Also, for the X Version, support for OpenGL has been added.
This support is found in the distribution directory
\code{v/vxgl}. While the \V OpenGL canvas pane seems
very robust, it is still somewhat experimental. I would
like any feedback on its use and design.

Other changes, mostly bug fixes, include:

\begin{itemize}

\item X version: The little close button on the left of the
menu bar has been dropped by popular request. It seems most people
didn't like it. If you do, you can still get it by defining
the symbol USE\_CLOSE\_BUTTON. Instead, \V now supports the
X WM\_DELETE\_WINDOW protocol. This protocol is supported
slightly differently by different window managers, but
accomplishes the same thing as the old close button.

\item X version: There was a minor bug in how the
scroll bars worked when \code{top == 0}.

\item X version: The method used to get the size of a window
was changed, and should now give correct values.

\item X version: There was a bug in drawing radio buttons
that only showed up on some systems.

\item X version: There was a bug in changing the current
selection in combo boxes.

\item X version: There was a bug in setting colors for the
PostScript DC.

\item X and MS-Windows: There were several bugs in
\code{vTextCanvasPane} exposed by the implementation
of \code{vTextEditor}.

\item X version: There was a bug in the key mapping that would
cause a program to terminate if an unrecognized key was pressed.

\item MS-Windows: The method to determine the size of the MDI
frame and client windows was improved (I hope!).

\item MS-Windows: A bug with the work timer was fixed. The interaction
between the work timer, check events, and the MS-Windows message
loop was changed to work better.

\item MS-Windows: The argument order of ClearRect was fixed to correspond
to X and the documentation.

\item MS-Windows: There was a bug that didn't allow SetValue to work
correctly for some controls.

\item MS-Windows: A bug in handling the MS-Windows caret in text
canvases was fixed. This one was a bit subtle, but nasty in
possible side effects. Also, EnterFocus and LeaveFocus did not work correctly.

\item MS-Windows: A bug in setting text colors on NT and Windows 3.1 was fixed.
The bug did not manifest itself on Windows 95.

\end{itemize}

\item[Version 1.15]

Release of V Version 1.15 has some non-backward compatible
changes. In previous versions of V, there were inconsistencies in
the order of width and height parameters. These have all been now
changed to consistently use a width/height order. (Except for
vIcon, which still use height/width.) The decision to fix this
order came from a general consensus of the V mail list.

You will need to change your code to reflect the new changes.
The following things must be changed:

1. Any calls to the constructor of a base or derived vCmdWindow
will need the width and height order swapped.

2. Calls or overrides of vApp::NewAppWin need the
order of width and height swapped.

3. Calls to vCanvasPane::SetHeightWidth(h,w) need to be
changed to vCanvasPane::SetWidthHeight(w,h).

4. Calls or overrides of all versions of Redraw(x,y,h,w)
need to be changed to Redraw(x,y,w,h).

5. Calls or overrides of all versions of Resize(h,w)
need to be changed to Resize(w,h). (The vTextCanvas
row/column versions retain their row/column order.)

Also, the makefiles have been revised for more flexible
building on different *nix platforms.

A new method, vDialog::DialogDisplayed has been added to
allow dynamic setting of dialog control values.

\item[Version 1.16]

Version 1.16 has no significant changes in V functionality.
It mostly has some bug fixes. The only major change is
the release of a completely new set of Makefiles for
the Unix version. These new makefiles were contributed by
a V user, and are much cleaner than the old versions.

A summary of the changes:
\begin{itemize}
\item A small change to the code generated by vAppGen.
\item A fix to scrolling in the V Icon Editor.
\item Some changes to the v\_defs.h file for MS-Windows, including
compatibility changes needed for Microsoft VC++. Project files were
added for MSVC++.
\item The == and != operators for brushes, fonts, pens, and colors were
changed to use reference parameters consistently.
\item Various minor changes to enhance compiler compatibility, both
on MS-Windows and X.
\item VReply was fixed to work over multiple shows.
\item A void* was added to vAppWinfo.
\item Vmemdc had height and width switched.
\item Sizing of buttons on MS-Windows was fixed for Windows 95.
\item A resource leak was fixed for MS-Windows.
\item A major bug that showed up only under Microsoft VC++ was
fixed.
\item Initialization of text in strings was fixed for MS-Windows.
\item Changing the values of radio buttons on MS-Windows now works.
\item Spinners now honor the size specification.
\item A tab keystroke now works correctly on MS-Windows.
\item A bug in 
\item Various new tests were added to the test program.
\item A couple of bugs were fixed in the X OpenGL V interface.
\end{itemize}

\item[Version 1.17]

Version 1.16 has proven to be remarkably stable. A few minor bugs
have been reported and corrected for Version 1.17. Some
enhancements have been added, the most significant allows you
to specify the number of rows displayed in a list box.

A summary of the changes:
\begin{itemize}
\item Lists by default display 8 rows, buy you can now specify and
size between 1 and 32 rows.
\item A bug in Windows when closing multiple windows was fixed.
\item The vReply dialog has been changed to allow a default string in
the input field.
\item Direct printing to \code{lpr} has been added to the X version.
\item The PostScript driver was modified to print better lines.
\end{itemize}

\end{description}

\section {Future Plans}

\begin{itemize}

\item An OS/2 Port is currently in Alpha release. Watch the \code{www.objectcentral.com}
home page for news.

\item The major plan is to port \V to \code{gtk} for version 1.18. This version
will not have major enhancements to \V. However, lifting the Athena restriction will
allow many new features to be added. These will be included in \V version 2.0, which
I hope to have done by summer. New functionality planned includes floating help boxes,
multiple list selection, faster graphics, a dialog canvas pane, index tabs in
dialogs, and probably more. I hope to minimize any changes required in the API.

\item \V still needs a class to portably interact with the standard system
clipboards.

\end{itemize}