%***********************************************************************
%***********************************************************************
%***********************************************************************
\chapter {Drawing}

This chapter covers classes and utility functions needed to draw
text and graphics.

The classes and objects covered in this chapter include:

\begin{description}
	\item[Introduction to Drawing] Basic \V\ drawing model.
	\item[Fonts] Various screen fonts are available in \V\@.
	\item[vBrush] A brush for filling areas.
	\item[vCanvasPaneDC] The canvas pane drawing canvas.
	\item[vCanvasPane] A base class to build graphical and text canvas panes.
	\item[vBaseGLCanvasPane] A specialized class to support OpenGL.
	\item[vColor] A class for specifying colors.
	\item[vDC] A base class describing drawing canvas methods.
	\item[vMemoryDC] A memory drawing canvas.
	\item[vPen] A drawing pen.
	\item[vPrintDC] A printer drawing canvas.
	\item[vPrinter] A printer setup dialog.
	\item[vTextCanvasPane] A class for drawing text on a canvas. 
	\item[vTextEditor] A class for editing text.
	\item[vBaseGLCanvasPane] A class to support OpenGL.
\end{description}

%------------------------------------------------------------------------
\Class{Introduction to Drawing}
\index{drawing}

The basic \V\ model of drawing is a canvas. \V\ supports several kinds
of drawing canvases. The most obvious canvas is the screen drawing canvas.
This will often be the main or even only canvas you use. \V\ also
supports printing canvases. Each kind of canvas has identical drawing
methods, so you can write code to draw that is mostly independent of
which kind of canvas is being used.

There is also a specialized drawing canvas to support OpenGL. This
class differs somewhat from the other drawing canvases.
\index{OpenGL}

\subsection* {Drawing with the vDC Class}
\Indextt{vDC}

You draw to the various canvases using a \code{vDC} class, the
general \V\ Drawing Canvas Class (the OpenGL canvas does not use
the code{vDC} class). The \code{vDC} class for drawing to the
screen is \code{vCanvasPaneDC}. The class \code{vPrintDC} is the
platform independent class to draw to a printer. For X, \code{vPrintDC}
supports PostScript printing. The Windows version supports
standard Windows printers. (You can also use the PostScript DC
independently on Windows.) If you write your drawing code to use
a \code{vDC} pointer, you will be able to draw to several
canvases just by changing the value of the pointer.

Each \code{vDC} supports the methods described in the \code{vDC} section.
Because the \code{vCanvasPane} class is so central to most
applications, it duplicates
all the \code{vDC} methods so you can call them directly from your
\code{vCanvasPane} object. In fact, all the methods in \code{vCanvasPane}
are just calls to the corresponding \code{vDC} using the \code{vCanvasPaneDC}
of the canvas pane. You can get the \code{vCanvasPaneDC} pointer with
the \code{GetDC} method.

There are three kinds of drawing methods supported by \V\@. The simplest
methods draw lines of various widths and colors using the current
\code{vPen}. You change the color and width of the lines being drawn
by setting the current \code{vPen} with the \code{SetPen} method.

The second type of drawing includes filling the space surrounded
by a shape such as a polygon. The edges of the shape are drawn using
the current \code{vPen}. The filled area is drawn using the current
\code{vBrush}. You can set various attributes of the brush, and use
\code{SetBrush} to change how the shapes will be filled, as well as
changing the attributes of the \code{vPen} used to draw the surrounding
line. Both the pen and the brush can be transparent, allowing you to
draw unfilled outline shaped, or to fill a shape without an outline.

Finally, \V\ supports drawing of text on a canvas using various
\code{vFonts} and text attributes. The canvas pane will start out
using the default system font (\code{vfSystemDefault}). If you need
a different initial font, use \code{vFont::SetFontValues} to
select the font you want, then \code{vCanvasPane::SetFont} to set
the new font.

\subsection{Coordinates}

All \V\ drawing canvas classes use integer physical coordinates
appropriate to the canvas. All devices call the upper left corner
x,y coordinate of the drawing canvas 0,0. The x values increase
to the right, and y values increase down.

It it up to each application to provide appropriate mapping
from the coordinates used for the particular model being used
(often called the world coordinate system) to the physical
mapping used by each \V\ drawing canvas. Each drawing canvas
will have a physical limit for the maximum x and maximum y,
usually imposed by the particular canvas (a screen or a paper
size, for example). You can set a scale factor for each drawing
canvas which can be helpful for using different kinds of drawing
canvases. \V\ also supports setting an x,y translation. This will
allow you to more easily use the scroll bars and set margins
on printers. Your application can usually use the messages
received from the scroll bars to set the translation coordinates
to map your the canvas to a different drawing area. The system
will handle clipping.

However, the application is for the most part responsible
for determining all coordinate mapping -- translations of
a viewport of the drawing, determining the scaling for
various drawing canvases, and any mapping from the world
to the physical coordinates. The application will have to
map the mouse input accordingly, too.

%------------------------------------------------------------------------

\Class{Fonts}
\index{fonts}
\Indextt{vFont}

Various screen fonts are available in \V\@.

\subsection* {Synopsis}

\begin{description}
	\item [Class:] \code{vFont}
	\item [Header:] \code{<v/vfont.h>}
\end{description}

\subsection* {Description}

Fonts are difficult to make portable. \V\ has adopted a font
model that is somewhat portable, yet allows you to take advantage
of various fonts available on different platforms. In fact, it
is possible to write your programs to use the \code{vFontSelect}
dialog class, and pretty much ignore many of the details of
selecting fonts. The main characteristics of fonts your program
will have to deal with are the height and width of text displayed
on a canvas. These values are provided by 
\code{vDC::TextHeight} and \code{vDC::TextWidth}.

Fonts are associated with drawing canvases. For example, the
\code{vCanvasPane::SetFont} method is used to set the font used
by the canvas pane. The sizes of the actual fonts will probably
differ on different kinds of canvases. Specifically, your program
should not depend on getting the same \code{TextWidth} value
for screen and printer canvases for the same font.

The class \code{vFont} is used to define font objects, and the
characteristics of the font are set either by the class
constructor when the font is instantiated, or by using the  
\code{vFont :: SetFontValues} method. The utility class \code{vFontSelect}
can be used to interactively set font characteristics.  The
characteristics associated with a font are described in the
following sections. Remember, however, that \code{vFontSelect::FontSelect}
can be used to set these attributes.

\subsubsection*{Font Family}

Each font belongs to a font family. There are eight font families
defined by \V\@ with the \code{vFontID} attribute of the font object.
Font families typically correspond to some typeface name such
as \emph{Helvetica} or \emph{Times Roman}, but use more generic names.
There are three system fonts, \code{vfDefaultSystem}, \code{vfDefaultFixed},
and \code{vfDefaultVariable}. These default fonts are defined by
the specific platform. \code{vfDefaultSystem} will usually be a
fixed space font, and is often settable by the user. On X, for
example, the default system font can be changed by using a
\code{-fn fontname} switch when starting the application. The
\code{vfDefaultSystem} font will have fixed attributes, and will
not be changeable by the program. The \code{vfDefaultFixed}
(fixed spacing) and  \code{vfDefaultVariable} (variable spacing)
fonts are also system specified, but can usually have their
attributes, such as size and weight changed.

\V\ also supports five other font families. The \code{vfSerif} font
is a seriffed font such as \code{Times Roman}. The \code{vfSanSerif}
is a serifless font such as \code{Swiss} or \code{Lucidia}. Both
of these are variable spaced fonts. The \code{vfFixed} is a fixed
space font, often called \code{Courier} on the host platform.
The \code{vfDecorative} font usually contains symbols or other drawing
characters. It is not very portable across platforms. Finally,
\V\ supports a font family called \code{vfOther}. This is used when
the system supports other fonts that are selectable via the
\code{vFontSelect} dialog class. Windows supports a wide variety of fonts,
while X does not support any additional fonts.

\subsubsection*{Font Style}

\V\ supports two kinds of font styles: \code{vfNormal} for normal
fonts, and \code{vfItalic} for italic fonts.

\subsubsection*{Font Weight}

\V\ supports two kinds of font weights: \code{vfNormal} for
normal weight fonts, and \code{vfBold} for boldface fonts.

\subsubsection*{Point Size}

\V\ supports a wide range of point size, usually ranging from 8 point
to 40 or 72 point fonts. Not all point sizes are supported on each
platform. How each point size maps to space on the screen or page
also vary from platform to platform.

\subsubsection*{Underlining}

You can also specify that a font is underlined. Currently, underlining
does not work for X screens.

\subsection* {Methods}

\Meth{vFont(vFontID fam = vfDefaultFixed, int size = 10,
vFontID sty = vfNormal, vFontID wt = vfNormal, int und = 0)}
\Indextt{vFont}

The constructor is used to declare a font with the specified
family, size, style, weight, and underline.

\Meth{vFontID GetFamily()}
\Indextt{GetFamily}

Returns the family of the font object.

\Meth{int GetPointSize()}
\Indextt{GetPointSize}

Returns the point size of the font object.

\Meth{vFontID GetStyle()}
\Indextt{GetStyle}

Returns the style of the font object.

\Meth{vFontID GetWeight()}
\Indextt{GetWeight}

Returns the weight of the font object.

\Meth{int GetUnderlined()}
\Indextt{GetUnderlined}

Returns the underline setting of the font object.

\Meth{void SetFontValues(vFontID fam = vfDefaultFixed, int size =
10, vFontID sty = vfNormal, vFontID wt = vfNormal, int und = 0)}
\Indextt{SetFontValues}

Changes the attributes of the font object. For example, the font
selection dialog uses this method to change the font attributes.

%------------------------------------------------------------------------

\Class{vBrush}
\Indextt{vBrush}\index{brush}

A class to specify the brush used to fill shapes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vbrush.h>}
	\item [Class name:] vBrush
\end{description}

\subsection* {Description}

Brushes are used to fill shapes. Brushes have
two attributes, including color and style.

\subsection* {Methods}

\Meth{vBrush(unsigned int r = 0, unsigned int g = 0, unsigned
int b = 0, int style = vSolid)}
\Indextt{vBrush}

The brush constructor allows you to set the initial color and
style of the brush. The default constructs a solid black brush.

\Meth{int operator == , !=}

You can use the operators \code{==} and \code{!=} for comparisons.

\Meth{vColor GetColor()}
\Indextt{GetColor}

This method returns the current color of the brush as a \code{vColor} object.

\Meth{int GetFillMode()}
\Indextt{GetFillMode}

This method returns the fill mode of the brush (either \code{vAlternate}
or \code{vWinding}).

\Meth{int GetStyle()}
\Indextt{GetStyle}

This method returns the current style of the brush.

\Meth{void SetColor(vColor\& c)}
\Indextt{SetColor}
\index{color!brush}

You can use this method to set the brush color by passing
in a \code{vColor} object.

\Meth{int SetFillMode(int fillMode)}
\Indextt{SetFillMode}

