
This is the V FAQ. It is still evolving, but contains
frequent and interesting questions about V. It also has
some useful tips for writing V applications.

FAQ updated August 20, 1996
-------------------------------------------------------------
Topics:

**** HOW CAN I HELP? ****
**** How can I help contribute to V?

**** V CLASSES ****
**** About vAppWinInfo class
**** How to use vTimer

**** DRAWING STUFF ****
**** Fast way to display bitmaps?
**** More on displaying images fast
**** Coordinate Translation and Scaling
**** About colors and color maps
**** When to set attributes for a vCanvasPane
**** Too many Redraw messages to keep up with

**** V COMMAND CONTROLS ****
**** How to dynamically modify list controls
**** Does V have Text Edit controls?
**** Changing size of dialogs
**** History of values on menus
**** Getting dynamic changes from TextIn Controls
**** Grouping controls in a dialog
**** Layout of Controls different in X and Windows
**** vIcons as controls in a vCanvasPane
**** Controlling width of Lists
**** Waiting for computations

**** PHILOSOPHY ****
**** V in the Computer Science Classroom
**** Why does V use static tables for menus?
**** Programming for Windows vs. Unix and X
**** V vs. wxWindows
**** Using V for commercial applications

**** PLATFORMS ****
**** WINDOWS.H and WINDOWSX.H files for Windows version 
**** Cygnus gcc-win32
**** Missing files/libraries in X
**** OS/2 Version
**** Mac Version
**** Windows 95 Version

**** MISC. ****
**** Using V from C
**** How can I learn C++?

-------------------------------------------------------------
**** HOW CAN I HELP? ****
-------------------------------------------------------------
**** How can I help contribute to V?
Q:
> How can I contribute to the V project?

A:
As you may know from other sources, so far V has been
pretty much a one person project - me. That means while
V is getting pretty complete, there are still things
missing, and things that could be done to make it better.

I really appreciate help from the ever growing V community.
There are several ways you can help contribute to V:

1) Find bugs. 

If you discover a V bug, I really do appreciate bug reports.
Better are bug reports with a solution. I've received an amazing
number of bug reports along with a patch to the source code to
fix it. While it would be ideal to get a report and a fix, I
still want to get the reports.

2) Contribute applications. 

I'd like to collect two kinds of V applications. First would
be apps that would be useful to the whole V community, either
as a tool, or perhaps as an example of something useful.
I'd also like any kind of app that uses V that you might
wish to share. Any time you can share code that others
might learn from, it will be useful.

3) Additions to V

V does have some things missing (a Text Editor, a direct
draw canvas, multi-selection lists, double click in Athena,
etc.). I would like to see all of these added to V eventually,
but just don't have the time to get to them quickly. I'd
really like contributions such as these.

However, for the contributions to be really useful, they
need to be developed using certain guidelines. First, if
you see a hole you'd like to fill, e-mail me (wampler@cs.unm.edu)
first. Someone else might be working on it, or I might
already have some specific ideas. If it is a big project
(like the OS/2 port), I probably can put you in touch
with others working on the problem.

Second, a new feature for one platform isn't really useful
for inclusion in V. Anything new must run on both Windows
and X, and eventually OS/2 and the Mac. There are a few
ways to handle this requirement. First, do the different
versions yourself. Second, find someone else to do the
other platforms. Third, use only existing V classes.

One problem with distributed development by volunteers
is keeping things in sync. I've been turning out a new
version of V every month or two, so it is hard to keep
contributions current when they are necessarily done
on older versions. We just have to work with it.

Currently (August 1996) there are people or groups
working on OS/2, a multi-selection list control, a
direct draw canvas, and a Mac port. I plan to develop
a vTextEditCanvasPane over the next month.

In summary, I really do like help. It is hard to
coordinate sometimes, but I will do my best. Contributors
will be acknowledged in the appropriate places. Just
send me e-mail with any bugs reports, contributions,
or ideas.

-------------------------------------------------------------
**** V CLASSES
-------------------------------------------------------------
**** About vAppWinInfo class
Q:
> How do you use the vAppWinInfo class? An example?

A:
Well, I don't actually have an example...

If the Vdraw program were written using the MVC model "correctly",
then the representation of each drawing would be held in
a derived vAppWinInfo class instead of the drawing canvas directly.
The information about the data, file name, etc., would be there,
supposedly providing a cleaner separation of data, and possibly
allowing other views of the drawing other than the drawn
representation (like a list of all the points in text or something).
Then the usefulness of vAppWinInfo would be more obvious.

It is really provided more for big MVC model apps, and hasn't
been used by most V apps I've seen.

-------------------------------------------------------------
**** How to use vTimer
Q:
> I want to call a screen update every few seconds.
> Is it best to call the routine from within the TimerTick routine,
> or send an update event to the cmdwin ?

A:
The key to coordinating a timer with a window is to create
the timer object from the command window, and pass the
'this' of the command window to the timer. The timer then
uses the pointer to the command window to call the WindowCommand
method of that window object to do whatever is needed on the timer
event.

