[Table of Contents]
[Previous Chapter]
[Next Chapter]
[Object Central Home]
The V C++ GUI Reference Manual - Vers. 1.20 - 6/30/98
Copyright © 1998, Bruce E. Wampler
This chapter covers classes and utility functions needed to draw
text and graphics.
The classes and objects covered in this chapter include:
There is also a specialized drawing canvas to support OpenGL. This
class differs somewhat from the other drawing canvases.
Each vDC supports the methods described in the vDC section.
Because the vCanvasPane class is so central to most
applications, it duplicates
all the vDC methods so you can call them directly from your
vCanvasPane object. In fact, all the methods in vCanvasPane
are just calls to the corresponding vDC using the vCanvasPaneDC
of the canvas pane. You can get the vCanvasPaneDC pointer with
the 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
vPen. You change the color and width of the lines being drawn
by setting the current vPen with the 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 vPen. The filled area is drawn using the current
vBrush. You can set various attributes of the brush, and use
SetBrush to change how the shapes will be filled, as well as
changing the attributes of the 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
vFonts and text attributes. The canvas pane will start out
using the default system font (vfSystemDefault). If you need
a different initial font, use vFont::SetFontValues to
select the font you want, then vCanvasPane::SetFont to set
the new font.
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.
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 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
vDC::TextHeight and vDC::TextWidth. Use these
values to calculate how much space a text string will take
up on the screen or page.
Fonts are associated with drawing canvases. For example, the
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 TextWidth value
for screen and printer canvases for the same font.
The class 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
vFont :: SetFontValues method. The utility class vFontSelect
can be used to interactively set font characteristics. The
characteristics associated with a font are described in the
following sections. Remember, however, that vFontSelect::FontSelect
can be used to set these attributes.
Each font belongs to a font family. There are eight font families
defined by
V with the vFontID attribute of the font object.
Font families typically correspond to some typeface name such
as
Helvetica or
Times Roman, but use more generic names.
There are three system fonts, vfDefaultSystem, vfDefaultFixed,
and vfDefaultVariable. These default fonts are defined by
the specific platform. 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
-fn fontname switch when starting the application. The
vfDefaultSystem font will have fixed attributes, and will
not be changeable by the program. The vfDefaultFixed
(fixed spacing) and 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 vfSerif font
is a seriffed font such as Times Roman. The vfSanSerif
is a serifless font such as Swiss or Lucidia. Both
of these are variable spaced fonts. The vfFixed is a fixed
space font, often called Courier on the host platform.
The vfDecorative font usually contains symbols or other drawing
characters. It is not very portable across platforms. Finally,
V supports a font family called vfOther. This is used when
the system supports other fonts that are selectable via the
vFontSelect dialog class. Windows supports a wide variety of fonts,
while X does not support any additional fonts.
V supports two kinds of font styles: vfNormal for normal
fonts, and vfItalic for italic fonts.
V supports two kinds of font weights: vfNormal for
normal weight fonts, and vfBold for boldface fonts.
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.
You can also specify that a font is underlined.
You can specify that a font is to be drawn at something other
than horizontally, left to right. If you need a vertical font,
for a graph perhaps, you can specify an angle in the font
constructor. This means you must use one of V's
standard fonts, and can't use the font select dialog. You
also can't dynamically change the angle on the fly. If you
need text at more than one angle, you need to create multiple
instances of a vFont.
You specify the angle in degrees, with 0 representing
standard horizontal text. Using 90 degrees gives vertical
text, reading from bottom to top. Using 180 gives upside
down horizontal text, and 270 gives vertical text, top
to bottom. A simple example:
Brushes are used to fill shapes. Brushes have
two attributes, including color and style.
You can use the operators == and != for comparisons.
This class is normally automatically used by the vCanvasPane
class. It provides the actual implementation of the screen drawing
canvas class.
This is the base drawing class. You use it to build more complicated
drawing canvases, either for graphical drawing or text drawing.
The 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 Redraw or 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 vPane for a general description of panes.
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.
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 vDC used by the vCanvasPane
by calling GetDC().
The cursors currently supported include:
The 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 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.
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 ShowVScroll and ShowHScroll in
the code of your vCmdWindow class constructor
(or other initialization code)
after calling
vWindow::ShowWindow in your class constructor.
Sorry, but thanks to the Macintosh, handling of buttons is a bit
nonportable. The 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.
The parameters of Redraw represent the rectangular area
that needs to be repainted. This areas is not always the whole
canvas, and it is possible that many Redraw events will
be generated in a row as the user drags a covering window off
the canvas.
The default Redraw in vCanvasPane is a
no-op, and your subclass needs to override Redraw.
The default Resize in vBaseGLCanvasPane is a
no-op, and your subclass needs to override Redraw.
vTextCanvasPane
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 vTextEditor,
your class can be very minimal. You will need to provide some
service methods for the parent 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 vTextEditor,
you can get a fully functional text editor with no additional work.
However, vTextEditor has been designed to allow you to extend
and add functionality to the editor if you need to. The 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 vTextEditor class takes
care of all those details, and provides a standard editing interface.
The following steps are required to use vTextEditor. First,
you create an instance of your derived class from your vCmdWindow
class, something like this:
The following code shows how to add the contents of a text file
to the vTextEditor buffer, and display it in the canvas
for the first time. Calls to vTextEditor methods are
marked with **.
When your are editing (e.g., the user enters a Close command),
you retrieve the text from the vTextEditor buffer
with calls to getLine.
Then, to use the editor, you pass keystrokes from the
KeyIn method of your vCmdWindow to the EditKeyIn
method of the vTextEditor. 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 EditCommand
method.
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 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.
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 vTextEditor to
determine the specifications of the methods you'd need
to override.
Each function supported by vTextEditor has an
associated id (symbolically defined in v/vtexted.h), each
beginning with 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 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 edLineGoto.
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 vTextEditor is evolving,
it is likely more commands will be added. Check the
v/vtexted.h file for specification of new editor
commands. In the following descriptions, the note
``no val'' means that the val parameter is not
used. A notation of ``+/-'' means the sign of val
indicates direction.
The default implementation of 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.
vTextCanvasPane
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 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 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 vPane for a general description of panes.
V supports only one visual per application, and the first
vBaseGLCanvasPane created determines the attributes of
the visual used.
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 vCanvasPane class.
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 vCanvasPane for details.
The parameters of Redraw represent the rectangular area
that needs to be repainted. This areas is not always the whole
canvas, and it is possible that many Redraw events will
be generated in a row as the user drags a covering window off
the canvas.
The default Redraw in vBaseGLCanvasPane is a
no-op, and your subclass needs to override Redraw.
The default Resize in vBaseGLCanvasPane is a
no-op, and your subclass needs to override Redraw.
It is critical that you call the graphicsInit method
in the base vBaseGLCanvasPane class
first,
then whatever OpenGL calls you need.
See the example in the OpenGL tutorial section for more details.
A minimal V/OpenGL application will consist of a class derived
from vApp, a class derived from vCmdWindow, and
a canvas pane class derived from 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
graphicsInit method, and the Redraw method. The
following code fragment, adapted directly from the example code
in Mark J. Kilgard's book,
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 opengl/shapes directory
in the
V distribution.
vCanvasPane
The
V color model allows you to specify colors as an RGB value.
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 224 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 vColor class allows you to define
colors easily.
In order to make using colors somewhat easier,
V has defined
a standard array of 16 basic colors that you can
access by including v/vcolor.h>. This array is called
vStdColors. You index the array using the symbols vC_Black,
vC_Red, vC_DimRed, vC_Green, vC_DimGreen,
vC_Blue, vC_DimBlue, vC_Yellow,
vC_DimYellow, vC_Magenta, vC_DimMagenta,
vC_Cyan, vC_DimCyan, vC_DarkGray,
vC_MedGray, and vC_White. For example, use the standard color
vStdColors[vC_Green] to represent green. You can also get a
char for the color by using the symbol to index the
char* vColorName[16] array.
The file <v/vcb2x4.h> contains definitions for
8 color buttons in a 2 high by 4 wide frame. The file
<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 vC_Size. The default is 8. You can also specify
the location in a dialog of the color button frame by defining
the symbols vC_Frame, vC_RightOf, and vC_Below.
The ids of each button in the frame correspond to the color
indexes, but with a M prefix (e.g., M_Red for
vC_Red). See the example in 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 vColor values. Thus, assignment,
copy constructor, and equality comparison operators are provided.
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.
Consider the following code excerpt:
On some systems, and systems with a full 24 bits of color,
ResetColor and Set work identically.
WARNING: If you intend to use ResetColor on a
vColor object, then ResetColor is the only way
you should change the color of that object. You should not
use the color assignment operator, or Set. ResetColor
needs to do some unconventional things internally to
preserve color palette entries, and these can be incompatible
with regular assignment or Set. You can, however,
safely use such a vColor object with any other vColor
object. For example:
Set all three values of the color at once.
Get the Red value.
Get the Green value.
Get the Blue value.
Compare two color objects for equality.
Compare two color objects for inequality.
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 224
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,
vColor::BitsOfColor() tells you how many bits are used by
the running system to represent color. The method
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.
C_ColorButton, vCanvas
All drawing classes such as vCanvasPaneDC and 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 vdc.h.
See the specific sections for details of drawing classes.
Beginning with
Vrelease 1.13, 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 CopyFromMemoryDC to copy the memory canvas to the
canvas pane for Redraw events.
ChrAttr attr is used to specify attributes to override
some of the text drawing characteristics normally determined by
the pen and font. Specifying ChNormal means the current
pen and font will be used. 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 ORed
combinations the basic color attributes ChRed, ChBlue,
and ChGreen. Most combinations are also provided as
ChYellow, ChCyan, ChMagenta, ChWhite,
and ChGray. These colors can be combined with ChDimColor
can be used for half bright color combinations (or you can use
ChDimRed, etc.). You can combine color attributes with
ChReverse. Attributes such as boldface, size, and
underlining are attributes of the font.
The current Pen will be used to draw the lines.
The type vLine is defined in v_defs.h as:
The current Pen will be used to draw the lines.
The current Pen will be used to draw the points.
The type vPoint is defined in v_defs.h as:
The fillMode parameter specifies one of two alternative filling
algorithms, vAlternate or vWinding. These algorithms correspond
to the equivalent algorithms on the native platforms.
The type vPoint is defined in v_defs.h as:
The type vRect is defined in v_defs.h as:
This drawing canvas can be used to draw to memory. Like
all drawing canvases, the available methods are described
in 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 Redraw events. This is especially
useful if your application requires extensive computation to
draw a screen.
The method 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.
Pens are used to draw lines and the outlines of shapes. Pens have
several attributes, including color, width, and style.
You can use the operators == and != for comparisons.
This drawing canvas can be used to draw to a printer. Like
all drawing canvases, the available methods are described
in vDC. A very effective technique for combining a printer
DC and a screen DC is to pass a pointer to either a vCanvasPaneDC
or a vPrintDC to the code that draws the screen. The same
code can then be used to draw or print.
To successfully use a vPrintDC, your code must
obtain the physical size of the page in units using
GetPhysWidth and 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 BeginPrinting
and EndPrinting. Use BeginPage and EndPage
to control paging. Note that the width of text will not
necessarily be the same on a vCanvasPaneDC and a 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 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 vPrintDC is somewhat platform
dependent. For X, vPrintDC represents a PostScript
printer, and is derived from the class vPSPrintDC. For
Windows, vPrintDC is derived from the vWinPrintDC
class. To get platform independent operation for your
application, use vPrintDC. On Windows, you can also use
the PostScript version directly if you want by using the vPSPrintDC
class, but the program will not conform to standard Windows
behavior.
This is a simple example taken from the VDraw demo program.
Print is called to print the current drawing. Print
calls vPrinter::Setup to set the printer characteristics,
and then calls DrawShapes with a pointer to the vPrintDC.
DrawShapes is also called to repaint the screen using the
vCanvasPaneDC. By carefully planning for both screen and
printer drawing, your program can often share drawing code in
this fashion.
The 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 vPrinter::Setup dialog before printing, the
user will be given the option of setting various printer
attributes.
The exact functionality of the Setup dialog will be
platform dependent. By using the vPrinter class, you will
get the behavior appropriate for the platform. If you want to use
the vPSPrintDC class for PostScript support on Windows,
you can use vPSPrinter directly.
You can use the various methods associated with a vPrinter
to get printer attributes as needed to during drawing to
the vPrintDC.
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.
See vPrintDC for an example of using vPrinter::Setup.
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 Redraw events. In essence, the
vTextCanvasPane class provides the functionality of a
typical simple-minded text terminal.
vCanvasPane, vWindow
Chapter 7
Drawing
7.1 Introduction to 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.
Drawing with the vDC Class
You draw to the various canvases using a vDC class, the
general
V Drawing Canvas Class (the OpenGL canvas does not use
the codevDC class). The vDC class for drawing to the
screen is vCanvasPaneDC. The class vPrintDC is the
platform independent class to draw to a printer. For X, 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 vDC pointer, you will be able to draw to several
canvases just by changing the value of the pointer.
7.1.1 Coordinates
7.2 Fonts
Various screen fonts are available in
V.
Synopsis
Description
Font Family
Font Style
Font Weight
Point Size
Underlining
Angled text
vFont font90(vfSansSerif,10,vfNormal,vfNormal,0,90);
myCanvas->SetFont(font90);
myCanvas->DrawText(200,150,"Vertical Text");
The Windows version supports any arbitrary angle. The X
version only supports 90, 180, and 270. Because X does
not provide native support for non-horizontal text, the
initial implementation of angled text (V Version 1.18)
simulates angled text by drawing standard horizontal
characters vertically or backwards. It doesn't look
too bad, and is better than having to do it yourself.
Real vertical text will probably be supported someday,
and I will probably forget to remove this note when
that happens, so go by the release notes.
Methods
vFont(vFontID fam = vfDefaultFixed, int size = 10,
vFontID sty = vfNormal, vFontID wt = vfNormal, int und = 0,
int angle = 0)
The constructor is used to declare a font with the specified
family, size, style, weight, underline, and angle.
vFontID GetFamily()
Returns the family of the font object.
int GetPointSize()
Returns the point size of the font object.
vFontID GetStyle()
Returns the style of the font object.
vFontID GetWeight()
Returns the weight of the font object.
int GetUnderlined()
Returns the underline setting of the font object.
void SetFontValues(vFontID fam = vfDefaultFixed, int size =
10, vFontID sty = vfNormal, vFontID wt = vfNormal, int und = 0)
Changes the attributes of the font object. For example, the font
selection dialog uses this method to change the font attributes.
Note that you can't use this method to set font angles.
7.3 vBrush
A class to specify the brush used to fill shapes.
Synopsis
Description
Methods
vBrush(unsigned int r = 0, unsigned int g = 0, unsigned
int b = 0, int style = vSolid)
The brush constructor allows you to set the initial color and
style of the brush. The default constructs a solid black brush.
int operator == , !=
vColor GetColor()
This method returns the current color of the brush as a vColor object.
int GetFillMode()
This method returns the fill mode of the brush (either vAlternate
or vWinding).
int GetStyle()
This method returns the current style of the brush.
void SetColor(vColor& c)
You can use this method to set the brush color by passing
in a vColor object.
int SetFillMode(int fillMode)
This method sets the fill mode of the brush.
The fillMode parameter specifies one of two alternative filling
algorithms, vAlternate or vWinding. These algorithms correspond
to the equivalent algorithms on the native platforms.
void SetStyle(int style)
This method is used to set the style of the brush. Brush styles
include:
7.4 vCanvasPaneDC
The drawing canvas class for CanvasPanes.
Synopsis
Description
7.5 vCanvasPane
A base class to build graphical and text canvas panes.
Synopsis
Description
Utility Methods
Drawing
The vCanvasPane normally creates a vCanvasPaneDC to
use for drawing, and class provides direct support by including
direct calls for the drawing methods described in the vDC
section. If your drawing will only be to the screen, then you
can use the methods of the vCanvasPane class directly.
Each of these methods is really an inline function that expands
to _cpDC->DrawWhatever().
virtual void CreateDC(void)
This method is called when the vCanvasPane is initialized.
The default is to create a drawing canvas using _cpDC = new
vCanvasPaneDC(this);. If you want to derive a different canvas
pane class from vCanvasPane perhaps using a more
sophisticated drawing canvas derived from the vCanvasPaneDC
class, you can override the CreateDC method and set the
protected vDC* _cpDC pointer to an instance of your new
drawing canvas (e.g., _cpDC = new myCanvasPaneDC(this)
instead.
vDC* GetDC()
Returns a pointer to the vDC of the current drawing canvas. The
vDC can be used for most of the drawing methods to achieve
drawing canvas independence. If your code draws via a vDC pointer,
then the same code can draw to the screen canvas or the printer canvas
depending on what the vDC points to.
VCursor GetCursor()
Returns the id of the current cursor being used in the canvas.
See SetCursor.
virtual int GetHeight()
Returns the height of the current drawing canvas in pixels.
virtual int GetHScroll(int& Shown, int& Top)
Get the status of the Horizontal Scroll bar. Returns 1 if the
scroll bar is displayed, 0 if not. Returns in Shown and
Top the current values of the scroll bar. See SetVScroll
for a description of the meanings of parameters.
virtual int GetVScroll(int& Shown, int& Top)
Get the status of the Vertical Scroll bar. See
GetHScroll for details.
virtual int 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.
void SetCursor(VCursor id)
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.
void SetWidthHeight(int width, int height)
This will set the size of the drawing canvas to height
and width in pixels. It will also cause a Resize
event message to be sent to the window.
virtual void SetHScroll(int Shown, int Top)
Set the horizontal scroll bar. See SetVScroll for
a description of the parameters.
virtual void SetVScroll(int Shown, int Top)
Set the vertical scroll bar. The 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 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.
virtual void ShowHScroll(int OnOrOff)
virtual void ShowVScroll(int OnOrOff)
When a canvas is first displayed, it will begin with both
horizontal and scroll bars not shown by default. ShowHScroll
and 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 Resize after
you have set the scroll bars.
Methods to Override
virtual void FontChanged(int vf)
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.
virtual void HPage(int Shown, int Top)
When the user moves the horizontal scroll bar, it generates an
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 Shown and
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 SetHScroll to
set appropriate values, and they are explained there.
The Shown value supplied here
will correspond to the value you program set for the scroll bar.
The Top value should indicate the meaningful change as input
by the user.
virtual void HScroll(int step)
This method is called when the user enters a single step command
to the scroll bar. The value of 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.
virtual void MouseDown(int x, int y, int button)
This is called when the user clicks a button on the mouse. The
x and 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 vCanvasPane will need to
handle proper interpretation of mouse clicks.
virtual void MouseMotion(int x, int y)
This is called when the mouse moves while a button is
not
pressed, and gives the current x and y of the
mouse. Most applications will ignore this information.
virtual void MouseMove(int x, int y, int button)
This is called when the mouse moves while a button is pressed,
and gives the new x, y, and 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
do have the translation added.
virtual void MouseUp(int x, int y, int button)
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.
virtual void Redraw(int x, int y, int width, int height)
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 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.
virtual void Resize(int newW, int newH)
A Resize event is generated when the user changes the
size of the canvas using the resize window command provided
by the host windowing system.
virtual void VPage(int Shown, int Top)
See HPage.
virtual void VScroll(int step)
This method is called when the user enters a single step command
to the vertical scroll bar. The value of 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.
See Also
7.6 vTextEditor
A complete text editing canvas pane.
Synopsis
Description
...
// The Text Editor Canvas
vedCanvas = new vedTextEditor(this);
AddPane(vedCanvas);
...
// Show Window
ShowWindow();
vedCanvas->ShowVScroll(1); // Show Vert Scroll for vTextEditor
...
Your derived 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.) 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 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
vTextEditor worry about the buffering.
//===================>>> 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;
}
To load text into the editor buffer,
you first call resetBuff to initialize the
buffer, then add a line at a time with calls to addLine,
and finally display the text by calling displayBuff.
Constructor
vTextEditor(vBaseWindow* parent)
The vTextEditor constructor requires that you specify
the parent vCmdWindow. Since you usually create the text editor object
in your vCmdWindow object, this is easy. You will probably need
to cast the this to a vBaseWindow*.
Utility Methods
resetBuff()
Before you load new text into the buffer, you must first
call this method. It initializes the internal state of
the text buffer.
virtual int addLine(char* line)
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.
virtual void displayBuff()
After you have added the complete file, call displayBuff
to display the text in the window.
virtual int getLine(char* line, int maxChars, long
lineNum)
virtual int getFirstLine(char* line, int maxChars)
virtual int getNextLine(char* line, int maxChars)
These are used to retrieve the edited text from the buffer.
You can use getFirstLine with getNextLine for
easy sequential retrieval, or getLine for specific
lines. These methods return -1 when all lines have been
recovered.
virtual int EditCommand(int id, long val)
This method provides a complete interface to the functions
provided by vTextEditor. While the basic
editing functions are also handled by EditKeyIn,
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.
For a basic editor, the simplest way to use EditCommand
is to use the ed* id's to define the associated menu
items and controls, and then call EditCommand as the
default case of the switch in the WindowCommand
method of your vCmdWindow. Thus, you might have
code that looks like this:
...
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);
}
virtual int EditKeyIn(vKey key, unsigned int shift)
This method is usually called from the KeyIn method
of your derived vCmdWindow class. See the above code
example.
edState GetEdState()
void SetEdState()
VTextEditor maintains a state structure with relevant state
information associated with various operating options of vTextEditor. It is
defined in v/vtexted.h, and has the following fields:
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;
You can query and set the state with GetEdState and
SetEdState.
long GetLines()
Returns the number of lines in the current buffer.
Methods to Override
virtual void ChangeLoc(long line, int col)
This method is called by vTextEditor whenever the current line
or current column is changed. This information could be displayed
on a status bar, for example.
virtual void ChangeInsMode(int IsInsMode)
This method is called by vTextEditor whenever the
insert mode is changed. If 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.
virtual void StatusMessage(char* Msg)
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.
virtual void ErrorMessage(char* Msg)
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.
See Also
7.7 vBaseGLCanvasPane
A specialized base class to support OpenGL graphics.
Synopsis
Description
Constructor
vBaseGLCanvasPane(unsigned int vGLmode)
The vBaseGLCanvasPane constructor allows you to specify
certain attributes of the visual used by OpenGL. The options,
which can be ORed together, include:
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 vGL_Default mode works well
for many OpenGL applications.
Utility Methods
VCursor GetCursor()
Returns the id of the current cursor being used in the canvas.
See SetCursor.
virtual int GetHeight()
Returns the height of the current drawing canvas in pixels.
virtual int GetHScroll(int& Shown, int& Top)
Get the status of the Horizontal Scroll bar. Returns 1 if the
scroll bar is displayed, 0 if not. Returns in Shown and
Top the current values of the scroll bar. See SetVScroll
for a description of the meanings of parameters.
virtual int GetVScroll(int& Shown, int& Top)
Get the status of the Vertical Scroll bar. See
GetHScroll for details.
virtual int 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.
void SetCursor(VCursor id)
This method sets the cursor displayed while the mouse in
in the current canvas area.
See the description of vCanvasPane for details.
void SetWidthHeight(int width, int height)
This will set the size of the drawing canvas to height
and width in pixels. It will also cause a Resize
event message to be sent to the window.
virtual void SetHScroll(int Shown, int Top)
Set the horizontal scroll bar
See the description of vCanvasPane for details.
virtual void SetVScroll(int Shown, int Top)
Set the vertical scroll bar.
See the description of vCanvasPane for details.
virtual void ShowHScroll(int OnOrOff)
virtual void ShowVScroll(int OnOrOff)
See the description of vCanvasPane for details.
Methods to Override
virtual void HPage(int Shown, int Top)
When the user moves the horizontal scroll bar, it generates an
HPage event.
See the description of vCanvasPane for details.
virtual void HScroll(int step)
This method is called when the user enters a single step command
to the scroll bar.
See the description of vCanvasPane for details.
virtual void MouseDown(int x, int y, int button)
This is called when the user clicks a button on the mouse.
virtual void MouseMotion(int x, int y)
This is called when the mouse moves while a button is
not
pressed.
See the description of vCanvasPane for details.
virtual void MouseMove(int x, int y, int button)
This is called when the mouse moves while a button is pressed.
See the description of vCanvasPane for details.
virtual void MouseUp(int x, int y, int button)
This is called when the user releases the mouse button.
See the description of vCanvasPane for details.
virtual void Redraw(int x, int y, int width, int height)
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.
virtual void Resize(int newW, int newH)
A Resize event is generated when the user changes the
size of the canvas using the resize window command provided
by the host windowing system.
virtual void VPage(int Shown, int Top)
See the description of vCanvasPane for details.
virtual void VScroll(int step)
See the description of vCanvasPane for details.
Specific OpenGL methods
virtual void graphicsInit(void)
This method is called after the OpenGL drawing canvas has
been created, and
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.
void vglMakeCurrent(void)
This method should be called by your program before you
call any OpenGL drawing code. Normally, this is called
first thing in 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.
virtual void vglFlush(void)
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
Redraw method.
virtual XVisualInfo* GetXVisualInfo()
This method is specific to X, and will return a pointer to the
XVisualInfo structure currently being used. There will
be an equivalent method available for MS-Windows.
Tutorial
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
}
....
Note that this example includes a method called 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 v/opengl directory for
a complete example of animation using the timer.
See Also
7.8 vColor
A class for handling and specifying colors.
Synopsis
Description
Constructor
vColor(unsigned int rd 0, unsigned int gr = 0, unsigned int
bl = 0)
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.
// 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
};
Utility Methods
BitsOfColor()
ResetColor(unsigned int rd = 0, unsigned int gr = 0,
unsigned int bl = 0)
ResetColor(vColor& c)
Like the 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 ResetColor.
You can also pass a vColor object.
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
}
...
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.
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
}
...
This example accomplishes the same as the first, but does not use
up color map entries. Instead, the entry used for 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 ResetColor will minimize the number of color map accesses.
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
Set(unsigned int rd = 0, unsigned int gr = 0, unsigned int bl = 0)
void SetR(unsigned int rd = 0)
Set the Red value.
void SetG(unsigned int gr = 0)
Set the Green value.
void SetB(unsigned int bl = 0)
Set the Blue value.
unsigned int r()
unsigned int g()
unsigned int b()
int operator ==
int operator !=
Notes about color
See Also
7.9 vDC
This is the base class that defines all the drawing methods provided
by the various drawing canvases.
Synopsis
Description
Utility Methods
virtual void BeginPage()
Supported by printer canvases. Call to specify a page is
beginning. Bracket pages with BeginPage and EndPage
calls.
virtual void BeginPrinting()
Required by printer canvases. Call to specify a document is
beginning. You
must bracket documents with BeginPrinting
and EndPrinting calls. BeginPrinting includes an
implicit call to BeginPage.
virtual void Clear()
Clear the canvas to the background color. No op on printers.
virtual void ClearRect(int x, int y, int width, int height)
Clear a rectangular area starting at x,y of height and width. No
op on printers.
void CopyFromMemoryDC(vMemoryDC* memDC, int destX, int
destY, int srcX = 0, int srcY = 0, int srcW = 0, int srcH = 0)
This method is used to copy the image contained in a vMemoryDC
to another drawing canvas. The parameter memDC specifies
the vMemoryDC object, and destX and destY
specify where the image is to be copied into this drawing
canvas (which will usually be 0,0). If you use the default
values for srcX=0, srcY=0, srcW=0, and
srcH=0, the entire source canvas will be copied.
virtual void DrawAttrText(int x, int y, char* text, const
ChrAttr attr)
Draw text using the current font with specified attributes at
given x, y.
virtual void DrawColorPoints(int x, int y, int nPts, vColor*
pts)
Draw an array of nPts 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, DrawColorPoints will be significantly faster
than separate calls to DrawPoint.
virtual void DrawEllipse(int x, int y, int width, int
height)
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.
virtual void DrawIcon(int x, int y, vIcon& icon)
A 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.
virtual void DrawLine(int x, int y, int xend, int yend)
Draw a line from x,y to xend,yend.
The current Pen will be used to draw the line.
virtual void DrawLines(vLine* lineList, int count)
Draws the count lines contained in the list lineList.
typedef struct vLine
{
short x, y, xend, yend;
} vLine;
virtual void DrawLines(vPoint* points, int count)
Draws the count lines defined by the list of endpoints points.
This is similar to drawing with a line list. The value of count
must be 2 or greater. (New in version 1.19)
virtual void DrawPoint(int x, int y)
Draw a point at x,y using the current Pen.
virtual void DrawPoints(vPoint* pointList, int count)
Draws the count points contained in the list pointList.
typedef struct vPoint
{
short x, y;
} vPoint;
virtual void DrawPolygon(int n, vPoint points[],
int fillMode = vAlternate)
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.
typedef struct vPoint // a point
{
short x, y; // X version
} vPoint;
virtual void DrawRoundedRectangle(int x, int y, int width,
int height, int radius = 10)
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.
virtual void DrawRectangle(int x, int y, int width,
int height)
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.
virtual void DrawRectangles(vRect* rectList, int count)
Draw a list of count vRect rectangles pointed to by
the list rectList.
The current Pen will be used to draw the rectangles, and the
current Brush will be used to fill the rectangles.
typedef struct vRect
{
short x, y, w, h;
} vRect;
virtual void DrawRubberLine(int x, int y, int xend, int yend)
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 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.
virtual void DrawRubberEllipse(int x, int y, int width,
int height)
Draw a rubber-band Ellipse. See DrawRubberLine.
virtual void DrawRubberPoint(int x, int y)
Draw a rubber-band point. See DrawRubberLine.
virtual void DrawRubberRectangle(int x, int y, int width,
int height)
Draw a rubber-band rectangle. See DrawRubberLine.
virtual void DrawText(int x, int y, char* text)
Simple draw text at given x, y using the current font and
current pen. Unlike icons and other
V drawing objects,
x and y represent the lower left corner of the
first letter of the text. Using a vSolid pen results
in the text being drawn in with the pen's color using
the current background color. Using a vTransparent
pen results in text in the current color, but just drawing
the text over the current canvas colors. (See vPen::SetStyle.)
virtual void EndPage()
Supported by printer canvases. Call to specify a page is
ending. Bracket pages with BeginPage and EndPage
calls.
virtual void EndPrinting()
Supported by printer canvases. Call to specify a document is
ending. Bracket documents with BeginPrinting and
EndPrinting calls. EndPrinting includes
an implicit call to EndPage.
virtual vBrush GetBrush()
Returns a copy of the current brush being used by the canvas.
virtual vFont GetFont()
Returns a copy of the current font of the drawing canvas.
virtual vBrush GetPen()
Returns a copy of the current pen being used by the canvas.
virtual int GetPhysHeight()
Returns the maximum physical y value supported by the
drawing canvas. Especially useful for determining scaling
for printers.
virtual int GetPhysWidth()
Returns the maximum physical x value supported by the
drawing canvas. Especially useful for determining scaling
for printers.
virtual void GetScale(int& mult, int& div)
Returns the scaling factors for the
canvas. See SetScale.
void GetTranslate(int& x, int& y)
int GetTransX()
int GetTransY()
Returns the current x and y translation values.
virtual void SetBackground(vColor& color)
This sets the background of the drawing canvas to the
specified color.
virtual void SetBrush(vBrush& brush)
This sets the brush used by the drawing canvas. Brushes are used
for the filling methods such as vDrawPolygon. It is
important to call SetBrush whenever you change any
attributes of a brush used by a drawing canvas.
virtual void SetFont(vFont& vf)
Change the font associated with this canvas. The default method
handles changing the font and calls the FontChanged method for
the canvas pane.
virtual void SetPen(vPen& pen)
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 SetPen whenever you change any attributes of
a pen used by a drawing canvas.
virtual void SetScale(int mult, int div)
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.
void SetTranslate(int x, int y)
void SetTransX(int x)
void SetTransY(int y)
These methods set the internal translation used by the
drawing canvas. Each coordinate sent to the various
drawing methods (e.g., 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.
int TextHeight(int& ascent, int& descent)
This function returns the total height of the font fontId.
The total height of the font is the sum of the ascent and
descent heights of the font fontId. Each character
ascends ascent pixels above the Y coordinate where it is
being drawn, and descent pixels below the Y coordinate.
int TextWidth(char* str)
Returns the width in pixels or drawing points of the string
str using the currently set font of the canvas.
7.10 vMemoryDC
A memory drawing canvas.
Synopsis
Description
Methods
vMemoryDC(int width, int height)
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
Redraw events, then it should be initialized to be
big enough to repaint whatever you will be drawing on the
physical screen. The methods vApp::ScreenWidth() and
vApp::ScreenHeight() can be used to obtain the maximum
size of the physical screen.
7.11 vPen
A class to specify the pen used to draw lines and shapes.
Synopsis
Description
Methods
vPen(unsigned int r = 0, unsigned int g = 0, unsigned int b = 0,
int width = 1, int style = vSolid)
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.
int operator ==, !=
vColor GetColor()
This method returns the current color of the pen as a vColor object.
int GetStyle()
This method returns the current style of the pen.
void GetWidth()
This gets the width of the line the pen will draw.
void SetColor(vColor& c)
You can use this method to set the pen color by passing
in a vColor object.
void SetStyle(int style)
This method is used to change the style of a pen. Styles include:
void SetWidth(int width)
This sets the width of the line the pen will draw.
7.12 vPrintDC
A printer drawing canvas.
Synopsis
Description
Methods
void SetPrinter(vPrinter& printer)
This method is used to associate a vPrinter with
a vPrintDC.
By default, a vPrintDC represents standard
8.5x11 inch Letter paper printed in black and white in
portrait orientation. You can use vPrinter::Setup to allow
the user to change the attributes of the printer, then use
SetPrinter to associate those attributes with the vPrintDC.
Note: If you change the default printer attributes, you
must
call SetPrinter before doing any drawing to the DC.
Example
//===================>>> 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
...
}
7.13 vPrinter
A printer object, with a dialog to interactively set printer
attributes.
Synopsis
Description
Methods
int GetCopies()
void SetCopies(int s)
Many printers support printing multiple copies of the same
document. This attributes controls the number of copies printed.
The Setup dialog will provide control of this
if it
is supported.
char* 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.
int GetPaper()
char* GetPaperName()
Printers can print a variety of papers. The user may be
able to select which paper from the Setup dialog.
The printers supported are defined in the vprinter.h
header file (or the base class used by vPrinter).
int GetPortrait()
void SetPortrait(int p)
Many printers can print in either Portrait or Landscape orientation.
This returns true if the printer will print in portrait.
int GetToFile()
void SetToFile(int f)
int GetUseColors()
void SetUseColors(int c)
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.
int Setup(char* fn = 0)
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 Setup returns false, you should abandon the
print job. After you call Setup, you can then
call vPrintDC::SetPrinter to associate the printer
with the vPrintDC.
Example
7.14 vTextCanvasPane
A class for drawing text on a canvas.
Synopsis
Description
New Methods
void ClearRow(const int row, const int col)
This clears to blanks row row of the screen from
column col to the end of the line.
void ClearToEnd(const int row, const int col)
This clears to blanks from row row and column col
to the end of the screen.
int GetCols()
Returns number of columns in current text canvas.
int GetRows()
Returns number of rows in current text canvas.
void GetRC(int& row, int& col)
Returns in row and col the current row and
column of the text cursor.
void GotoRC(const int row ,const int row)
Moves the text cursor to row,col.
void DrawAttrText(const char* text, const ChrAttr attr)
Draws text starting at the current cursor location using
text attribute attr. For more details, see vDC::DrawAttrText.
void DrawChar(const char chr, const ChrAttr attr)
Draws a single character chr at the current
cursor location using text attribute attr. See
DrawAttrText for more details.
void DrawText(const char* text)
Draws text starting at the current cursor location.
The newline character '\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.
void HideTextCursor(void)
This method will hide the text cursor.
void ShowTextCursor(void)
This method will redisplay the text cursor at the current
row and column.
void ScrollText(const int count)
This will scroll the text in the text canvas up or down by
count lines. There will be count blank lines
created at the bottom or top of the screen.
void ResizeText(const int rows, const int cols)
This method handles resize events. You will want to override
this to track the new number of rows and columns.
void TextMouseDown(int row, int col, int button)
This is called when the user clicks the mouse button down.
It is called with the text row and column, and the button number.
void TextMouseUp(int row, int col, int button)
This is called when the user releases the mouse button.
It is called with the text row and column, and the button number.
void TextMouseMove(int row, int col, int button)
This is called when the mouse moves.
It is called with the text row and column, and the button number.
Derived Methods
virtual void Clear()
This clears the text canvas and resets the row and column
to 0,0.
void FontChanged(int)
This is called when the font of the canvas changes.
FontChanged calls ResizeText, so you probably
won't have to deal with this event.
void Redraw(int x, int y, int width, int height)
Called when the screen needs to be redrawn. Normally, you won't
have to override this class since the vTextCanvasPane
superclass will handle redrawing what is in the window. Instead,
you will usually just have to respond to the FontChanged
and ResizeText events when the contents of the canvas will
actually change.
Inherited Methods
virtual void HPage(int Shown, int Top)
virtual void HScroll(int step)
virtual void SetFont(int vf)
virtual void SetHScroll(int Shown, int Top)
virtual void SetVScroll(int Shown, int Top)
virtual void VPage(int Shown, int Top)
virtual void VScroll(int step)
See Also
[Table of Contents]
[Previous Chapter]
[Next Chapter]
[Object Central Home]