This method sets the fill mode of the brush.
The fillMode parameter specifies one of two alternative filling
algorithms, \code{vAlternate} or \code{vWinding}. These algorithms correspond
to the equivalent algorithms on the native platforms.

\Meth{void SetStyle(int style)}
\Indextt{SetStyle}

This method is used to set the style of the brush. Brush styles
include:

\begin{description}
	\item [vSolid] The brush fills with a solid color.
	\item [vTransparent] The brush is transparent, which allows
you to draw unfilled shapes.
	\item [vHorizontalHatch] The brush fills with a horizontal hatch pattern
in the current color.
	\item [vVerticleHatch] The brush fills with a vertical hatch pattern.
	\item [vLeftDiagonalHatch] The brush fills with a left leaning
diagonal hatch pattern.
	\item [vRightDiagonalHatch] The brush fills with a right
leaning diagonal hatch pattern.
	\item [vCrossHatch] The brush fills with a vertical and horizontal cross hatch
pattern.
	\item [vDiagonalCrossHatch] The brush fills with a diagonal
cross hatch pattern.
\end{description}

%------------------------------------------------------------------------

\Class{vCanvasPaneDC}
\Indextt{vCanvasPaneDC}

The drawing canvas class for CanvasPanes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vcpdc.h>}
	\item [Class name:] vCanvasPaneDC
 	\item [Hierarchy:] vDC \rta vCanvasPaneDC
\end{description}

\subsection* {Description}

This class is normally automatically used by the \code{vCanvasPane}
class. It provides the actual implementation of the screen drawing
canvas class. 

%------------------------------------------------------------------------

\Class{vCanvasPane}
\Indextt{vCanvasPane}

A base class to build graphical and text canvas panes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vcanvas.h>}
	\item [Class name:] vCanvasPane
 	\item [Hierarchy:] vPane \rta vCanvasPane
\end{description}

\subsection* {Description}

This is the base drawing class. You use it to build more complicated
drawing canvases, either for graphical drawing or text drawing.
The \code{vCanvasPane} class has all the basic methods needed to
interact with the drawing canvas. It does not, however, know
how to handle repainting the screen on \code{Redraw} or \code{Resize}
events. It provides utility methods for drawing on the canvas,
and several other methods that are normally overridden by your
application.

See the section \code{vPane} for a general description of panes.

\subsection* {Utility Methods}

The following methods provide useful service without modification. Sometimes
you will want to override some of these, but you will then usually
call these methods from your derived class.

%............................................................
\Meth{Drawing}
\index{drawing}

The \code{vCanvasPane} normally creates a \code{vCanvasPaneDC} to
use for drawing, and class provides direct support by including
direct calls for the drawing methods described in the \code{vDC}
section. If your drawing will only be to the screen, then you
can use the methods of the \code{vCanvasPane} class directly.
Each of these methods is really an inline function that expands
to \code{\_cpDC->DrawWhatever()}.

If your drawing code might want to draw to both a screen and
a printer, you might want to use a parameter to the appropriate
drawing canvas. You can get the \code{vDC} used by the \code{vCanvasPane}
by calling \code{GetDC()}.

%............................................................
\Meth{virtual void CreateDC(void)}
\Indextt{CreateDC}

This method is called when the \code{vCanvasPane} is initialized.
The default is to create a drawing canvas using \code{\_cpDC = new
vCanvasPaneDC(this);}. If you want to derive a different canvas
pane class from \code{vCanvasPane} perhaps using a more
sophisticated drawing canvas derived from the \code{vCanvasPaneDC}
class, you can override the \code{CreateDC} method and set the
protected \code{vDC* \_cpDC} pointer to an instance of your new
drawing canvas (e.g., \code{\_cpDC = new myCanvasPaneDC(this)}
instead.

%............................................................
\Meth{vDC* GetDC()}
\Indextt{GetDC}

Returns a pointer to the \code{vDC} of the current drawing canvas. The
\code{vDC} can be used for most of the drawing methods to achieve
drawing canvas independence. If your code draws via a \code{vDC} pointer,
then the same code can draw to the screen canvas or the printer canvas
depending on what the \code{vDC} points to.

%............................................................
\Meth{VCursor GetCursor()}
\Indextt{GetCursor}

Returns the id of the current cursor being used in the canvas.
See \code{SetCursor}.

%............................................................
\Meth{virtual int GetHeight()}
\Indextt{GetHeight}

Returns the height of the current drawing canvas in pixels.

%............................................................
\Meth{virtual int GetHScroll(int\& Shown, int\& Top)}
\Indextt{GetHScroll}

Get the status of the Horizontal Scroll bar. Returns 1 if the
scroll bar is displayed, 0 if not. Returns in \code{Shown} and
\code{Top} the current values of the scroll bar. See \code{SetVScroll}
for a description of the meanings of parameters.

%............................................................
\Meth{virtual int GetVScroll(int\& Shown, int\& Top)}
\Indextt{GetVScroll}

Get the status of the Vertical Scroll bar. See
\code{GetHScroll} for details.

%............................................................
\Meth{virtual int GetWidth()}
\Indextt{GetWidth}

Returns the width of the current drawing canvas in pixels.
This is either the initial size of the window, or the size
after the user has resized the window.

%............................................................
\Meth{void SetCursor(VCursor id)}
\Indextt{SetCursor}

This method sets the cursor displayed while the mouse in
in the current canvas area. The default cursor is the
standard arrow cursor used on most host platforms. You
can change the cursor displayed within the canvas area
only by calling this method.

The cursors currently supported include:

\begin{description}

\item[VC\_Arrow] The standard arrow cursor.
\item[VC\_CenterArrow] An upward point arrow.
\item[VC\_CrossHair] A cross hair cursor.
\item[VC\_EWArrows] Double ended horizontal arrows (EastWest).
\item[VC\_Hand] A hand with a pointing finger (NOT ON WINDOWS).
\item[VC\_IBar] An I bar cursor.
\item[VC\_Icon] A cursor representing an icon.
\item[VC\_NSArrows] Double ended vertical arrows (NorthSouth).
\item[VC\_Pencil] A pencil (NOT ON WINDOWS).
\item[VC\_Question] A question mark cursor (NOT ON WINDOWS).
\item[VC\_Sizer] The cursor used for sizing windows.
\item[VC\_Wait] A cursor that symbolizes waiting, usually an hour glass.
\item[VC\_X] An X shaped cursor (NOT ON WINDOWS).
\end{description}

%............................................................
\Meth{void SetWidthHeight(int width, int height)}
\Indextt{SetWidthHeight}

This will set the size of the drawing canvas to \code{height}
and \code{width} in pixels. It will also cause a \code{Resize}
event message to be sent to the window.

%............................................................
\Meth{virtual void SetHScroll(int Shown, int Top)}
\Indextt{SetHScroll}

Set the horizontal scroll bar. See \code{SetVScroll} for
a description of the parameters.

%............................................................
\Meth{virtual void SetVScroll(int Shown, int Top)}
\Indextt{SetVScroll}\index{scroll bars}

Set the vertical scroll bar. The \code{Shown} parameter
is a value from 0 to 100, and represents the percent
of the scroll bar shows of the view in the canvas. For
example, the canvas might be displaying text from a file.
If the file was 100 lines long, and the window could show
20 lines, then the value of \code{Shown} would be 20,
meaning that the canvas is showing 20 percent of the file.
As the size of the data viewed in the canvas changes, your
program should change the scroll bar to corresponding values.

The \code{Top} parameter represents where the top of
the scroll indicator should be placed.  For example,
if the first line displayed in the canvas of a 100 line file
was line 40, then  \code{Top} should be 40, representing
40 percent.

This model of a scroll bar can be mapped to all the underlying
windowing systems supported by \V, but the visual appearance
of the scroll bar will vary.

%............................................................
\Meth{virtual void ShowHScroll(int OnOrOff)}
\Indextt{ShowHScroll}
\Meth{virtual void ShowVScroll(int OnOrOff)}
\Indextt{ShowVScroll}\index{scroll bars}

When a canvas is first displayed, it will begin with both
horizontal and scroll bars not shown by default. \code{ShowHScroll}
and \code{ShowVScroll} can be used to selectively turn on and off
the canvas scroll bars. When a scroll bar is turned off or on, the size
of the canvas may changes, so you should also call \code{Resize} after
you have set the scroll bars.

You must not call either of these methods until the canvas has
actually been instantiated on the screen. This means if your
application needs to start with scroll bars, you should have
the calls to \code{ShowVScroll} and \code{ShowHScroll} in
the code of your \code{vCmdWindow} class constructor
(or other initialization code) \emph{after} calling
\code{vWindow::ShowWindow} in your class constructor.

\subsection* {Methods to Override} %------------------------

%............................................................
\Meth{virtual void FontChanged(int vf)}
\Indextt{FontChanged}

Called when the font is changed. This usually means your
application needs to resize the window and recalculate
the number of rows and columns of text that can be displayed.

%............................................................
\Meth{virtual void HPage(int Shown, int Top)}
\Indextt{HPage}

When the user moves the horizontal scroll bar, it generates an
\code{HPage} event. It is up to your program to intercept (override)
this method, and provide proper interpretation. This event usually
is used for large movements. The meaning of \code{Shown} and
\code{Top} represent the state of the scroll bar as set by
the user.  It is then up to your program to display the
correct portion of the data shown in the canvas to correspond
to these values.  Your program uses \code{SetHScroll} to
set appropriate values, and they are explained there.
The \code{Shown} value supplied here
will correspond to the value you program set for the scroll bar.
The \code{Top} value should indicate the meaningful change as input
by the user.

%............................................................
\Meth{virtual void HScroll(int step)}
\Indextt{HScroll}

This method is called when the user enters a single step command
to the scroll bar. The value of \code{step} will be positive for right or
negative for left scroll.  These scrolls
are usually interpreted as discreet steps - either a line or
screenful at a time. It is up to your application to give
an appropriate interpretation.

%............................................................
\Meth{virtual void MouseDown(int x, int y, int button)}
\Indextt{MouseDown}

This is called when the user clicks a button on the mouse. The
\code{x} and \code{y} indicates the position of the mouse in the
canvas when the button was clicked. Mouse events in vCanvasPane
are no-ops, and your subclass of \code{vCanvasPane} will need to
handle proper interpretation of mouse clicks.

Sorry, but thanks to the Macintosh, handling of buttons is a bit
nonportable. The \code{button} parameter will have a value of 1,
2, or 3. On X based systems, 1 is the left button, 2 is the
middle button, and 3 is the right button. On Windows, 1 is the
left button, and 3 is the right button. Thus, applications using
the left and right buttons are portable from X to Windows. The
single Macintosh button will return a value of 1. 

If you intend your applications to port to all three platforms,
you will have to account for the single Macintosh button. If you
ignore X's middle button, then your applications can be directly
portable from X to Windows.

%............................................................
\Meth{virtual void MouseMotion(int x, int y)}
\Indextt{MouseMotion}

This is called when the mouse moves while a button is \emph{not}
pressed, and gives the current \code{x} and \code{y} of the
mouse. Most applications will ignore this information.

%............................................................
\Meth{virtual void MouseMove(int x, int y, int button)}
\Indextt{MouseMove}

This is called when the mouse moves while a button is pressed,
and gives the new \code{x}, \code{y}, and \code{button} of the
mouse. Mouse events in vCanvasPane are no-ops, and your subclass
needs to interpret them.
Note that scaling applies to output only. The mouse
events will provide unscaled coordinates, and it is up
to your code to scale mouse coordinates appropriately.
Mouse coordinate \emph{do} have the translation added.

%............................................................
\Meth{virtual void MouseUp(int x, int y, int button)}
\Indextt{MouseUp}

This is called when the user releases the mouse button, and
gives the final location of the mouse.
Mouse events in vCanvasPane are no-ops, and your subclass
needs to interpret them.

%............................................................
\Meth{virtual void Redraw(int x, int y, int width, int height)}
\Indextt{Redraw}

\code{Redraw} is called when the canvas needs to be redrawn.
The first redraw is generated when the canvas is first created.
Other redraws are generated when the canvas is covered or uncovered
by another window, and means the contents of the canvas must
be repainted.  The \code{vCanvasPane} does not know how to repaint
the contents of the canvas, so you must override this method to
be able to keep the canvas painted.

The parameters of \code{Redraw} represent the rectangular area
that needs to be repainted. This areas is not always the whole
canvas, and it is possible that many \code{Redraw} events will
be generated in a row as the user drags a covering window off
the canvas.

The default \code{Redraw} in \code{vCanvasPane} is a
no-op, and your subclass needs to override \code{Redraw}.

%............................................................
\Meth{virtual void Resize(int newW, int newH)}
\Indextt{Resize}

A \code{Resize} event is generated when the user changes the
size of the canvas using the resize window command provided
by the host windowing system.

The default \code{Resize} in \code{vBaseGLCanvasPane} is a
no-op, and your subclass needs to override \code{Redraw}.

%............................................................
\Meth{virtual void VPage(int Shown, int Top)}
\Indextt{VPage}

See \code{HPage}.

%............................................................
\Meth{virtual void VScroll(int step)}
\Indextt{VScroll}

This method is called when the user enters a single step command
to the vertical scroll bar. The value of \code{step} will be
positive for down or negative for up scroll.  These scrolls are
usually interpreted as discreet steps - either a line or
screenful at a time. It is up to your application to give an
appropriate interpretation.

\subsection* {See Also}

vTextCanvasPane

%------------------------------------------------------------------------
\Class{vTextEditor}
\Indextt{vTextEditor}\index{Text Editor}

A complete text editing canvas pane.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vtexted.h>}
	\item [Class name:] vTextEditor
 	\item [Hierarchy:] vCanvasPane \rta vTextCanvasPane \rta vTextEditor