Consider the following code excerpts:

   // Derive a simple timer class that allows a command window
   // pointer to be passed in.
   class myCmdWindow;   // Whatever you command window class is
   class myTimer : public vTimer
      {
      public:           //---------------------------------------- public
        myTimer(myCmdWindow* cw) { cmdw = cw; }
        ~myTimer() {}
        virtual void TimerTick()
           // Call the window's WindowCommand to respond to the timer
	   {cmdw->WindowCommand(appropriateID, appropriateID, C_Button);}
      private:          //--------------------------------------- private
        myCmdWindow* cmdw;
      };

   // Then, in the command window

//================>>> myCmdWindow::myCmdWindow <<<================
  myCmdWindow::myCmdWindow(char* name, int height, int width) :
    vCmdWindow(name, height, width)
  { 
    // Appropriate stuff to define window
    // ...

    // Now, create the timer to local myTimer _timer ptr.

    _timer = new myTimer(this);         // create timer
    _timer->TimerSet(1000);             // 1 second interval

    // ....
   }

-------------------------------------------------------------
**** DRAWING STUFF
-------------------------------------------------------------
****  Fast way to display bitmaps?
Q:
> I'm using V to display bitmaps. My app is rendering a complex
> image so I would like to display the result every few seconds. I
> tried drawing my bitmap with DrawIcon, but it takes too long and
> the second call to the function displays the same bitmap even if
> the data of the vIcon changed. I tried using a pen and drawing
> points one by one but that is way too slow.
>  
> So, is there any easy and fast way to display 24-bit bitmaps
> using V?

A:
This may be one of the weaker parts of V. I've spent a good deal
of time with this issue, and can't get stuff real fast. In
theory, writing to a vMemDC should be the fastest way to write
pixels, which you can do a row at a time with DrawColorPoints,
then transferring to the screen with CopyFromMemDC.
This technique get you about as close to the native drawing stuff
as can be done portably, but it is still faster to draw
directly to the screen using DrawColorPoints. It isn't
real fast.

The native tool kits let you work directly with the bitmap/pixmap
in memory, but do it quite differently on Windows and X. Perhaps
someday I'll figure out a way to give portable access to the
underlying model.

An alternative, and not a terrible one, is to get the handle
to the actual X or Windows window used for the canvas.
This is HWND vCanvas::DrawingWindow() for Windows, and
Widget vCanvas::DrawingWindow() -OR- 
Drawable vCanvas::GetXDrawable() for X. You can then use
the HWND or Widget/Drawable as to draw to directly using
the native drawing toolkits. These are usually much easier
to use and figure out than all the control stuff for dialogs
and menus.

-------------------------------------------------------------
**** More on displaying images fast
Q:
> I'm thinking of using V for a project I'm about to start.  I need to 
> be able to display images (8, 16, 24, and maybe 32 bit) to a window 
> and I need to do it very fast.
> 
Actually, in its current state, V can't really do what you need.
The vMemoryDC already uses BitBlt to in the CopyFromMemoryDC
method, but it is still too slow - it takes too long to fill
the image, no matter what mode you use.

The ultimate solution is to provide access directly to the
screen memory via a pointer. This is something like Microsoft's
game API. However, I haven't had the time to do it portably,
although I think it can be done.

The alternative is to drop down to real Windows or X code.
The vCanvas provides the necessary hooks to get the Window,
Drawable, or Widget as needed. This solution is not portable.
-------------------------------------------------------------
**** Coordinate Translation and Scaling
Q:
> When using a canvas with scaling and translation, it's not clear
> whether coordinates are first translated and then scaled, or vice
> versa.

A:
  ScreenX = (((PassedInX + XTranslate) * ScaleMult) / ScaleDiv);

-------------------------------------------------------------
**** About colors and color maps
Q:
> I assume that V tries to allocate read/write color cells when under X,
> so that it can (possibly) change colors.  If the color map is full,
> does it just take what it can get?

A:
Presently, V tries to hide what is going on with the color map.
This led to some problems on the X version in earlier releases.
With V Version 1.07 and later, V tries to allow efficient
use of the colormap while still hiding most of the details.

The main way to use and generate colors is with vColor objects.
There are 16 predefined vColors, and you can declare other
vColors, either with no color specified (which defaults to black),
or your own colors. Ideally, it wouldn't matter how many colors
you used, or how many vColors you declared, or how many times
you changed the color value of vColor objects.

In  reality, some color systems do allow unlimited colors, but
most existing systems run with a palette or color map of 256
colors. So mostly, at any given time, a program can have only
256 active colors. As better color hardware gets more widely
used, this situation will change, but count on only 256 for now.

The question then becomes which 256 colors are available to
the program. Both X and Windows provide default system
color maps that provide the current 256 colors, and V uses
the default system color maps. The way the system color maps
work are somewhat different for X and Windows, however.

