VCanvasPane

A base class to build graphical and text canvas panes.

Synopsis

Header:: [vquickr.htm#vCanvasPane <v/vcanvas.h>]
Class name:: vCanvasPane
Hierarchy:: [vpane.htm vPane] ->vCanvasPane

Description

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.

Utility Methods

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

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

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

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.

vWindow* GetPaneParent()

Returns a pointer to the parent vWindow of the canvas pane.

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 is 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:

VC_Arrow: The standard arrow cursor.
VC_CenterArrow: An upward point arrow.
VC_CrossHair: A cross hair cursor.
VC_EWArrows: Double ended horizontal arrows (EastWest).
VC_Hand: A hand with a pointing finger (NOT ON WINDOWS).
VC_IBar: An I bar cursor.
VC_Icon: A cursor representing an icon.
VC_NSArrows: Double ended vertical arrows (NorthSouth).
VC_Pencil: A pencil (NOT ON WINDOWS).
VC_Question: A question mark cursor (NOT ON WINDOWS).
VC_Sizer: The cursor used for sizing windows.
VC_Wait: A cursor that symbolizes waiting, usually an hour glass.
VC_X: An X shaped cursor (NOT ON WINDOWS).

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.

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.

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.

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.

Platform Dependent

If you simply must access the native window for low level drawing, V provides a couple of platform dependent functions that can sometimes help. Be warned that your code will then be platform dependent.

Methods for MS-Windows

HWND DrawingWindow()

This returns the HWND of the drawing window of the current canvas. This is then used to get a DC as needed. For example:

....

    // Assume mycanvas is a pointer to your canvas pane.
    // Call DrawingWindow to get the HWND used by canvas
    HWND drawingWindow = mycanvas->DrawingWindow();

    // Now use that HWND to call the native Windows GetDC to get a DC
    HDC myHDC = ::GetDC(drawingWindow);

   // use myHDC to do drawing....
   // note that you will need to use native Windows drawing calls here,
   // and not use V drawing functions. You can use V stuff IF you
   // first release the DC, call the V code, and then get your
   // own DC again. But since you are really using the DC in a native
   // way, why use V at all for the drawing part at this point?
   // The V GUI stuff will still work fine.

   .... // your drawing code here

   // IMPORTANT! When done drawing, youj must release the DC
   ::ReleaseDC(drawingWindow, myHDC);

Methods for X

Widget DrawingWindow()

This returns the X Widget used by the canvas.

Drawable GetXDrawable()

This returns the X Drawable used by the canvas.

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.

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.

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.

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.

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.

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

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.