\end{description}

\subsection* {Description}

This class is a completely functional line oriented text editor.
It can edit any file with lines less than 300 characters wide that
use a linefeed, carriage return, or combination of those to mark
the end of each line.

While you need to create your own class derived from \code{vTextEditor},
your class can be very minimal. You will need to provide some
service methods for the parent \code{vCmdWindow}, such as methods
to open, read, save, and close files. Other than actually working
with the real text source and providing that source to \code{vTextEditor},
you can get a fully functional text editor with no additional work.

However, \code{vTextEditor} has been designed to allow you to extend
and add functionality to the editor if you need to. The \code{vTextEditor}
also sends messages that will allow you to place various status
messages on a status bar if you wish. The hard stuff is done for you.
You don't need to worry about mouse movements, scroll bars or scroll
messages, updating the screen, handling keystrokes, or anything else
associated with actual editing. The \code{vTextEditor} class takes
care of all those details, and provides a standard editing interface.

The following steps are required to use \code{vTextEditor}. First,
you create an instance of your derived class from your \code{vCmdWindow}
class, something like this:

\footnotesize
\begin{verbatim}
   ...

   // The Text Editor Canvas
    vedCanvas = new vedTextEditor(this);
    AddPane(vedCanvas);
   ...

   // Show Window

    ShowWindow();
    vedCanvas->ShowVScroll(1);  // Show Vert Scroll for vTextEditor

    ...
\end{verbatim}
\normalfont\normalsize

Your derived \code{vTextEditor} class should provide the methods
needed for opening and reading the text file you want to edit.
(Actually, you can edit any text source you wish.) \code{VTextEditor}
doesn't actually read or write any text itself. It maintains an
internal line buffer. (The default version of the internal buffer
is essentially limited by the amount of memory your system can
provide. The buffer methods can be overridden to provide totally
unlimited file size, if you wish.) The idea is to have your
application control where the text comes from, and then
add it a line at a time to the \code{vTextEditor} buffer.
You retrieve the text a line at a time when you want to save
the edited text. Thus, your if your code is working with
disk files, it can read the text a line at a time, and let
\code{vTextEditor} worry about the buffering.

The following code shows how to add the contents of a text file
to the \code{vTextEditor} buffer, and display it in the canvas
for the first time. Calls to \code{vTextEditor} methods are
marked with **.

\footnotesize
\begin{verbatim}
//===================>>> vedTextEditor::ReadFile <<<====================
  int vedTextEditor::ReadFile(char* name)
  {
    const int maxBuff = 300;    // Line length
    char buff[maxBuff];

    if (!name || !*name)
        return 0;
    ifstream inFile(name);      // Open the file

    if (!inFile)
        return 0;               // file not there

    resetBuff();                // ** Tell vTextEditor to init buffer

    while (inFile.getline(buff,maxBuff))  // read file
      {
        if (!addLine(buff))     // ** Add the line to the buffer
          {
            ERROR_MESSAGE("File too big -- only partially read.");
            break;
          }
      }
    inFile.close();             // Close the file
    displayBuff();              // ** Now, display the buffer
    return 1;
  }
\end{verbatim}
\normalfont\normalsize

To load text into the editor buffer,
you first call \code{resetBuff} to initialize the
buffer, then add a line at a time with calls to \code{addLine},
and finally display the text by calling \code{displayBuff}.

When your are editing (e.g., the user enters a Close command),
you retrieve the text from the \code{vTextEditor} buffer
with calls to \code{getLine}.

Then, to use the editor, you pass keystrokes from the
\code{KeyIn} method of your \code{vCmdWindow} to the \code{EditKeyIn}
method of the \code{vTextEditor}. \code{EditKeyIn} interprets
the conventional meanings of the arrow keys, etc., and lets
you edit the text in the buffer. You will also probably implement
other commands, such as Find, by using the \code{EditCommand}
method.

\code{VTextEditor} also calls several methods to notify of
text state changes, such as current line, insert or overtype,
etc. You can receive these messages by overriding the default
methods, and display appropriate information on a status bar.

While \code{vTextEditor} is very complete, there are some
things missing. The major hole is cut and paste support. This
will be added when cut and paste support is added to \V. There
is also no real undo support. Maybe someday.


\subsection* {Constructor} %------------------------------------

\Meth{vTextEditor(vBaseWindow* parent)}
\Indextt{vTextEditor!constructor}

The \code{vTextEditor} constructor requires that you specify
the parent \code{vCmdWindow}. Since you usually create the text editor object
in your \code{vCmdWindow} object, this is easy. You will probably need
to cast the \code{this} to a \code{vBaseWindow*}.

\subsection* {Utility Methods} %------------------------

\Meth{resetBuff()}
\Indextt{vTextEditor!resetBuff}

Before you load new text into the buffer, you must first
call this method. It initializes the internal state of
the text buffer.

\Meth{virtual int addLine(char* line)}
\Indextt{vTextEditor!addLine}

This method is called repeatedly to add lines to the
text buffer. The default method is limited by the amount
of memory available on the system, and this method
return 0 when it runs out of memory.

Note that the entire text buffer package can be overridden
if you need to provide unlimited file size handling. You
should examine the source code for \code{vTextEditor} to
determine the specifications of the methods you'd need
to override.

\Meth{virtual void displayBuff()}
\Indextt{vTextEditor!displayBuff}

After you have added the complete file, call \code{displayBuff}
to display the text in the window.

\Meth{virtual int getLine(char* line, int maxChars, long
lineNum)}
\Meth{virtual int getFirstLine(char* line, int maxChars)}
\Indextt{vTextEditor!getFirstLine}
\Meth{virtual int getNextLine(char* line, int maxChars)}
\Indextt{vTextEditor!getNextLine}

These are used to retrieve the edited text from the buffer.
You can use \code{getFirstLine} with \code{getNextLine} for
easy sequential retrieval, or \code{getLine} for specific
lines. These methods return -1 when all lines have been
recovered.

\Meth{virtual int EditCommand(int id, long val)}
\Indextt{vTextEditor!EditCommand}

This method provides a complete interface to the functions
provided by \code{vTextEditor}. While the basic
editing functions are also handled by \code{EditKeyIn},
\code{EditCommand} gives access to functions that typically
are either usually invoked from a menu command (such as
Find), or don't have a standard mapping to a functions
key (such as lineGoto). If you want the functionality of
these commands in your application, you will have to
provide an appropriate menu or command pane item to
support them.

Each function supported by \code{vTextEditor} has an
associated id (symbolically defined in \code{v/vtexted.h}), each
beginning with \code{ed}. Many of
the functions also take an associated value. Many editors
allow a repetition count to be specified with many commands.
For example, it is sometimes useful to be able to specify
a command to move right some specific number of characters.
The \code{val} parameter can be used to specify a value
as desired. The only function that really need a value
other than 1 (or -1 in the case of directional movement
commands) is \code{edLineGoto}.

\code{EditCommand} returns 1 if the command was executed
successfully, 0 if the command was recognized, but not
successful (the find fails, for example), and -1 if
the command was not recognized as valid.

At the time this manual was written, the following commands
are supported. Because \code{vTextEditor} is evolving,
it is likely more commands will be added. Check the
\code{v/vtexted.h} file for specification of new editor
commands. In the following descriptions, the note
``no val'' means that the \code{val} parameter is not
used. A notation of ``+/-'' means the sign of \code{val}
indicates direction.

\begin{description}
\item[edBalMatch] find matching paren (if val > 1, up to val
lines away, otherwise within a reasonable range)
\item[edBufferBottom] move to bottom of file (no val)
\item[edCharDelete] delete +/- val chars
\item[edCharFoldCase] swap case of +/- val letters
\item[edCharInsert] insert char val
\item[edCharRight] move +/- val chars right
\item[edFind] invoke TextEd's find dialog (no val)
\item[edFindNext] find next occurrence of prev (no val)
\item[edLineBeginning] move to line beginning (no val)
\item[edLineDown] move down +/- val lines in column
\item[edLineDownBeg] move down +/- val lines
\item[edLineDelete] delete +/- val lines
\item[edLineDeleteFront] delete to beginning of line (no val)
\item[edLineDeleteToEnd] delete to end of line (no val)
\item[edLineEnd] move to end of line (no val)
\item[edLineGoto] move cursor to line val
\item[edLineOpen] open val new blank lines
\item[edScrollDown] scroll +/- val lines without changing cursor
\item[edVerify] force repaint of screen (no val)
\item[edWordRight] move cursor +/- val words right

