# vDC

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

## Synopsis

Header:
  `<v/vdc.h>`
Class name:
  vDC

## Description

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: `vCanvasPaneDC`, `vMemoryDC`, `vPrintDC`, and Drawing.

## 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.

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.

#### 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.

`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.

#### 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`.

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;

#### 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)

The current Pen will be used to draw the lines.

#### 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`.

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;

#### 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.

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;

#### 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.

The type `vRect` is defined in `v_defs.h` as:

        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.