The situation for X is currently somewhat better than Windows.
The default system color map is allocated partly ReadOnly, and
partly ReadWrite. Usually, four to eight colors are allocated
ReadOnly, and correspond to black, white, and the basic colors
used by the screen manager. The rest of the entries are available
for program use. When you create a new color, either by declaring
a vColor object with a new color, or you use vColor::Set to set
an existing object to a new color, a new cell of the system
color map is allocated and used. If you continue to generate
more new colors, the map eventually fills up, and you don't
get what you had hoped for.

With V Version 1.07 and later, a new method called 
vColor::ResetColor was added to help solve this problem.
If you will be generating lots of new colors, you can
only use about 245 or so of them at a time. If you
use vColor::Set to change the colors, the color map
fills up. If, on the other hand, you reuse and existing
vColor object by calling vColor::ResetColor, then the
original entry in the X system color map is reused.
Thus, as long as you don't use more than the number of
available entries in the color map, you won't have
problems displaying just what you want at any given time.
You can use vColor::BitsOfColor to determine the color
resolution of the system you are running on.

The situation on Windows is different. There, you still
usually have 256 colors, but the default system color
map (called a palette in Windows jargon) is fixed.
Each time you use a color, Windows uses the closest
match, and this is sometimes a dithered color. Thus,
while you will never run out of palette entries, you
also don't always get the color you wanted. 

Since Windows systems more commonly have more colors, and
since you don't run out of color map entries, I don't
plan to change this soon. Changing would mean adding
a color map or pallete V object, with all the portability
problems that introduces. For now, vColor::Set and
vColor::Reset have identical behavior on Windows, but
quite different behavior on X.

-------------------------------------------------------------
**** When to set attributes for a vCanvasPane
Q:
> When *exactly* is the right time to set such attributes as
> Background color etc. to a vCanvasPane? The attached DC is not
> available at constructor call, so I tricked around using static
> variables and Redraw(), but there has to be a cleaner way, no?

A:
Actually, you got it. Redraw is called when the window
is first displayed, before you have any chance to call
any of your code. So, you really do need something like:

  void myCanvas::Redraw(int x, int y, int h, int w)
  {
    static int first = 1;

    // Redraw is called when the canvas is first displayed,
    // before your code can do any real work. The vDC is
    // available at this point. Any special initialization
    // needs to be done here because the vDC is not
    // available at constructor time.
    if (first)
      {
        first = 0;

        // Set colors, whatever now...

        // And call your parent class's Redraw
        vParentPane::Redraw(x,y,h,w);
        return;
      }
    // Normal Redraw code goes here
    ....
  }

-------------------------------------------------------------
**** Too many Redraw messages to keep up with
Q.
> My V application takes quite a bit of time to redraw its
> image. When I drag another window across the V app's window,
> the app gets behind trying to keep up with all the Redraw
> messages sent by this action. Is there a way around this
> problem?

A.
This problem doesn't occur on all platforms. (e.g., Windows
draws an outline of the top window, avoiding these multiple
calls to Redraw. X and NT do generate multiple calls.)
No matter how fast V drawing ever gets, this situation will
no doubt continue to exist. There is a rather simple solution
that works for the V Icon editor that limits the total number
of redraws to 2.  Consider the following code fragment adapted
from the V Icon Editor code:

//===================>>> myCanvasPane::Redraw <<<=================
  void myCanvasPane::Redraw(int x, int y, int w, int h)
  {
    // Cheap way to handle multiple calls to Redraw that
    // doesn't use the passed coordinates.

    static int nest = 0;  // Track multiple calls to Redraw

    if (++nest > 1)   // ignore multiple calls
        return;

    DrawImage();      // draw image - may take a while

    if (nest > 1)     // had nested calls, so need to redraw again
      {
        DrawImage();  // draw image
      }
   nest = 0;          // Really done
  }

-------------------------------------------------------------
**** V COMMAND CONTROLS
-------------------------------------------------------------
**** How to dynamically modify list controls
Q:
> I need the ability to dynamically add/delete/modify items in a
> list box control.

A:
There are two ways to do this. You can modify the contents
of the ORIGINAL list, and then call the SetValue function
with the 'ChangeList' value. You can also create a new list,
and call SetValue with the 'ChangeListPtr' value. These are
explained in the reference manual in more detail.

-------------------------------------------------------------
**** Does V have Text Edit controls?
Q:
> Are there any text editors (or a text widget) out there
> written using V?

A:
I wish I had a nice text edit canvas, but just haven't had the
time to get to it. I'd love a contribution from someone.

I do have a text editor I've been stringing along for YEARS that
is mostly working under V right now, but it uses a private
command set (although it can be configured), and is really
a programmer's editor that works exactly the way I think an
editor should work.

So, I want to write a good text editor canvas, and port my
editor to it. Another maybe someday.

-------------------------------------------------------------
**** Changing size of dialogs
Q:
> With dialogs, and even command windows is there a way to set the
> minimum and/or maximum size allowed for the user to resize?  Some
> dialogs just don't make any sense to allow the user to resize, while
> others would be really nice to allow the user to change the size on.
> 

A:
Dialogs are whatever size they are. The X window manager does whatever
it does to dialogs if you fiddle them, and I don't think I can fix
V to freeze the sizes.