\end{description}

For a basic editor, the simplest way to use \code{EditCommand}
is to use the \code{ed*} id's to define the associated menu
items and controls, and then call \code{EditCommand} as the
default case of the \code{switch} in the \code{WindowCommand}
method of your \code{vCmdWindow}. Thus, you might have
code that looks like this:

\footnotesize
\begin{verbatim}
   ...
  static vMenu EditMenu[] = {
  ...
    {"Find", edFind, isSens,notChk,noKeyLbl,noKey,noSub},
    {"Find Next", edFindNext, isSens,notChk,noKeyLbl,noKey,noSub},
    {"Find Matching Paren", edBalMatch, isSens,notChk,
      noKeyLbl,noKey,noSub},
  ...
  };

   ...

//===========>>> vedCmdWindow::WindowCommand <<<====================
 void vedCmdWindow::WindowCommand(ItemVal id, ItemVal val,
      CmdType cType)
 {
   switch (id)
    {
     ...

      default:  // route unhandled commands through editor
       {
         if (vedCanvas->EditCommand(id, 1) < 0)
            vCmdWindow::WindowCommand(id, val, cType);
        break;
       }

    }
   ...
 }

//====================>>> vedCmdWindow::KeyIn <<<====================
  void vedCmdWindow::KeyIn(vKey keysym, unsigned int shift)
  {
    if (vedCanvas->EditKeyIn(keysym, shift) < 0)
        vCmdWindow::KeyIn(keysym, shift);
  }
\end{verbatim}
\normalfont\normalsize

\Meth{virtual int EditKeyIn(vKey key, unsigned int shift)}
\Indextt{vTextEditor!EditKeyIn}

This method is usually called from the \code{KeyIn} method
of your derived \code{vCmdWindow} class. See the above code
example. 

The default implementation of \code{EditKeyIn} handles
most of the standard keys, such as
the arrow keys, the page keys, backspace, home, delete,
insert, and end keys. It will also insert regular
character keys into the text. It ignores function keys
and non-printing control key values except tab and newline.

You can override this method to provide your own look and feel
to the editor.

\Meth{edState GetEdState()}
\Indextt{vTextEditor!GetEdState}
\Meth{void SetEdState()}
\Indextt{vTextEditor!SetEdState}

\code{VTextEditor} maintains a state structure with relevant state
information associated with various operating options of \code{vTextEditor}. It is
defined in \code{v/vtexted.h}, and has the following fields:

\footnotesize
\begin{verbatim}
    typedef struct edState
      {
        long changes,           // count of changes
             cmdCount;          // how many times to repeat command
        int
            findAtBeginning,    // leave find at beginning of pattern
            fixed_scroll,       // flag if using fixed scroll
            ins_mode,           // true if insert mode
            counter,            // counter for + insert
            echof,              // whether or not to echo action
            tabspc,             // tab spacing
            wraplm;             // right limit
      } edState;
\end{verbatim}
\normalfont\normalsize

You can query and set the state with \code{GetEdState} and
\code{SetEdState}.

\Meth{long GetLines()}
\Indextt{vTextEditor!GetLines}

Returns the number of lines in the current buffer.

\subsection* {Methods to Override} %------------------------

\Meth{virtual void ChangeLoc(long line, int col)}
\Indextt{vTextEditor!ChangeLoc}

This method is called by \code{vTextEditor} whenever the current line
or current column is changed. This information could be displayed
on a status bar, for example.

\Meth{virtual void ChangeInsMode(int IsInsMode)}
\Indextt{vTextEditor!ChangeInsMode}

This method is called by \code{vTextEditor} whenever the
insert mode is changed. If \code{IsInsMode} is true, then
the editor is in insert mode. Otherwise, it is in overtype
mode. The editor starts in insert mode. This information could be displayed
on a status bar, for example.

\Meth{virtual void StatusMessage(char* Msg)}
\Indextt{vTextEditor!StatusMessage}

The editor will call this message with a non-critical message
such as ``Pattern Not Found'' for certain operations.
This information could be displayed on a status bar, for example.

\Meth{virtual void ErrorMessage(char* Msg)}
\Indextt{vTextEditor!ErrorMessage}

The editor will call this message with a critical error message
such as ``Bad parameter value'' for certain operations.
This information could be displayed in a warning dialog, for example.

\subsection* {See Also} %---------------------------------------

vTextCanvasPane
%------------------------------------------------------------------------

\Class{vBaseGLCanvasPane}
\Indextt{vBaseGLCanvasPane}\index{OpenGL}

A specialized base class to support OpenGL graphics.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vbglcnv.h>}
	\item [Class name:] vBaseGLCanvasPane
 	\item [Hierarchy:] vPane \rta vBaseGLCanvasPane
\end{description}

\subsection* {Description}

This is a specialized class to provide very basic support
for the OpenGL graphics package. Unlike other \V\ canvas
panes, this class does not use a \code{vDC} class. Instead,
it has a few features designed to support OpenGL.

This is a basic class. It does not provide many convenience
methods to support OpenGL at a high level, but it does hide
all the messy details of interfacing with the host GUI
environment, and provides the first really easy way to
generate sophisticated interfaces for OpenGL applications.
A more sophisticated class
called \code{vGLCanvasPane} that will provide a number
of convenience operations is under development, but the
base class is still very useful.

By following a standard convention to structure V/OpenGL
code, it is relatively easy to generate applications.
The details of this convention are explained in the tutorial
section of this description.

See the section \code{vPane} for a general description of panes.

\subsection* {Constructor} %------------------------------------
\Meth{vBaseGLCanvasPane(unsigned int vGLmode)}
\Indextt{vBaseGLCanvasPane()}

The \code{vBaseGLCanvasPane} constructor allows you to specify
certain attributes of the visual used by OpenGL. The options,
which can be ORed together, include:

\begin{description}

\item[vGL\_Default] Use the default visual, which includes
\code{vGL\_RGB} and \code{vGL\_DoubleBuffer}. \V\ will
use this default if you don't provide a value to the constructor.

\item[vGL\_RGB] This is the standard RGBA mode used by
most OpenGL programs. The size of the RED, GREEN, and
BLUE planes are maximized according to the capabilities
of the host machine. An ALPHA plane is not included
unless the \code{vGL\_Alpha} property is also specified.

\item[vGL\_Alpha] Used to include an APLHA plane. Not all
machines support ALPHA planes.

\item[vGL\_Indexed] Use indexed rather than RGB mode. \V\
will attempt to maximize the usefulness of the palette.
You should not specify both RGB and Indexed.

\item[vGL\_DoubleBuffer] Use Double buffering if available.
Single buffering is assumed if \code{vGL\_DoubleBuffer} is not
specified.

\item[vGL\_Stereo] Use a Stereo buffer if available.

\item[vGL\_Stencil] Use Stencil mode if available.

\item[vGL\_Accum] Use accumulation buffers if available.

\item[vGL\_Depth] Use Depth mode if available.

\end{description}

Not all of these attributes are available on all OpenGL implementations,
and \V\ will attempt to get a reasonable visual based on your
specifications. For now, the \code{vGL\_Default} mode works well
for many OpenGL applications.

\V\ supports only one visual per application, and the first
\code{vBaseGLCanvasPane} created determines the attributes of
the visual used.

\subsection* {Utility Methods} %-------------------------------

The following methods provide useful service without modification. Sometimes
you will want to override some of these, but you will then usually
call these methods from your derived class. Most of these methods
are the equivalent of the normal \V\ \code{vCanvasPane} class.

%............................................................
\Meth{VCursor GetCursor()}
\Indextt{GetCursor}

Returns the id of the current cursor being used in the canvas.
See \code{SetCursor}.

%............................................................
\Meth{virtual int GetHeight()}
\Indextt{GetHeight}

Returns the height of the current drawing canvas in pixels.

%............................................................
\Meth{virtual int GetHScroll(int\& Shown, int\& Top)}
\Indextt{GetHScroll}

Get the status of the Horizontal Scroll bar. Returns 1 if the
scroll bar is displayed, 0 if not. Returns in \code{Shown} and
\code{Top} the current values of the scroll bar. See \code{SetVScroll}
for a description of the meanings of parameters.

%............................................................
\Meth{virtual int GetVScroll(int\& Shown, int\& Top)}
\Indextt{GetVScroll}

Get the status of the Vertical Scroll bar. See
\code{GetHScroll} for details.

%............................................................
\Meth{virtual int GetWidth()}
\Indextt{GetWidth}

Returns the width of the current drawing canvas in pixels.
This is either the initial size of the window, or the size
after the user has resized the window.

%............................................................
\Meth{void SetCursor(VCursor id)}
\Indextt{SetCursor}

This method sets the cursor displayed while the mouse in
in the current canvas area.
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{void SetWidthHeight(int width, int height)}
\Indextt{SetWidthHeight}

This will set the size of the drawing canvas to \code{height}
and \code{width} in pixels. It will also cause a \code{Resize}
event message to be sent to the window.

%............................................................
\Meth{virtual void SetHScroll(int Shown, int Top)}
\Indextt{SetHScroll}

Set the horizontal scroll bar
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void SetVScroll(int Shown, int Top)}
\Indextt{SetVScroll}\index{scroll bars}

Set the vertical scroll bar. 
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void ShowHScroll(int OnOrOff)}
\Indextt{ShowHScroll}
\Meth{virtual void ShowVScroll(int OnOrOff)}
\Indextt{ShowVScroll}\index{scroll bars}

See the description of \code{vCanvasPane} for details.

\subsection* {Methods to Override} %------------------------

%............................................................
\Meth{virtual void HPage(int Shown, int Top)}
\Indextt{HPage}

When the user moves the horizontal scroll bar, it generates an
\code{HPage} event. 
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void HScroll(int step)}
\Indextt{HScroll}

This method is called when the user enters a single step command
to the scroll bar. 
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void MouseDown(int x, int y, int button)}
\Indextt{MouseDown}

This is called when the user clicks a button on the mouse.

It is important to remember that all mouse coordinates are
in screen pixels, and use 0,0 as the upper left corner.
You will probably have to map them to the actual coordinates
in use by your OpenGL graphic.

See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void MouseMotion(int x, int y)}
\Indextt{MouseMotion}

This is called when the mouse moves while a button is \emph{not}
pressed.
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void MouseMove(int x, int y, int button)}
\Indextt{MouseMove}

This is called when the mouse moves while a button is pressed.
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void MouseUp(int x, int y, int button)}
\Indextt{MouseUp}

This is called when the user releases the mouse button.
See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void Redraw(int x, int y, int width, int height)}
\Indextt{Redraw}

