Greetings V Users:

This is still not a formal FAQ, but is the beginning of one.
I finally figured out I need to SAVE all the questions
I get and the replies I send. I just started doing that,
and will keep adding to this list. When it gets big enough,
I'll try to formalize it. So, far the topics covered include:

FAQ updated June 27, 1996
-------------------------------------------------------------
- About vAppWinInfo.
- About drawing bitmaps quickly
- About translation and scaling
- About color maps
- A discussion of V's object-oriented philosophy
- A discussion of dynamically changing list controls
- Text edit object
- About setting attributes of a newly created canvas
- Resizing dialogs
- Multiple redraws caused by dragging other windows
- A discussion of Windows issues for Unix programmers
- Keeping a file history on a menu
- A discussion on TextIn objects
- V vs. wxWindows
- Some tricks for controlling dialog control placement
- How to use a timer from a command window
- Picking objects (icons) in a command window canvas
- Using V with C programs

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

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

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

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);

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

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

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.

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

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

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

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

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

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
  }
-------------------------------------------------------------

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.

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

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

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

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

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.

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

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.

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

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

    // ....
   }

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

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.

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

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.

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