This chapter covers classes and utility functions needed to draw text and graphics.
The classes and objects covered in this chapter include:
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.
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.
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.
Various screen fonts are available in V .
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.
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. Currently, underlining does not work for X screens.
The constructor is used to declare a font with the specified family, size, style, weight, and underline.
Returns the family of the font object.
Returns the point size of the font object.
Returns the style of the font object.
Returns the weight of the font object.
Returns the underline setting of the font object.
Changes the attributes of the font object. For example, the font selection dialog uses this method to change the font attributes.
A class to specify the brush used to fill shapes.
Brushes are used to fill shapes. Brushes have two attributes, including color and style.
The brush constructor allows you to set the initial color and style of the brush. The default constructs a solid black brush.
You can use the operators == and != for comparisons.
This method returns the current color of the brush as a vColor object.
This method returns the fill mode of the brush (either vAlternate or vWinding).
This method returns the current style of the brush.
You can use this method to set the brush color by passing in a vColor object.
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.
This method is used to set the style of the brush. Brush styles include:
The drawing canvas class for CanvasPanes.
This class is normally automatically used by the vCanvasPane class. It provides the actual implementation of the screen drawing canvas class.
A base class to build graphical and text canvas panes.
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.
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().
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().
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.
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.
Returns the id of the current cursor being used in the canvas. See SetCursor.
Returns the height of the current drawing canvas in pixels.
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.
Get the status of the Vertical Scroll bar. See GetHScroll for details.
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.
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:
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.
Set the horizontal scroll bar. See SetVScroll for a description of the parameters.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The default Resize in vBaseGLCanvasPane is a no-op, and your subclass needs to override Redraw.
See HPage.
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.
vTextCanvasPane
A complete text editing canvas pane.
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 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.
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 **.
//===================>>> 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.
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.
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*.
Before you load new text into the buffer, you must first call this method. It initializes the internal state of the text buffer.
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 vTextEditor to determine the specifications of the methods you'd need to override.
After you have added the complete file, call displayBuff to display the text in the window.
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.
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.
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.
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);
}
This method is usually called from the KeyIn method of your derived vCmdWindow class. See the above code example.
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.
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.
Returns the number of lines in the current buffer.
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.
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.
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.
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.
vTextCanvasPane
A specialized base class to support OpenGL graphics.
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.
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.
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.
Returns the id of the current cursor being used in the canvas. See SetCursor.
Returns the height of the current drawing canvas in pixels.
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.
Get the status of the Vertical Scroll bar. See GetHScroll for details.
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.
This method sets the cursor displayed while the mouse in in the current canvas area. See the description of vCanvasPane for details.
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.
Set the horizontal scroll bar See the description of vCanvasPane for details.
Set the vertical scroll bar. See the description of vCanvasPane for details.
See the description of vCanvasPane for details.
When the user moves the horizontal scroll bar, it generates an HPage event. See the description of vCanvasPane for details.
This method is called when the user enters a single step command to the scroll bar. See the description of vCanvasPane for details.
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 vCanvasPane for details.
This is called when the mouse moves while a button is not pressed. See the description of vCanvasPane for details.
This is called when the mouse moves while a button is pressed. See the description of vCanvasPane for details.
This is called when the user releases the mouse button. See the description of vCanvasPane for details.
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 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.
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.
The default Resize in vBaseGLCanvasPane is a no-op, and your subclass needs to override Redraw.
See the description of vCanvasPane for details.
See the description of vCanvasPane for details.
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.
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.
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.
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.
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.
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.
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.
vCanvasPane
A class for handling and specifying colors.
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 
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.
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
};
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.
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.
Consider the following code excerpt:
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.
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:
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 all three values of the color at once.
Set the Red value.
Set the Green value.
Set the Blue value.
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 
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
This is the base class that defines all the drawing methods provided by the various drawing canvases.
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.
Supported by printer canvases. Call to specify a page is beginning. Bracket pages with BeginPage and EndPage calls.
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.
Clear the canvas to the background color. No op on printers.
Clear a rectangular area starting at x,y of height and width. No op on printers.
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.
Beginning with V release 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.
Draw text using the current font with specified attributes at given x, y.
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.
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.
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.
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.
Draw a line from x,y to xend,yend. The current Pen will be used to draw the line.
Draws the count lines contained in the list lineList.
The current Pen will be used to draw the lines.
The type vLine is defined in v_defs.h as:
typedef struct vLine
{
short x, y, xend, yend;
} vLine;
Draw a point at x,y using the current Pen.
Draws the count points contained in the list pointList.
The current Pen will be used to draw the points.
The type vPoint is defined in v_defs.h as:
typedef struct vPoint
{
short x, y;
} vPoint;
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, vAlternate or vWinding. These algorithms correspond to the equivalent algorithms on the native platforms.
The type vPoint is defined in v_defs.h as:
typedef struct vPoint // a point
{
short x, y; // X version
} vPoint;
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.
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.
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.
The type vRect is defined in v_defs.h as:
typedef struct vRect
{
short x, y, w, h;
} vRect;
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.
Draw a rubber-band Ellipse. See DrawRubberLine.
Draw a rubber-band point. See DrawRubberLine.
Draw a rubber-band rectangle. See DrawRubberLine.
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.)
Supported by printer canvases. Call to specify a page is ending. Bracket pages with BeginPage and EndPage calls.
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.
Returns a copy of the current brush being used by the canvas.
Returns a copy of the current font of the drawing canvas.
Returns a copy of the current pen being used by the canvas.
Returns the maximum physical y value supported by the drawing canvas. Especially useful for determining scaling for printers.
Returns the maximum physical x value supported by the drawing canvas. Especially useful for determining scaling for printers.
Returns the scaling factors for the canvas. See SetScale.
Returns the current x and y translation values.
This sets the background of the drawing canvas to the specified color.
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.
Change the font associated with this canvas. The default method handles changing the font and calls the FontChanged method for the canvas pane.
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.
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.
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.
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.
Returns the width in pixels or drawing points of the string str using the currently set font of the canvas.
A memory drawing canvas.
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 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.
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.
A class to specify the pen used to draw lines and shapes.
Pens are used to draw lines and the outlines of shapes. Pens have several attributes, including color, width, and style.
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.
You can use the operators == and != for comparisons.
This method returns the current color of the pen as a vColor object.
This method returns the current style of the pen.
This gets the width of the line the pen will draw.
You can use this method to set the pen color by passing in a vColor object.
This method is used to change the style of a pen. Styles include:
This sets the width of the line the pen will draw.
A printer drawing canvas.
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 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.
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.
//===================>>> 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
...
}
A printer object, with a dialog to interactively set printer attributes.
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.
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.
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.
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).
Many printers can print in either Portrait or Landscape orientation. This returns true if the printer will print in portrait.
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.
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.
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.
See vPrintDC for an example of using vPrinter::Setup.
A class for drawing text on a canvas.
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.
This clears to blanks row row of the screen from column col to the end of the line.
This clears to blanks from row row and column col to the end of the screen.
Returns number of columns in current text canvas.
Returns number of rows in current text canvas.
Returns in row and col the current row and column of the text cursor.
Moves the text cursor to row,col.
Draws text starting at the current cursor location using text attribute attr. For more details, see vDC::DrawAttrText.
Draws a single character chr at the current cursor location using text attribute attr. See DrawAttrText for more details.
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.
This method will hide the text cursor.
This method will redisplay the text cursor at the current row and column.
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.
This method handles resize events. You will want to override this to track the new number of rows and columns.
This is called when the user clicks the mouse button down. It is called with the text row and column, and the button number.
This is called when the user releases the mouse button. It is called with the text row and column, and the button number.
This is called when the mouse moves. It is called with the text row and column, and the button number.
This clears the text canvas and resets the row and column to 0,0.
This is called when the font of the canvas changes. FontChanged calls ResizeText, so you probably won't have to deal with this event.
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.
vCanvasPane, vWindow