\code{Redraw} is called when the canvas needs to be redrawn.
The first redraw is generated when the canvas is first created.
Other redraws are generated when the canvas is covered or uncovered
by another window, and means the contents of the canvas must
be repainted. Normally, you will put a call to the code that
redraws your OpenGl picture here.

The parameters of \code{Redraw} represent the rectangular area
that needs to be repainted. This areas is not always the whole
canvas, and it is possible that many \code{Redraw} events will
be generated in a row as the user drags a covering window off
the canvas.

The default \code{Redraw} in \code{vBaseGLCanvasPane} is a
no-op, and your subclass needs to override \code{Redraw}.

%............................................................
\Meth{virtual void Resize(int newW, int newH)}
\Indextt{Resize}

A \code{Resize} event is generated when the user changes the
size of the canvas using the resize window command provided
by the host windowing system.

The default \code{Resize} in \code{vBaseGLCanvasPane} is a
no-op, and your subclass needs to override \code{Redraw}.

%............................................................
\Meth{virtual void VPage(int Shown, int Top)}
\Indextt{VPage}

See the description of \code{vCanvasPane} for details.

%............................................................
\Meth{virtual void VScroll(int step)}
\Indextt{VScroll}

See the description of \code{vCanvasPane} for details.

\subsection* {Specific OpenGL methods} %----------------------

%............................................................
\Meth{virtual void graphicsInit(void)}
\Indextt{graphicsInit}

This method is called after the OpenGL drawing canvas has
been created, and \emph{must} be overridden by your code.
You use this method to set up whatever you would usually do
to initialize OpenGL. In practice, this is a very convenient
way to get things started. 

It is critical that you call the \code{graphicsInit} method
in the base \code{vBaseGLCanvasPane} class \emph{first},
then whatever OpenGL calls you need.
See the example in the OpenGL tutorial section for more details.

%............................................................
\Meth{void vglMakeCurrent(void)}
\Indextt{vglMakeCurrent}

This method should be called by your program before you
call any OpenGL drawing code. Normally, this is called
first thing in \code{Redraw}, or whatever code you use
to draw with. It is essential to call this, and since
it is cheap to call this for an already current drawing
canvas, it is better to be safe.

%............................................................
\Meth{virtual void vglFlush(void)}
\Indextt{vglFlush}

Call this method after you are finished calling OpenGL to
draw a picture. It automatically handles the details of
displaying your picture in the window, including double
buffering and synchronization. It is normally found in your
\code{Redraw} method.
        
%............................................................
\Meth{virtual XVisualInfo* GetXVisualInfo()}
\Indextt{GetXVisualInfo()}

This method is specific to X, and will return a pointer to the
\code{XVisualInfo} structure currently being used. There will
be an equivalent method available for MS-Windows.

\subsection* {Tutorial} %---------------------------------------

A minimal V/OpenGL application will consist of a class derived
from \code{vApp}, a class derived from \code{vCmdWindow}, and
a canvas pane class derived from \code{vBaseGLCanvasPane}.
Most of your drawing code will be in or called from your derived
canvas pane.

Within that class, you will minimally need to override the
\code{graphicsInit} method, and the \code{Redraw} method. The
following code fragment, adapted directly from the example code
in Mark J. Kilgard's book, \emph{OpenGL, Programming for the X
Window System}, shows how simple it can be to draw a picture.
The full code can be found in the \code{opengl/shapes} directory
in the \V\ distribution.

\footnotesize
\begin{verbatim}

  static int initDone = 0;

  ......

//==========>>> testGLCanvasPane::graphicsInit <<<=================
  void testGLCanvasPane::graphicsInit(void)
  {
    // Always call the superclass first!
    vBaseGLCanvasPane::graphicsInit();

    // Example from Mark Kilgard
    glEnable(GL_DEPTH_TEST);
    glClearDepth(1.0);
    glClearColor(0.0, 0.0, 0.0, 0.0);  /* clear to black */
    glMatrixMode(GL_PROJECTION);
    gluPerspective(40.0, 1.0, 10.0, 200.0);
    glMatrixMode(GL_MODELVIEW);
    glTranslatef(0.0, 0.0, -50.0);
    glRotatef(-58.0, 0.0, 1.0, 0.0);

    initDone = 1;
  }

//============>>> testGLCanvasPane::Spin <<<=======================
  void testGLCanvasPane::Spin()
  {
    // Called from the parent CmdWindow for animation
    vglMakeCurrent();              // Call this FIRST!
    glRotatef(2.5, 1.0, 0.0, 0.0);
    Redraw(0,0,0,0);
  }

//============>>> testGLCanvasPane::Redraw <<<=====================
  void testGLCanvasPane::Redraw(int x, int y, int w, int h)
  {
    static int inRedraw = 0;

    if (inRedraw || !initDone)  // Don't draw until initialized
 	return;

    inRedraw = 1;               // Don't allow recursive redraws.

    vglMakeCurrent();           // Call this to make current

    // Code taken directly from Mark J. Kilgard's example
    // Draws 3 intersecting triangular planes
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    glBegin(GL_POLYGON);
    glColor3f(0.0, 0.0, 0.0); glVertex3f(-10.0, -10.0, 0.0);
    glColor3f(0.7, 0.7, 0.7); glVertex3f(10.0, -10.0, 0.0);
    glColor3f(1.0, 1.0, 1.0); glVertex3f(-10.0, 10.0, 0.0);
    glEnd();

    glBegin(GL_POLYGON);
    glColor3f(1.0, 1.0, 0.0); glVertex3f(0.0, -10.0, -10.0);
    glColor3f(0.0, 1.0, 0.7); glVertex3f(0.0, -10.0, 10.0);
    glColor3f(0.0, 0.0, 1.0); glVertex3f(0.0, 5.0, -10.0);
    glEnd();

    glBegin(GL_POLYGON);
    glColor3f(1.0, 1.0, 0.0); glVertex3f(-10.0, 6.0, 4.0);
    glColor3f(1.0, 0.0, 1.0); glVertex3f(-10.0, 3.0, 4.0);
    glColor3f(0.0, 0.0, 1.0); glVertex3f(4.0, -9.0, -10.0);
    glColor3f(1.0, 0.0, 1.0); glVertex3f(4.0, -6.0, -10.0);
    glEnd();

    vglFlush();    // Call when done drawing to display

    inRedraw = 0;  // Not in here any more
  }

  ....
\end{verbatim}
\normalfont\normalsize

Note that this example includes a method called \code{Spin}.
It is used to animate the intersecting planes. In a \V\
OpenGL application, the easiest way to implement animation
is with the timer. Create a timer in the Command Window
class, and then call the animation code in the canvas
in response to timer events. You should keep code to
prevent recursive redraws if the timer events end up
occurring faster than the picture can be rendered, which
might happen for complex pictures or heavily loaded systems.
See the example code in the \code{v/opengl} directory for
a complete example of animation using the timer.

\subsection* {See Also} %---------------------------------------

vCanvasPane

%------------------------------------------------------------------------

\Class{vColor}
\Indextt{vColor}
\index{color!in V}

A class for handling and specifying colors.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vcolor.h>}
	\item [Class name:] vColor
\end{description}

\subsection* {Description}

The \V\ color model allows you to specify colors as an RGB value.
\index{color!RGB model}
The intensity of each primary color, red, green, and blue are
specified as a value between 0 and 255. This allows you to
specify up to $2^{24}$ colors. Just how many of all these
colors you can see and how they will look on your display will
depend on that display. Even so, you can probably count  on
(255,0,0) being something close to red on most displays. Given
this 24 bit model, the \code{vColor} class allows you to define
colors easily.

In order to make using colors somewhat easier, \V\ has defined
\index{color!standard}
a standard array of 16 basic colors that you can
access by including \code{v/vcolor.h>}. This array is called
\code{vStdColors}. You index the array using the symbols \code{vC\_Black},
\code{vC\_Red}, \code{vC\_DimRed}, \code{vC\_Green}, \code{vC\_DimGreen},
\code{vC\_Blue}, \code{vC\_DimBlue}, \code{vC\_Yellow},
\code{vC\_DimYellow}, \code{vC\_Magenta}, \code{vC\_DimMagenta},
\code{vC\_Cyan}, \code{vC\_DimCyan}, \code{vC\_DarkGray},
\code{vC\_MedGray}, and \code{vC\_White}. For example, use the standard color
\code{vStdColors[vC\_Green]} to represent green. You can also get a
\code{char} for the color by using the symbol to index the
\code{char* vColorName[16]} array.

The file \code{<v/vcb2x4.h>} contains definitions for
\index{color!selection buttons}
8 color buttons in a 2 high by 4 wide frame. The file
\code{<v/vcb2x8.h>} has a 2 by 8 frame of all 16 standard colors.
You can specify the size of each button in the frame by
defining \code{vC\_Size}. The default is 8. You can also specify
the location in a dialog of the color button frame by defining
the symbols \code{vC\_Frame, vC\_RightOf,} and \code{vC\_Below}.
The ids of each button in the frame correspond to the color
indexes, but with a \code{M} prefix (e.g., \code{M\_Red} for
\code{vC\_Red}). See the example in \code{v/examp} for and example
of using the standard color button frames.

Also note that unlike most other \V\ objects, it makes perfect
sense to assign and copy \code{vColor} values. Thus, assignment,
copy constructor, and equality comparison operators are provided.

\subsection* {Constructor} %------------------------------------

\Meth{vColor(unsigned int rd 0, unsigned int gr = 0, unsigned int
bl = 0)}
\Indextt{vColor}

The class has been defined so you can easily initialize a color
either by using its constructor directly, or indirectly via an
array declaration. Each color has a red, green, and blue value in
the range of 0 to 255.

\footnotesize
\begin{verbatim}
  // Declare Red via constructor
  vColor btncolor(255, 0 , 0);   // Red

  // Declare array with green and blue
  vColor GreenAndBlue[2] =
    {
      (0, 255, 0),              // Green
      (0, 0, 255)               // Blue
    };
\end{verbatim}
\normalfont\normalsize

\subsection* {Utility Methods} %--------------------------------

\Meth{BitsOfColor()}

This method returns the number of bits used by the machine
to display to represent color. A value of 8, for example,
means the computer is using 8 bits to show the color.

\Meth{ResetColor(unsigned int rd = 0, unsigned int gr = 0,
unsigned int bl = 0)}
\Meth{ResetColor(vColor\& c)}
\Indextt{ResetColor}

Like the \code{Set} method, this method will set all three values
of the color at once. However, \V\ tries to preserve entries in
the system color palette or color map with \code{ResetColor}.
You can also pass a \code{vColor} object.

Consider the following code excerpt:

\footnotesize
\begin{verbatim}
    vColor aColor;        // A V Color
    vBrush aBrush;
    int iy;

    ...

    for (iy = 0 ; iy < 128 ; ++iy)
      {
        aColor.Set(iy,iy,iy);     // Set to shade of gray
        aBrush.SetColor(aColor);  // Set brush
        canvas.DrawLine(10,iy+100,200,iy+100);  // Draw line
      }
    ...