-------------------------------------------------------------
**** History of values on menus
Q:
> I have a field that I would like to maintain a ``history'' of,
> such that if the user enters a new value it will be added the the
> history.  Something of a combination C_ComboBox and a C_TextIn.  I'm
> certain you've seen this sort of thing under Windoze.

A:
Hmm... V does not allow you to dynamically add items to a menu.
It does let you change the contents of a menu item. A good compromise
might be to keep a history of the last 4 things in a menu (using
blanks or <none> until you fill in the field), and the full history
in a dialog using a list or a combo box (which can now be totally
dynamic in V 1.10).

-------------------------------------------------------------
**** Getting dynamic changes from TextIn Controls
Q1:
> Upon completion of data entry into a single line text field, is there
> a way to retrieve the data from that field upon completion of text
> entry(signaled either by a carriage return or a tab key) rather than
> pressing a button to invoke the GetTextIn function?

A:
V can't do this. You could do this directly on X or on Windows,
but the mechanism is completely different on each platform, so
V has to hide it. On windows, pressing Return will terminate
the dialog if there is a default button defined, but that helps
only for one text in field, and it doesn't work on the X
version. The next best alternative might be to put a "submit"
button to the right of each field you want to work this way.
A pain, but...

Q2:
> Is there a way to traverse a set of single line text fields
> per keystroke, as opposed to moving the mouse from one text 
> field to another?

A:
This works on the Windows version right now, but doesn't work
on the X Athena version. It might work for the Motif version
when it is done.

-------------------------------------------------------------
**** Grouping controls in a dialog
Q:
> When designing a dialog window, I sometimes want to place a control to the
> right of several other controls. This can be done by giving cRightOf and
> cBelow (members of CommandObject) the right values. By this I can place
> a control to the right of another. I would like to place the control to 
> the right of three other controls but as the size becomes dynamic, I 
> don't know which one will be the largest. Is there a way to express this 
> in the CommandObject structure? Or are there other ways to achieve this 
> goal?

A:
The best way I know to get a control to the right of (or below or
whatever) a group of other controls is to place the other controls
in a frame. Since you can make the frame have no border, you can make
it so it won't show on the displayed dialog. You can also use
blank objects as space fillers to help control positions.
Another thing that helps is padding the messages with blanks
to get alignment right.

Another trick is to make a control that will be as large
as the largest control that gets generated, and then make
it hidden. It will count in the size calculations, but not
be displayed in the dialog. Hidden controls can occupy the
same location on the dialog as the controls you want to see.

Using borderless frames is the best tool that V has for
controlling tricky layout, but even so, sometimes you still
can't get everything placed exactly as you want. This is one
of the compromises of the V design. Most of the time, you can
design pretty good looking dialogs. Sometimes, you have to
compromise, and get OK instead of perfect.  All things considered,
I hope most V users will find this a reasonable compromise.

-------------------------------------------------------------
**** Layout of Controls different in X and Windows
Q:
> I've got a problem with positioning the controls in a dialog box. 
> The linux version is working correct, but the same source, compiled with 
> Borland, results in a dialog box with overlapping controls. Do you have a 
> clue?
> 

The documentation needs to be more explicit about this. It turns
out that this is actually an inherent problem with V. If you had
started out with Windows, you'd probably find the X version was
OK. The problem is that not all controls are the same relative
size on X and Windows. While dialogs with just buttons and label
fields will generally work on both platforms, using lists,
spinners, or progress bars will often give a good looking result
on one platform, but not another.

Fortunately, there are a couple of solutions for this problem.
Both, however, involve being able to compile for both platforms.
Of course, you wouldn't be seeing the problem at all if you
weren't compiling on both platforms.

Sometimes using a different control as the reference control
works. For example, if you had a label and a spinner on one
line, and want to put another label and spinner below, the
natural tendency is to use the label since it is first. However,
the spinner is taller on Windows, so will generate an overlap
on the Windows version. Using the spinner as the reference
rather than the label solves the problem.

The other thing is to use borderless frames, and position
controls relative to the frame rather than controls in the
frame. By combining this and the above technique, you can
usually design an attractive dialog that works on both
platforms. The vDraw example program quick pick dialog
uses these tricks to get a layout suitable for both platforms.

I wish it were easier, but it is just not possible to get
all controls the same relative size on all platforms. At
least there is a way around the problem, even if it takes
a bit more care. Usually, though, it just takes 20 or 30 minutes
to clean up a dialog.

-------------------------------------------------------------
**** vIcons as controls in a vCanvasPane
Q:
> 
> I'm working on a simple application for FreeBSD, and would like to
> use the V GUI toolkit.  I have the following need for this application:
> 
> The main window of the application will represent a group of objects
> as icons.  Each icon will have an image and a name.  When the user
> double-clicks on an icon, a dialog allowing the user to customize
> that object will be created/shown.
> 
> Is there a straight forward method in V to represent a scrolling
> "icon arena", where each icon represents an object?  I've thought
> about making each object and icon button and just adding all of them 
> to a command window, but I don't quite see how to make the window
> scrollable.
> 

