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