\end{verbatim}
\normalfont\normalsize

This example will use up 128 color map entries on some systems
(X, for example). Once a system has run out of entries, \V\ will
draw in black or white. When these systems run out of new color
map entries, the color drawn for new colors will be black or
white. 

\footnotesize
\begin{verbatim}
    vColor aColor;        // A V Color
    vBrush aBrush;
    int iy;

    ...

    for (iy = 0 ; iy < 128 ; ++iy)
      {
        aColor.ResetColor(iy,iy,iy);     // Set to shade of gray
        aBrush.SetColor(aColor);  // Set brush
        canvas.DrawLine(10,iy+100,200,iy+100);  // Draw line
      }
    ...

\end{verbatim}
\normalfont\normalsize

This example accomplishes the same as the first, but does not use
up color map entries. Instead, the entry used for \code{aColor}
is reused to get better use of the color map. If your application
will be working with a large number of colors that will vary,
using \code{ResetColor} will minimize the number of color map accesses.

On some systems, and systems with a full 24 bits of color,
\code{ResetColor} and \code{Set} work identically.

\emph{WARNING}: If you intend to use \code{ResetColor} on a
\code{vColor} object, then \code{ResetColor} is the only way
you should change the color of that object. You should not
use the color assignment operator, or \code{Set}. \code{ResetColor}
needs to do some unconventional things internally to
preserve color palette entries, and these can be incompatible
with regular assignment or \code{Set}. You can, however,
safely use such a \code{vColor} object with any other \code{vColor}
object. For example:

\footnotesize
\begin{verbatim}
    vColor c1, c2;

    c1.ResetColor(100,100,100);    // You can use c1 with others.
    c2 = c1;                       // OK, but this = now makes c2
                                   // incompatible with ResetColor.
    c2.ResetColor(200,200,200);    // DON'T DO THIS
\end{verbatim}
\normalfont\normalsize

\Meth{Set(unsigned int rd = 0, unsigned int gr = 0, unsigned int bl = 0)}

Set all three values of the color at once.

\Meth{void SetR(unsigned int rd = 0)}
\Indextt{SetR}

Set the Red value.

\Meth{void SetG(unsigned int gr = 0)}
\Indextt{SetG}

Set the Green value.

\Meth{void SetB(unsigned int bl = 0)}
\Indextt{SetB}

Set the Blue value.

\Meth{unsigned int r()}

Get the Red value.

\Meth{unsigned int g()}

Get the Green value.

\Meth{unsigned int b()}

Get the Blue value.

\Meth{int operator ==}

Compare two color objects for equality.

\Meth{int operator !=}

Compare two color objects for inequality.

\subsection* {Notes about color}

The color model used by \V\ attempts to hide most of the
details for using color. However, for some applications
you may end up confronting some of the sticky issues of
color.

Most machines in use in 1996 will not support all $2^{24}$
colors that can be represented by the RGB color specification.
Typically, they devote 8 or 16 bits to each pixel. This
means that the 24-bit RGB colors must be mapped to the
smaller 8-bit or 16-bit range. This mapping is usually
accomplished by using a palette or colormap.

\V\ tries to use the default system color palette provided by the
machine it is running on. On some systems, such as X, it is
possible to run out of entries in the color map. Others, like
Windows, map colors not in the color palette to dithered colors.
\V\ provides two methods to help with this problem. First,
\code{vColor::BitsOfColor()} tells you how many bits are used by
the running system to represent color. The method  
\code{vColor::ResetColor(r,g,b)} can be used to change the value
of a color without using up another entry in the system color
map. For now, these methods should allow you to work with color
with pretty good flexibility. Eventually, \V\ may include more
direct support for color palettes.


\subsection* {See Also}

C\_ColorButton, vCanvas


%------------------------------------------------------------------------

\Class{vDC}
\Indextt{vDC}

This is the base class that defines all the drawing methods provided
by the various drawing canvases.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vdc.h>}
	\item [Class name:] vDC
\end{description}

\subsection* {Description}

All drawing classes such as \code{vCanvasPaneDC} and \code{vPostScriptDC}
are derived from this class. Each drawing class will support
these methods as needed. Not all drawing classes have the same
scale, and printer drawing canvases provide extra support for
paging. Your code will not normally need to include \code{vdc.h}.

See the specific sections for details of drawing classes.

\subsection* {Utility Methods}

%............................................................
\Meth{virtual void BeginPage()}
\Indextt{BeginPage}

Supported by printer canvases. Call to specify a page is
beginning. Bracket pages with \code{BeginPage} and \code{EndPage}
calls.

%............................................................
\Meth{virtual void BeginPrinting()}
\Indextt{BeginPrinting}

Required by printer canvases. Call to specify a document is
beginning. You \emph{must} bracket documents with \code{BeginPrinting}
and \code{EndPrinting} calls. \code{BeginPrinting} includes an
implicit call to \code{BeginPage}.

%............................................................
\Meth{virtual void Clear()}
\Indextt{Clear}

Clear the canvas to the background color. No op on printers.

%............................................................
\Meth{virtual void ClearRect(int x, int y, int width, int height)}
\Indextt{ClearRect}

Clear a rectangular area starting at x,y of height and width. No
op on printers.

%............................................................
\Meth{void CopyFromMemoryDC(vMemoryDC* memDC, int destX, int
destY, int srcX = 0, int srcY = 0, int srcW = 0, int srcH = 0)}
\Indextt{CopyFromMemoryDC}
 
This method is used to copy the image contained in a \code{vMemoryDC}
to another drawing canvas. The parameter \code{memDC} specifies
the \code{vMemoryDC} object, and \code{destX} and \code{destY}
specify where the image is to be copied into \code{this} drawing
canvas (which will usually be 0,0). If you use the default
values for \code{srcX=0}, \code{srcY=0}, \code{srcW=0}, and
\code{srcH=0}, the entire source canvas will be copied.

Beginning with \V release 1.13, \code{CopyFromMemoryDC} provides
the extra parameters to specify an area of the source to copy.
You can specify the source origin, and its width and height.
The default values for these allow backward call and behavior
compatibility.

One of the most useful uses of this is to draw both the canvas
pane drawing canvas, and to a memory drawing canvas, and then
use \code{CopyFromMemoryDC} to copy the memory canvas to the
canvas pane for \code{Redraw} events.

%............................................................
\Meth{virtual void DrawAttrText(int x, int y, char* text, const
ChrAttr attr)}
\Indextt{DrawAttrText}

Draw text using the current font with specified attributes at
given x, y.

\index{text drawing attributes}
\code{ChrAttr attr} is used to specify attributes to override
some of the text drawing characteristics normally determined by
the pen and font. Specifying \code{ChNormal} means the current
pen and font will be used.  \code{ChReverse} is used to specify
the text should be drawn reversed or highlighted, using the
current font and pen. You can also specify 16 different standard
colors to override the pen color. You use \code{ORed}
combinations the basic color attributes \code{ChRed}, \code{ChBlue},
and \code{ChGreen}. Most combinations are also provided as
\code{ChYellow}, \code{ChCyan}, \code{ChMagenta},  \code{ChWhite},
and \code{ChGray}. These colors can be combined with \code{ChDimColor}
can be used for half bright color combinations (or you can use
\code{ChDimRed}, etc.). You can combine color attributes with
\code{ChReverse}. Attributes such as boldface, size, and
underlining are attributes of the font.

%............................................................
\Meth{virtual void DrawColorPoints(int x, int y, int nPts, vColor*
pts)}
\Indextt{DrawColorPoints}

Draw an array of \code{nPts} \code{vColors} as points starting at
x,y. This method is useful for drawing graphical images, and
bypasses the need to set the pen or brush for each point.
Typically, \code{DrawColorPoints} will be significantly faster
than separate calls to \code{DrawPoint}.

%............................................................
\Meth{virtual void DrawEllipse(int x, int y, int width, int
height)}
\Indextt{DrawEllipse}

Draw an ellipse inside the bounding box specified by x, y, width,
and height.
The current Pen will be used to draw the shape, and the current
Brush will be used to fill the shape.

%............................................................
\Meth{virtual void DrawIcon(int x, int y, vIcon\& icon)}
\Indextt{DrawIcon}

A \code{vIcon} is drawn at x,y using the current Pen.
Note that only the location of an icon is scaled. The icon
will retain its original size.

%............................................................
\Meth{virtual void DrawLine(int x, int y, int xend, int yend)}
\Indextt{DrawLine}

Draw a line from x,y to xend,yend.
The current Pen will be used to draw the line.

%............................................................
\Meth{virtual void DrawLines(vLine* lineList, int count)}
\Indextt{DrawLines}

Draws the \code{count} lines contained in the list \code{lineList}.

The current Pen will be used to draw the lines.

The type \code{vLine} is defined in \code{v\_defs.h} as:
\Indextt{vLine}
\footnotesize
\begin{verbatim}
    typedef struct vLine
      {
        short x, y, xend, yend;
      } vLine;
\end{verbatim}
\normalfont\normalsize


%............................................................
\Meth{virtual void DrawPoint(int x, int y)}
\Indextt{DrawPoint}

Draw a point at x,y using the current Pen.

%............................................................
\Meth{virtual void DrawPoints(vPoint* pointList, int count)}
\Indextt{DrawLines}

Draws the \code{count} points contained in the list \code{pointList}.

The current Pen will be used to draw the points.

The type \code{vPoint} is defined in \code{v\_defs.h} as:
\Indextt{vLine}
\footnotesize
\begin{verbatim}
    typedef struct vPoint
      {
        short x, y;
      } vPoint;
\end{verbatim}
\normalfont\normalsize

%............................................................
\Meth{virtual void DrawPolygon(int n, vPoint points[],
int fillMode = vAlternate)}
\Indextt{DrawPolygon}

A closed polygon of n points is drawn. Note that the
first and last element of the point list must specify
the same point.
The current Pen will be used to draw the shape, and the current
Brush will be used to fill the shape.

The fillMode parameter specifies one of two alternative filling
algorithms, \code{vAlternate} or \code{vWinding}. These algorithms correspond
to the equivalent algorithms on the native platforms.

The type \code{vPoint} is defined in \code{v\_defs.h} as:
\Indextt{vPoint}
\footnotesize
\begin{verbatim}
    typedef struct vPoint       // a point
      {
        short x, y;             // X version
      } vPoint; 
\end{verbatim}
\normalfont\normalsize

%............................................................
\Meth{virtual void DrawRoundedRectangle(int x, int y, int width,
int height, int radius = 10)}
\Indextt{DrawRoundedRectangle}

Draw a rectangle with rounded corners at x,y of size width and
height. The radius specifies the radius of the circle used to
draw the corners. If a radius of less than 0 is specified, the
radius of the corners will be ((width+height)/-2*radius) which
gives a more or less reasonable look for various sized
rectangles. The current Pen will be used to draw the shape, and
the current Brush will be used to fill the shape.