A:
You will have to do some work, but this would be true for most
any GUI toolkit.

You can draw a V icon anywhere in the canvas of a command window.
For each icon, you would have to track its X,Y position, and
associated label. (A simple list would do.) You then map mouse 
clicks to the icon you've placed at the mouse location by
searching your list.  Use scroll bars in the canvas as needed,
and adjust mouse coordinates to account for scrolling.

A little work, but not that hard. The double click is harder.
V does not support a separate message for double clicks. You
can fake it by counting two clicks, or get close to real by
using a timer. This limitation is mostly due to the Athena
widget set on X.

-------------------------------------------------------------
**** Controlling width of Lists
Q:
> One more question, have you thought about my suggestion to let the
> user control the width of a C_List ?

The way lists are supposed to work now is that V will use
the width of the widest item in the list when first instantiated.
So one possibility is to first create the list with a fake item
that is as wide as the widest list item you expect, and then
use ChangeList or ChangeListPtr to change to the actual list.
The problem on Windows is that it is hard to dynamically resize
the whole dialog, so I do the best I can by sizing the list
to the widest item. This then determines the size and positions
of all the other controls in a dialog with a list. In fact,
I don't know how non-V Windows programs handle list size, if
they really do. Windows dialogs are normally fixed size.

-------------------------------------------------------------
**** Waiting for computations
Q:
> Could you please tell me what's the best way to tackle the following
> problem? I would like to have a modal dialog that shows the user some
> useful information about a time-consuming operation. Basically, I want
> to open a modal dialog, start the computation and let the computation
> update the dialog's command objects. How can this be done? If the
> dialog is not modal it would be no problem, but I definitely want to
> block all input to the application. What I need is some routine to
> Show a modal dialog but returning immediately so that the program can
> proceed.
> 
A:
This is a hard problem for V, unfortunately. X and Windows handle
modal dialogs somewhat differently, so there is not a portable
solution that V could support.

But one suggestion is to add a "Begin Computation" button to the
modal dialog. Then in the dialog's DialogCommand method, call the
code to do the computation. That code should call vApp::CheckEvents
periodically to keep the system working, but I think this will
give you the effect you want, more or less. While the call to the
computation would not return until it was done, the calls to
vApp::CheckEvents would allow a Cancel button to work within the
modal dialog, which would then need to call a routine in your
code to set a cancel flag, or something like that. You could also
set flags within the modal dialog that it is in the middle of a
computation and behave accordingly.

I haven't tried this, but I'm pretty sure this technique can
work. It does require a "Begin" button, however, which might not
work the way you want.

I also think that you could keep a state flag of your own, and
override all DialogCommand and WindowCommand methods to ignore
any messages while in compute mode. I think the message from the
V close box on X, or the system close box on Windows might go
around these, but then that might still be how you want it to
work - exit if the user says so.

-------------------------------------------------------------
**** PHILOSOPHY
-------------------------------------------------------------
**** V in the Computer Science Classroom
Q:
> Is V suitable for CS classes that use C++?

A:
We've used V for two UNM CS courses, a Senior level
software engineering class, and a Junior level
design and programming class.

I have been using V for my software engineering class, and it is
excellent for that. It lets the students get big projects done
with truly neat interfaces. This is the FIRST time I've been able
to teach software engineering and have projects that both use C++
_and_ have a nice user interface. I really don't want to use
Tcl/Tk for a real software engineering class.

We have also used V in the Junior level programming class. It is
when the students first tackle real programs using C++. UNM
switched to C++ just about two years ago, and is still
making some adjustments.  The students used V to build some
simple, but real programs that required some design. I didn't
teach the class, but as I recall, one project involved putting
a spinning wheel on the screen, and controlling position and
spin rate using various V controls.  The problems students
had with V involved the standard problems with programming
in general, how to really use classes, constructors, destructors,
etc., and general GUI issues. V itself was really never a
hindrance - just struggling students.

Personally, I really feel V is PERFECT for that level of class.
If you want to use a real programming language (all debates aside,
C++ is real compared to a scripting language), and would like
the students to be able to generate GUI programs, I really don't
know of any alternative to V in an academic environment where
freeware is important.

For the first time, students really were able to fairly easily
generate GUI programs with C++ code. They found this VERY
rewarding and fun. More so that with the old INPUT/OUTPUT
stuff that we were limited to before. And not only that, a
lot of students are getting their own Linux boxes now, and
that makes V even better for them.

I hate to sound like a salesman, but the results I've seen
here make me wish that CS departments all around the country
knew about V, and would consider using it.  There are a couple
of other freeware GUI frameworks (wxWindows and YACL), but neither
is as simple or clean as V. (You can even use V code for case
study, it is very clean.)  I really don't think there is
anything missing from V for student projects. And the manual
is good enough so as to not generate tons of V questions for
the instructor.  (I get literally ONLY 3 or 4 V questions per
semester from my software engineering class - they really
just ask project questions.)

