# Programming with Canvas Controls

Drawing on a Canvas

You can draw a variety of shapes, text and images on a canvas control. Refer to Canvas Control Functions for a comprehensive list of the drawing functions you can use on a canvas control.

CanvasScroll scrolls the contents of a rectangular area of the canvas control.

CanvasDimRect overlays a checkerboard pattern in a rectangular area.

CanvasInvertRect inverts the colors in a rectangular area.

CanvasClear restores a rectangular area to the canvas background color.

Batch Drawing

Although you can call the drawing functions at any time, they are most efficient when you call them from within a batch drawing operation. A batch drawing operation consists of the following steps:

1. A call to CanvasStartBatchDraw
2. One or more calls to the canvas drawing functions
3. A call to CanvasEndBatchDraw

For optimal performance, include as many drawing primitives as possible within a batch drawing operation. When you call a drawing function outside of a batch operation, LabWindows/CVI implicitly surrounds the function call with calls to CanvasStartBatchDraw and CanvasEndBatchDraw.

Canvas Coordinate System

A canvas has a built-in pixel-based Cartesian coordinate system, where (0,0) represents the top, left corner of the canvas. You perform all drawing relative to this coordinate system. You can modify the coordinate system using the following four attributes of SetCtrlAttribute:

ATTR_XCOORD_AT_ORIGIN

ATTR_YCOORD_AT_ORIGIN

ATTR_XSCALING

ATTR_YSCALING

All canvas control functions use this coordinate system, except for CanvasGetPixel and CanvasGetPixels, which use unscaled pixel coordinates rather than the canvas coordinate system.

Off-Screen Bitmap

Each canvas has an off-screen bitmap that LabWindows/CVI uses to restore the appearance of the canvas whenever you cover and then re-expose a region. You can choose to draw directly to the screen, bypassing the off-screen bitmap. If you draw to the off-screen bitmap, you can choose whether to update the screen immediately or wait until draw events are processed. You use the ATTR_DRAW_POLICY attribute to control this behavior.

CanvasUpdate immediately copies the canvas off-screen bitmap to the screen, within a specified rectangular area.

The ATTR_OVERLAPPED_POLICY attribute controls what occurs when you draw to a canvas which is overlapped by another control.

Clipping

The drawing functions are constrained by the clipping set that you define with CanvasSetClipRect. Any drawing outside the clipping rectangle is not rendered. To obtain the current clipping rectangle, you call CanvasGetClipRect.

Background Color

The ATTR_PICT_BGCOLOR attribute controls the background color of the canvas. When you change ATTR_PICT_BGCOLOR, the entire canvas area is cleared.

Pens

Each canvas has a pen. You use SetCtrlAttribute to individually set the following canvas pen attributes:

ATTR_PEN_WIDTH

ATTR_PEN_STYLE

ATTR_PEN_COLOR

ATTR_PEN_FILL_COLOR

ATTR_PEN_MODE

ATTR_PEN_PATTERN

CanvasDefaultPen resets all these attributes to their default values.

The location of the pen affects the starting position of the line drawn by CanvasDrawLineTo. Only CanvasSetPenPosition and CanvasDrawLineTo affect the location of the pen. You call CanvasGetPenPosition to obtain the location of the pen.

Pixel Values

You can obtain the color values of pixels in the canvas. Call CanvasGetPixel to obtain the color of one pixel. Call CanvasGetPixels to obtain the values of the pixels within a rectangular area. You obtain the color values from the off-screen bitmap, not the screen.

Unlike other canvas control functions, CanvasGetPixel and CanvasGetPixels use unscaled pixel coordinates rather than the canvas coordinate system.