%............................................................
\Meth{virtual void DrawRectangle(int x, int y, int width,
int height)}
\Indextt{DrawRectangle}

Draw a rectangle with square corners at x,y of size width and
height. The current Pen will be used to draw the shape, and the
current Brush will be used to fill the shape.

%............................................................
\Meth{virtual void DrawRectangles(vRect* rectList, int count)}
\Indextt{DrawRectangles}

Draw a list of \code{count} \code{vRect} rectangles pointed to by
the list \code{rectList}.
The current Pen will be used to draw the rectangles, and the
current Brush will be used to fill the rectangles.

The type \code{vRect} is defined in \code{v\_defs.h} as:
\Indextt{vRect}
\footnotesize
\begin{verbatim}
    typedef struct vRect
      {
        short x, y, w, h;
      } vRect;
\end{verbatim}
\normalfont\normalsize

%............................................................
\Meth{virtual void DrawRubberLine(int x, int y, int xend, int yend)}
\Indextt{DrawRubberLine}

Draw a rubber-band line from x, y to xend, yend. This method is most
useful for showing lines while the mouse is down. By first drawing
a rubber line, and then redrawing over the same line with \code{DrawRubberLine}
causes the line to be erased. Thus, pairs of rubber lines can track
mouse movement. The current Pen is used to determine line style.

%............................................................
\Meth{virtual void DrawRubberEllipse(int x, int y, int width,
int height)}
\Indextt{DrawRubberEllipse}

Draw a rubber-band Ellipse. See DrawRubberLine.

%............................................................
\Meth{virtual void DrawRubberPoint(int x, int y)}
\Indextt{DrawRubberPoint}

Draw a rubber-band point. See DrawRubberLine.

%............................................................
\Meth{virtual void DrawRubberRectangle(int x, int y, int width,
int height)}
\Indextt{DrawRubberRectangle}

Draw a rubber-band rectangle. See DrawRubberLine.

%............................................................
\Meth{virtual void DrawText(int x, int y, char* text)}
\Indextt{DrawText}

Simple draw text at given x, y using the current font and
current pen. Unlike icons and other \V\ drawing objects,
\code{x} and \code{y} represent the lower left corner of the
first letter of the text. Using a \code{vSolid} pen results
in the text being drawn in with the pen's color using
the current background color. Using a \code{vTransparent}
pen results in text in the current color, but just drawing
the text over the current canvas colors. (See \code{vPen::SetStyle}.)

%............................................................

\Meth{virtual void EndPage()}
\Indextt{EndPage}

Supported by printer canvases. Call to specify a page is
ending. Bracket pages with \code{BeginPage} and \code{EndPage}
calls.

%............................................................
\Meth{virtual void EndPrinting()}
\Indextt{EndPrinting}

Supported by printer canvases. Call to specify a document is
ending. Bracket documents with \code{BeginPrinting} and
\code{EndPrinting} calls. \code{EndPrinting} includes
an implicit call to \code{EndPage}.

%............................................................
\Meth{virtual vBrush GetBrush()}
\Indextt{GetBrush}

Returns a copy of the current brush being used by the canvas.

%............................................................
\Meth{virtual vFont GetFont()}
\Indextt{GetFont}

Returns a copy of the current font of the drawing canvas.

%............................................................
\Meth{virtual vBrush GetPen()}
\Indextt{GetPen}

Returns a copy of the current pen being used by the canvas.

%............................................................
\Meth{virtual int GetPhysHeight()}
\Indextt{GetPhysHeight}

Returns the maximum physical y value supported by the
drawing canvas. Especially useful for determining scaling
for printers.

%............................................................
\Meth{virtual int GetPhysWidth()}
\Indextt{GetPhysWidth}

Returns the maximum physical x value supported by the
drawing canvas. Especially useful for determining scaling
for printers.

%............................................................
\Meth{virtual void GetScale(int\& mult, int\& div)}
\Indextt{GetScale}

Returns the scaling factors for the
canvas. See \code{SetScale}.

%............................................................
\Meth{void GetTranslate(int\& x, int\& y)}
\Indextt{GetTranslate}
\Meth{int GetTransX()}
\Indextt{GetTransX}
\Meth{int GetTransY()}
\Indextt{GetTransY}

Returns the current x and y translation values.

%............................................................
\Meth{virtual void SetBackground(vColor\& color)}
\Indextt{SetBackground}
\index{color!background}

This sets the background of the drawing canvas to the
specified color.

%............................................................
\Meth{virtual void SetBrush(vBrush\& brush)}
\Indextt{SetBrush}

This sets the brush used by the drawing canvas. Brushes are used
for the filling methods such as \code{vDrawPolygon}. It is
important to call \code{SetBrush} whenever you change any
attributes of a brush used by a drawing canvas.

%............................................................
\Meth{virtual void SetFont(vFont\& vf)}
\Indextt{SetFont}

Change the font associated with this canvas. The default method
handles changing the font and calls the FontChanged method for
the canvas pane.

%............................................................
\Meth{virtual void SetPen(vPen\& pen)}
\Indextt{SetPen}

Sets the current pen of the canvas to pen. Pens are used
to draw lines and the outlines of shapes. It is important
to call \code{SetPen} whenever you change any attributes of
a pen used by a drawing canvas.

%............................................................
\Meth{virtual void SetScale(int mult, int div)}
\Indextt{SetScale}

Sets the scaling factor. Each coordinate passed to the 
drawing canvas is first multiplied by mult and then divided
by div. Thus, to scale by one third, set mult to 1 and div to 3.
Many applications will never have to worry about scaling.
Note that scaling applies to output only. The mouse
events will provide unscaled coordinates, and it is up
to your code to scale mouse coordinates appropriately.

%............................................................
\Meth{void SetTranslate(int x, int y)}
\Indextt{SetTranslate}
\Meth{void SetTransX(int x)}
\Indextt{SetTransX}
\Meth{void SetTransY(int y)}
\Indextt{SetTransY}

These methods set the internal translation used by the
drawing canvas. Each coordinate sent to the various
drawing methods (e.g., \code{DrawRectangle}) will be
translated by these coordinates. This can be most useful
when using the scroll bars to change which part of a
drawing is visible on the canvas. Your application will
have to handle proper mapping of mouse coordinates.

%............................................................
\Meth{int TextHeight(int\& ascent, int\& descent)}
\Indextt{TextHeight}

This function returns the total height of the font \code{fontId}.
The total height of the font is the sum of the \code{ascent} and
\code{descent} heights of the font \code{fontId}. Each character
ascends \code{ascent} pixels above the Y coordinate where it is
being drawn, and \code{descent} pixels below the Y coordinate.

%............................................................
\Meth{int TextWidth(char* str)}
\Indextt{TextWidth}

Returns the width in pixels or drawing points of the string
\code{str} using the currently set font of the canvas.

%------------------------------------------------------------------------
\Class{vMemoryDC}
\Indextt{vMemoryDC}

A memory drawing canvas.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vmemdc.h>}
	\item [Class name:] vMemoryDC
\end{description}

\subsection* {Description}

This drawing canvas can be used to draw to memory. Like
all drawing canvases, the available methods are described
in \code{vDC}. A very effective technique for using a memory
canvas is to draw to both the screen canvas pane and a memory
canvas during interactive drawing, and use the memory canvas to
update the screen for \code{Redraw} events. This is especially
useful if your application requires extensive computation to
draw a screen.

\subsection* {Methods}

\Meth{vMemoryDC(int width, int height)}
\Indextt{vMemoryDC}

The constructor is used to construct a memory DC of the
specified width and height. This can be anything you need.
If you are using the memory DC to update the screen for
\code{Redraw} events, then it should be initialized to be
big enough to repaint whatever you will be drawing on the
physical screen. The methods  \code{vApp::ScreenWidth()} and
\code{vApp::ScreenHeight()} can be used to obtain the maximum
size of the physical screen.

The method \code{CopyFromMemoryDC} is used to copy the contents
of a memory DC to another DC. This can be another memory DC, but
will usually be a canvas pane DC.

%------------------------------------------------------------------------
\Class{vPen}
\Indextt{vPen}\index{pen}

A class to specify the pen used to draw lines and shapes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vpen.h>}
	\item [Class name:] vPen
\end{description}

\subsection* {Description}

Pens are used to draw lines and the outlines of shapes. Pens have
several attributes, including color, width, and style.

\subsection* {Methods}

\Meth{vPen(unsigned int r = 0, unsigned int g = 0, unsigned int b = 0, 
int width = 1, int style = vSolid)}
\Indextt{vPen}

The constructor for a pen allows you to specify the pen's color,
width, and style. The default will construct a solid black pen of
width 1.

\Meth{int operator ==, !=}

You can use the operators \code{==} and \code{!=} for comparisons.

\Meth{vColor GetColor()}
\Indextt{GetColor}

This method returns the current color of the pen as a \code{vColor} object.

\Meth{int GetStyle()}
\Indextt{GetStyle}

This method returns the current style of the pen.

\Meth{void GetWidth()}
\Indextt{GetWidth}

This gets the width of the line the pen will draw.

\Meth{void SetColor(vColor\& c)}
\Indextt{SetColor}
\index{color!pen}

You can use this method to set the pen color by passing
in a \code{vColor} object.

\Meth{void SetStyle(int style)}
\Indextt{SetStyle}

This method is used to change the style of a pen. Styles include:

\begin{description}
	\item [vSolid] The pen draws a solid line.
	\item [vTransparent] The pen is transparent. A transparent
pen can be used to avoid drawing borders around shapes. When drawing
text, a transparent pen draws the text over the existing background.
	\item [vDash] The pen draws a dashed line.
	\item [vDot] The pen draws a dotted line.
	\item [vDashDot] The pen draws an alternating dash and dotted line.
\end{description}

\Meth{void SetWidth(int width)}
\Indextt{SetWidth}

This sets the width of the line the pen will draw.

%------------------------------------------------------------------------
\Class{vPrintDC}
\Indextt{vPrintDC}\index{printing}

A printer drawing canvas.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vprintdc.h>}
	\item [Class name:] vPrintDC
\end{description}

\subsection* {Description}

This drawing canvas can be used to draw to a printer. Like
all drawing canvases, the available methods are described
in \code{vDC}. A very effective technique for combining a printer
DC and a screen DC is to pass a pointer to either a \code{vCanvasPaneDC}
or a \code{vPrintDC} to the code that draws the screen. The same
code can then be used to draw or print.

To successfully use a \code{vPrintDC}, your code must
obtain the physical size of the page in units using
\code{GetPhysWidth} and \code{GetPhysHeight}. On
paper, these represent 1/72 inch points, and correspond
very closely, but not exactly, to a pixel on the screen.