Well, I've rambled, but I would like to encourage you to take
a serious look at V and consider it for your classes.

-------------------------------------------------------------

**** Why does V use static tables for menus?
Q:
> Why have you used static tables of structures to initialize Menu
> and Command panes ?
> 
> Doesn't object oriented programming include hiding of data structures?

A:
One can stick strictly to a paradigm, and end up with something
that is obscure and difficult to program with, or one can bend
the rules and end up with something far simpler and easier to use.

The ability to easily define menus, dialogs, command bars, and
status bars using structures (which are usually static, but
don't have to be) gives a very simple and easy way to define
these things. After looking at some other OO GUI frameworks,
I decided they were too hard to get started with, and that
you ended up with code that was too hard to maintain. Keeping
all the definitions for V control objects in a single declaration
is much simpler.

The declarations for menus and dialogs actually are replacements
for the resource definitions usually found in the native GUI
toolkits. For example, V does not use standard Windows .RC files
to define menus and dialogs. You will find many similarities
in the elements included in a V dialog CommandObject declaration
and a Windows .RC file.

Underneath it all, however, all the controls are implemented as
C++ objects, and the details of the implementation of each
control object for each platform are hidden. The definitions of
dialogs and menus are platform independent, and easy to define,
modify, and maintain.

-------------------------------------------------------------
**** Programming for Windows vs. Unix and X
Q:
> This last is kind of a shot in the dark, but.... I'm trying to do most
> of my development on Linux, but also engineer the code for Windows
> compatibility.  The portability section in the coding style guidelines
> appendix has some good information, but what I was wanting to know
> mostly was how the Windows programming environment differs from the
> Unix-type environment in terms of memory management, pointer usage,
> and the like.  Can you recommend a good book on programming in Windows
> to help ease me into this (eventual) port?  If it can explain the
> difference between 16-bit and 32-bit Windows (and the differences
> between Win32s, Win 95, and Win NT in particular) it would be even
> more helpful.  Also, I'm not exactly up on the MDI/SDI thing, either.
> 

A:
Windows comes in just two basic flavors, Windows 3.1, which has a
bunch of very ugly properties left over from the segmented
architecture of the Intel 8086, and the 32-bit varieties, which
includes Win32s, Win 95, and Win NT. Win 95 has some nice
dialog controls, but for now V is not using them. Other than
that, all these are really WIN32 platforms.

As a programmer, there is really only one major issue you have
to deal with. The Windows 3.1 platform is basically a 16-bit
platform, and thus limits data objects to a maximum size of
64K bytes. You can have a whole bunch of 64K objects, but
each object can be at most 64K. There are also some limits
(not hard to hit...) on the amount of static data allowed,
again tied to 64K. This one seems to vary from compiler to
compiler, but can be hit by defining a lot of big static
V Icons. I had some problems with the V Icon Editor, for
example.)

The bottom line on Windows 3.1 is that you have to use
what is called Large Model to compile V applications,
and think about the 64K limit for any single data object.
You can't assume that you can compare pointers for
objects allocated separately (but then you shouldn't
assume that anyway), so using pointers in 3.1 really
doesn't create additional problems.

The WIN32 platform solves all these problems by using
the linear addressing available on all Intel chips
since the 80386. The WIN32 API to the system is
almost compatible with the older 3.1 API, but there
are some major incompatibilities, and some of that
16-bit ugliness remains. But fortunately, V hides
all of that. For regular old C++ programming, use
'new' and pointers just as you would on a real computer
with a real operating system (like Linux or SunOS!).

I personally don't have much positive to say about
Microsoft (some of it stemming from personal experience
back when I was involved with my own PC software
company), so I've really avoided using Visual C++,
but V users have reported V will compile with it.
I like Borland C++ the best, but Watcom's C++ 10.6
isn't bad, and for one price you get 3.1, 95, NT,
and OS/2 support. If you are associated with an
academic institution, you can get Watcom for only
$100, a really great deal. For NT and 95, the
Cygnus port of gcc is getting pretty reasonable, too,
but it isn't quite native.

I've found the Charles Petzold books the most useful for
getting going, but I also think that Herbert Schildt's
books are pretty good, and would maybe be my first
choice today. There are a lot of BAD Windows books,
and books by either of these two authors are a pretty
safe bet.

-------------------------------------------------------------
**** V vs. wxWindows
Q:
> How would you compare V against wxWindows ?

A:
V and wxWindows are quite similar in their goals. Naturally,
I prefer V. WxWindows has been around a bit longer than V,
and has some development tools not yet available in V
(e.g., an App generator). WxWindows is less fixed in the
look and feel of the apps it generates. WxWindows uses
Motif and OpenLook implementation for X, while V uses
a customized version of the free Athena widgets, with
a Motif version in progress.

V, on the other hand, pretty much imposes a look and feel.
It turns out that this look and feel is the standard
Windows look and feel, as well as the Motif look and feel,
(even though the Motif port is not yet done). Thus, when
using the Xt Athena version, you end up with Windows/Motif
like apps. I think this is a good thing.

