# vCanvasPane

A base class to build graphical and text canvas panes.

## Synopsis

Header:
  `<v/vcanvas.h>`
Class name:
  vCanvasPane
Hierarchy:
  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 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:

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

## See Also

vTextCanvasPane