You must bracket the printing with calls to \code{BeginPrinting}
and \code{EndPrinting}. Use \code{BeginPage} and \code{EndPage}
to control paging. Note that the width of text will not
necessarily be the same on a \code{vCanvasPaneDC} and a \code{vPrintDC},
even for the same fonts. Also, the size of the paper represents
the entire page. Most printers cannot actually print all the way
to the edges of the paper, so you will usually use \code{vDC:SetTranslate}
to leave some margins. (Don't forget to account for margins when
you calculate what can fit on a page.)

The implementation of \code{vPrintDC} is somewhat platform
dependent. For X, \code{vPrintDC} represents a PostScript
printer, and is derived from the class \code{vPSPrintDC}. For
Windows, \code{vPrintDC} is derived from the \code{vWinPrintDC}
class. To get platform independent operation for your
application, use \code{vPrintDC}. On Windows, you can also use
the PostScript version directly if you want by using the \code{vPSPrintDC}
class, but the program will not conform to standard Windows
behavior.

\subsection* {Methods}

\Meth{void SetPrinter(vPrinter\& printer)}
\Indextt{SetPrinter}

This method is used to associate a \code{vPrinter} with
a \code{vPrintDC}.
By default, a \code{vPrintDC} represents standard
8.5x11 inch Letter paper printed in black and white in
portrait orientation. You can use \code{vPrinter::Setup} to allow
the user to change the attributes of the printer, then use
\code{SetPrinter} to associate those attributes with the \code{vPrintDC}.
Note: If you change the default printer attributes, you \emph{must}
call \code{SetPrinter} before doing any drawing to the DC.

\subsection* {Example}

This is a simple example taken from the \code{VDraw} demo program.
\code{Print} is called to print the current drawing. \code{Print}
calls \code{vPrinter::Setup} to set the printer characteristics,
and then calls \code{DrawShapes} with a pointer to the \code{vPrintDC}.
\code{DrawShapes} is also called to repaint the screen using the
\code{vCanvasPaneDC}. By carefully planning for both screen and
printer drawing, your program can often share drawing code in
this fashion.

\footnotesize
\begin{verbatim}
//===================>>> myCanvasPane::Print <<<=================
  void myCanvasPane::Print()
  {
    // Print current picture

    vPrintDC pdc;               // create a vPrintDC object
    vPrinter printer;           // and a printer to set attributes

    printer.Setup("test.ps");   // setup the printer
    pdc.SetPrinter(printer);    // change to the printer we setup

    if (!pdc.BeginPrinting())   // call BeginPrinting first
        return;

    pdc.SetTranslate(36,36);    // Add 1/2" (36 * 1/72") margins

    DrawShapes(&pdc);           // Now, call shared drawing method

    pdc.EndPrinting();          // Finish printing
  }

//===================>>> myCanvasPane::DrawShapes <<<=================
  void myCanvasPane::DrawShapes(vDC* cp)
  {
    // Common code for drawing both on Screen and Printer
    ...
  }
\end{verbatim}
\normalfont\normalsize

%------------------------------------------------------------------------
\Class{vPrinter}
\Indextt{vPrinter}\index{printer attributes}

A printer object, with a dialog to interactively set printer
attributes.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vprinter.h>}
	\item [Class name:] vPrinter
\end{description}

\subsection* {Description}

The \code{vPrintDC} class prints to a printer (or a file that
will eventually be printed). Printers have such attributes as
size of paper, page orientation, color capability, etc. By
calling the \code{vPrinter::Setup} dialog before printing, the
user will be given the option of setting various printer
attributes.

The exact functionality of the \code{Setup} dialog will be
platform dependent. By using the \code{vPrinter} class, you will
get the behavior appropriate for the platform. If you want to use
the \code{vPSPrintDC} class for PostScript support on Windows,
you can use \code{vPSPrinter} directly.

You can use the various methods associated with a \code{vPrinter}
to get printer attributes as needed to during drawing to
the \code{vPrintDC}.

\subsection* {Methods}

\Meth{int GetCopies()}
\Indextt{GetCopies}

\Meth{void SetCopies(int s)}
\Indextt{SetCopies}

Many printers support printing multiple copies of the same
document. This attributes controls the number of copies printed.
The \code{Setup} dialog will provide control of this \emph{if} it
is supported.

\Meth{char* GetDocName()}
\Indextt{GetDocName}

Printer output may be directed to a file rather than the printer.
If it is, this will return the name of the file the output will
be sent to.

\Meth{int GetPaper()}
\Indextt{GetPaper}

\Meth{char* GetPaperName()}
\Indextt{GetPaperName}

Printers can print a variety of papers. The user may be
able to select which paper from the \code{Setup} dialog.
The printers supported are defined in the \code{vprinter.h}
header file (or the base class used by \code{vPrinter}).

\Meth{int GetPortrait()}
\Indextt{GetPortrait}

\Meth{void SetPortrait(int p)}
\Indextt{SetPortrait}

Many printers can print in either Portrait or Landscape orientation.
This returns true if the printer will print in portrait.

\Meth{int GetToFile()}
\Indextt{GetToFile}

\Meth{void SetToFile(int f)}

Printer output may be directed to a file rather than the printer.
This returns true if the user selected the option to send output
to a file.

\Meth{int GetUseColors()}
\Indextt{GetUseColors}

\Meth{void SetUseColors(int c)}
\Indextt{SetUseColors}

Printers can be either black and white, or color. This
returns true if the printer supports colors. You can
make a color printer print black and white by setting
this to false.

\Meth{int Setup(char* fn = 0)}
\Indextt{Setup}

This displays a modal dialog for the user to select desired
printer characteristics. If a filename is supplied, that
name will be used if the user selects print to file.
If \code{Setup} returns false, you should abandon the
print job. After you call \code{Setup}, you can then
call \code{vPrintDC::SetPrinter} to associate the printer
with the \code{vPrintDC}.

\subsection* {Example}

See \code{vPrintDC} for an example of using \code{vPrinter::Setup}.

%-----------------------------------------------------------------
\Class{vTextCanvasPane}
\Indextt{vTextCanvasPane}

A class for drawing text on a canvas. 

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vtextcnv.h>}
	\item [Class name:] vTextCanvasPane
 	\item [Hierarchy:] vPane \rta vCanvasPane \rta vTextCanvasPane
\end{description}

\subsection* {Description}

This class provides a complete scrolling text window. You
can send text line by line to the window, and it will scroll the
text up the screen in response to linefeed characters. You can
also position the cursor, and selectively clear areas of the text
screen or display text at specific locations. This class handles
repainting the screen on \code{Redraw} events. In essence, the
\code{vTextCanvasPane} class provides the functionality of a
typical simple-minded text terminal.

\subsection* {New Methods}

%............................................................
\Meth{void ClearRow(const int row, const int col)}
\Indextt{ClearRow}

This clears to blanks row \code{row} of the screen from
column \code{col} to the end of the line.

%............................................................
\Meth{void ClearToEnd(const int row, const int col)}
\Indextt{ClearToEnd}

This clears to blanks from row \code{row} and column \code{col}
to the end of the screen.

%............................................................
\Meth{int GetCols()}
\Indextt{GetCols}

Returns number of columns in current text canvas.

%............................................................
\Meth{int GetRows()}
\Indextt{GetRows}

Returns number of rows in current text canvas.

%............................................................
\Meth{void GetRC(int\& row, int\& col)}
\Indextt{GetRC}

Returns in \code{row} and \code{col} the current row and
column of the text cursor.

%............................................................
\Meth{void GotoRC(const int row ,const int row)}
\Indextt{GotoRC}

Moves the text cursor to \code{row,col}.

%............................................................
\Meth{void DrawAttrText(const char* text, const ChrAttr attr)}
\Indextt{DrawAttrText}

Draws \code{text} starting at the current cursor location using
text attribute \code{attr}. For more details, see \code{vDC::DrawAttrText}.

%............................................................
\Meth{void DrawChar(const char chr, const ChrAttr attr)}
\Indextt{DrawChar}

Draws a single character \code{chr} at the current
cursor location using text attribute \code{attr}. See
\code{DrawAttrText} for more details.

%............................................................
\Meth{void DrawText(const char* text)}
\Indextt{DrawText}

Draws \code{text} starting at the current cursor location.
The newline character \code{'$\backslash$n'} will
cause the cursor to move to the beginning of the next line,
and the text to scroll if the cursor was on the last line.

%............................................................
\Meth{void HideTextCursor(void)}
\Indextt{HideTextCursor}

This method will hide the text cursor.

%............................................................
\Meth{void ShowTextCursor(void)}
\Indextt{ShowTextCursor}

This method will redisplay the text cursor at the current
row and column.

%............................................................
\Meth{void ScrollText(const int count)}
\Indextt{ScrollText}

This will scroll the text in the text canvas up or down by
\code{count} lines.  There will be \code{count} blank lines
created at the bottom or top of the screen.

%............................................................
\Meth{void ResizeText(const int rows, const int cols)}
\Indextt{ResizeText}

This method handles resize events. You will want to override
this to track the new number of rows and columns.

%............................................................
\Meth{void TextMouseDown(int row, int col, int button)}
\Indextt{TextMouseDown}

This is called when the user clicks the mouse button down.
It is called with the text row and column, and the button number.

%............................................................
\Meth{void TextMouseUp(int row, int col, int button)}
\Indextt{TextMouseUp}

This is called when the user releases the mouse button.
It is called with the text row and column, and the button number.

%............................................................
\Meth{void TextMouseMove(int row, int col, int button)}
\Indextt{TextMouseMove}

This is called when the mouse moves.
It is called with the text row and column, and the button number.


\subsection* {Derived Methods}	

%............................................................
\Meth{virtual void Clear()}
\Indextt{Clear}

This clears the text canvas and resets the row and column
to 0,0.

%............................................................
\Meth{void FontChanged(int)}
\Indextt{FontChanged}

This is called when the font of the canvas changes.
\code{FontChanged} calls \code{ResizeText}, so you probably
won't have to deal with this event.

%............................................................
\Meth{void Redraw(int x, int y, int width, int height)}
\Indextt{Redraw}

Called when the screen needs to be redrawn. Normally, you won't
have to override this class since the \code{vTextCanvasPane}
superclass will handle redrawing what is in the window. Instead,
you will usually just have to respond to the \code{FontChanged}
and \code{ResizeText} events when the contents of the canvas will
actually change.

\subsection* {Inherited Methods}	%....................

\Meth{virtual void HPage(int Shown, int Top)}
\Indextt{HPage}

\Meth{virtual void HScroll(int step)}
\Indextt{HScroll}

\Meth{virtual void SetFont(int vf)}
\Indextt{SetFont}

\Meth{virtual void SetHScroll(int Shown, int Top)}
\Indextt{SetHScroll}

\Meth{virtual void SetVScroll(int Shown, int Top)}
\Indextt{SetVScroll}

\Meth{virtual void VPage(int Shown, int Top)}
\Indextt{VPage}

\Meth{virtual void VScroll(int step)}
\Indextt{VScroll}

\subsection* {See Also}

vCanvasPane, vWindow