You can see a result of this approach in how V builds dialogs.
While wxWindows uses a generic window for both drawing canvases
and dialogs, V uses different objects for each. Thus, on
X, you get a different kind of shell widget used for dialogs
and canvases, while on Windows you get a real Windows dialog
box with its specialized look. Thus your apps will look more native.

The last I looked, V also had more controls for its dialogs.
Adding controls to dialogs and windows is done differently.
In wxWindows, you add each object via a line of code. V lets
you define whole dialogs and menus simply using a static
array. I think this latter approach is much easier to program.

The visual look of V is more polished. This shows especially
in the dialogs. The Windows version has a very nice 3D look
for all dialog components, and the shading and color choices
look much more like polished apps than the standard app colors
generated by wxWindows apps. The X version also uses nice shading,
and allows you to change the color design using an X resource file.

Finally, if you look at the source code, I'm confident you will
find the V code much more readable and well structured. The
wxWindows code seems much less polished, and really lacks comments.
This may be a matter of style - I am a strong believer in
the concept that it is almost impossible to over comment code.
I believe this leads to more maintainable code.

-------------------------------------------------------------
**** Using V for commercial applications
Q:
> I've read the GNU License, and I'm not sure if I can use
> V for commercial applications. What are the restrictions
> for using V for a commercial app?

A:
The short answer is yes, you can use V for commercial
applications. The following are the relevant sections
of the GNU LIBRARY GENERAL PUBLIC LICENSE contained
in the file COPYING.LIB:

<<<<< BEGIN EXCERPT of GNU License >>>>>>

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference
between a "work based on the library" and a "work that uses the
library".  The former contains code derived from the library,
while the latter only works together with the library.

[stuff deleted]

  5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being
compiled or linked with it, is called a "work that uses the
Library".  Such a work, in isolation, is not a derivative work of
the Library, and therefore falls outside the scope of this
License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library
(because it contains portions of the Library), rather than a
"work that uses the library".  The executable is therefore
covered by this License. Section 6 states terms for distribution
of such executables.

[stuff deleted]

  6. As an exception to the Sections above, you may also compile
or link a "work that uses the Library" with the Library to
produce a work containing portions of the Library, and distribute
that work under terms of your choice, provided that the terms
permit modification of the work for the customer's own use and
reverse engineering for debugging such modifications.

[NOTE: This language is much more restrictive than it may appear.
The reverse engineering is allowed ONLY for debugging
modifications to the library. There is nothing to imply that
allowing reverse engineering extends to your work, so your
protection remains intact.]
  You must give prominent notice with each copy of the work that
the Library is used in it and that the Library and its use are
covered by this License.  You must supply a copy of this
License.  If the work during execution displays copyright
notices, you must include the copyright notice for the Library
among them, as well as a reference directing the user to the copy
of this License.  Also, you must do one of these things:

[Several options for supplying access to the library, and object
code for using modified libraries.]

<<<< END EXCERPT >>>>

My interpretation of all this is that you can pretty much protect
your commercial software. You need to acknowledge that you are
using V, and provide access to V. This can easily be accomplished
by providing a link to the V Web site.

Possibly the most objectionable part requires that you allow
users to relink the work using a modified version of V. This
provision can be satisfied by providing access to the the object
code files only upon request. You are also allowed to charge for
that access. Between these, I don't think there is much real
impact on using V for a commercial package.

So, by my interpretation, you can comply with the GNU license by
doing the following:

1. Acknowledge the use of V, and supply a reference to the
   V Web site.

2. Supply a copy of the GNU LIBRARY GENERAL PUBLIC LICENSE.
   The license implies that the object code is available for
   relinking for an appropriate charge. I don't think you
   need to explicitly state this anywhere else. You can also
   make it clear that only the V library uses that GNU
   LIBRARY GENERAL PUBLIC LICENSE, and that your commercial
   software uses a different license.

3. Being prepared for the very unlikely event someone will
   actually want to pay for access to the object code to
   relink to a modified version of V.

-------------------------------------------------------------
**** PLATFORMS ****
-------------------------------------------------------------
**** WINDOWS.H and WINDOWSX.H files for Windows version
Q:
> I downloaded the V C++ GUI package for Microsoft Windows from
> your website and attempted  to compile and run the tutorial
> (TUTAPP.CPP), only to discover that it indirectly  required two
> files named "WINDOWS.H" and "WINDOWSX.H". I don't have either
> of these  files. Where can I get them?

WINDOWS.H and WINDOWSX.H are the files that define the interface
to the Windows API toolkit. All Windows apps require these files.
They are usually provided with your compiler.

-------------------------------------------------------------
**** Cygnus gcc-win32
Q:
> I'm going to try to use V with the 
> Cygnus WIN32 environment. The makefiles
> for that environment are not included in the
> V distribution. Are those makefiles available anywhere?

A:
As far as I last knew, V is included in the
Cygnus WIN32 distribution, at least as of b14.
The makefiles should be included in the distribution.

-------------------------------------------------------------
**** Missing files/libraries in X
Q:
> I'm trying to compile your V libraries on Linux and seem to be missing 
> some of the include files for X.  The only subdirectories I have beyond 
> include/X11 are Bitmaps and Pixmaps which aren't really include 
> directories.  For example, I'm missing the "Xaw" and "Xmu" directories 
> to name a few.  Could you direct me to where I could get the extra 
> include files that I require to build the libraries?
> 

A:
V assumes that X has been installed on your system in some place,
usually something like /usr/X11 or /usr/X11R6 and other related
spots. The standard X installation contains the X include files,
X libraries, and others. V also needs the Athena widget set, Xaw,
and other files. Some systems don't install these (especially
Motif only systems), although most do. Almost always, if your
system is running X, then the required files are probably there.

Other that this general information, it is beyond my capability
to provide more help about proper installation of X on your
system. Check with your system administrator for help on that.

-------------------------------------------------------------
**** OS/2 Version
Q:
> When will an OS/2 version be available?

A:
I don't know. There are a couple of volunteers working
on this right now (August, 1996). If they have any luck,
an OS/2 version might be available by 1997.

-------------------------------------------------------------
**** Mac Version
Q:
> When will an Mac version be available?

A:
I don't know. There is a volunteer working on this right now
(August, 1996), but he just got started . If has any luck, an
OS/2 version might be available later in 1997.

-------------------------------------------------------------
**** Windows 95 Version
Q:
> I just would like to know your estimated time of completing the
> version for Windows 95.
> 
A:
The WIN32 version is done, and works well on Windows 95. It still
uses the Win3.1 file dialogs. I hope to add native Win95 stuff,
but will probably wait until Win NT 4.0 is available. In the meantime,
you can generate WIN32 Apps, and they will be source code
compatible whenever native Win95 stuff is added.

-------------------------------------------------------------
**** MISC.
-------------------------------------------------------------
**** Using V from C
Q: > V GUI looks quite interesting. I wonder if there is a way to
   > use it from a C program?

A: V can be used from C, but you still need to use the basic C++
object oriented framework. Converting an existing C program can
often be difficult because they are often command driven rather
than event driven.

It is much easier to convert a C program that has its major
functionality isolated into routines that get called from the
command interface interpreter. The easiest path is to toss the
interface code and start with a V sample program. Define the
menus and toolbars you need, and then call the appropriate C code
from a 'case' in the 'WindowCommand' routine of the command
window. Given the simple definitions of menus and toolbars, using
this approach requires more cut and paste into the sample code
than complete understanding of C++.

Handling output from the C program may also be a bit difficult.
The V vTextCanvas class may be the easiest. Essentially, it works
just like a classic dumb terminal, like a DOS session from
Windows, or a tty window from X. It isn't a VT100 (say, that
sounds like an interesting project), but it has similar
functionality. Using it will still require minimal understanding
of C++.

In the end, however, learning C++ is really worth it. I've found
the main payback is much more maintainable and robust code. It is
far easier to modify a well-defined object than a piece of even a
good C module, and the modifications don't break the rest of the
system.

-------------------------------------------------------------
**** How can I learn C++?
Q:
> I was wondering if you could help me out. I have been trying to
> learn C++, and I would like to learn how to use V also. What
> can you do to help me?

Occasionally I get general help requests like this. As much
as I would like to be able to help you out, I really don't
have the time to devote to getting people up to speed on
C++ or GUIs in general.

I do have some strong opinions about C++ and object orientation.
I think OO is wonderful, and that C++ is a reasonable
OO language, if not perfect. It has the overwhelming
advantage of being the marketplace winner. One of the
main problems with C++ that I have found is that there
are no really outstanding C++ books available, either for
the new programmer, or for someone converting to C++.

The main problem I've found is that to use C++ in a reasonable
and effective fashion, you need to use its object-oriented
capabilities. Without really understanding objects, encapsulation,
inheritance, AND aggregation, it is hard to know what
constructors are really good for, why destructors are so
wonderful for managing dynamic objects, and the real significance
of shallow and deep object semantics.

So, given that, I can recommend the following books:

FIRST, get the object-orientation! While these books aren't
perfect, they are the ones I like best:

Object-Oriented Systems Design - An Integrated Approach,
Edward Yourdon, Yourdon Press, ISBN 0-13-636325-3.

Object-Oriented Analysis and Design, Second Edition, Grady Booch,
Benjamin/Cummings, ISBN 0-8053-5340-2.

The C++ Books are harder to pin down. I really don't like
any of them. But I probably most use:

C++ Primer, 2nd Edition, Stanly B. Lippman, Addison Wesley,
ISBN 0-201-54848-8.

Stroustrup's book is essential after you are proficient
with C++.

It turns out that GUIs are one of the most natural object-oriented
applications around, so they really do provide a great way
to get started on OO. The use of inheritance, messages, and
real objects makes then seem natural. I think V is a good
example OO GUI. In fact, V started out as a small demo
program for an OO/C++ book I'm trying to write. The V
demo has taken over, and my book is on the back burner...
-------------------------------------------------------------

