Using the VSDraw Control

The VSDraw control allows you to create scaleable graphics. The graphics are vector-based, so they are very small compared to bitmaps, and can be scaled without loss of resolution. Typical uses for the VSDraw control include creating custom charts that can be embedded in VSPrinterdocuments, maps, and technical diagrams.

The VSDraw control is based on Windows metafiles. This means the control inherits certain limitations from the Windows metafile format. These include limits on coordinates, which must be in the range from -32768 to 32767, and relatively coarse control over text formatting and dimensioning. The shortcomings are compensated by the portability, small size, and scalability of the graphics created.

The diagram below shows the basic sequence of steps required to create a drawing using the VSDraw control:

As the diagram shows, there are five main steps to using the VSDraw control.

Set Drawing Scale

The drawing scale defines the coordinate system that will be used for drawing. It affects the placement of graphics and text on the drawing.

Before creating a drawing, you should choose the units you want to use, the extent of the drawing, and which direction is positive (up or down, left or right). You can change the scaling at any time, but choosing the right coordinate system from the start can simplify your drawing code a lot.

Defining the scale in the VSDraw control is similar defining the scale in a VB PictureBox control. It is done with four properties: ScaleWidth, ScaleHeight, ScaleLeft, and ScaleTop.

ScaleWidth defines the horizontal extent of the drawing. If it is positive, coordinates grow from left to right. If it is negative, coordinates grow from right to left. ScaleLeft defines the coordinate of the left edge of the control.

ScaleHeight defines the vertical extent of the drawing. If it is positive, coordinates grow from top to bottom. If it is negative, coordinates grow from bottom to top. ScaleTop defines the coordinate of the top edge of the control.

For example, the diagram below shows two typical ways to set up the control's coordinate system: with the vertical axis pointing down and up:

The VSDraw tutorial in this manual (see the Tutorials section) provides an interesting example of defining a coordinate system that makes drawing charts easy. The scaling is set up so that the chart portion will be contained in a rectangle from points (0,0) to (1000,1000). Some extra space is provided around the edges of this area for labels and titles. Here is how this is done:

Example Title	Copy Code
' horizontal extent = 1300 units: ' 1000 for the chart, plus 300 units for edges vd.ScaleWidth = 1300 ' left = -200: ' this leaves a 200 unit edge on the left, ' and a 100 unit edge on the right vd.ScaleLeft = -200 ' vertical extent = -1300 units: ' 1000 for the chart, plus 300 units for edges ' negative means coordinates grow from bottom vd.ScaleHeight = -1300 ' top = 1100 ' this leaves a 100 unit edge on the top, ' and a 200 unit edge along the bottom vd.ScaleTop = 1100

Example Title

Copy Code

' horizontal extent = 1300 units:

' 1000 for the chart, plus 300 units for edges

vd.ScaleWidth = 1300

' left = -200:

' this leaves a 200 unit edge on the left,

' and a 100 unit edge on the right

vd.ScaleLeft = -200

' vertical extent = -1300 units:

' 1000 for the chart, plus 300 units for edges

' negative means coordinates grow from bottom

vd.ScaleHeight = -1300

' top = 1100

' this leaves a 100 unit edge on the top,

' and a 200 unit edge along the bottom

vd.ScaleTop = 1100

With this scaling system, drawing the chart becomes pretty easy. For example, the following code draws a frame for the chart:

Example Title	Copy Code
vd.Clear vd.BrushStyle = bsTransparent vd.DrawRectangle 0, 0, 1000, 1000

Note that all scaling properties must be in the range from -32,768 to 32,767. This is a limitation imposed by Windows metafiles.

Set PageSize

This step is optional. With VSDraw 8, you can specify a physical size for the drawing. If you do, the control will preserve the aspect ratio of the drawing, avoiding distortions when the control is resized. The VSDraw control will also create and manage scrollbars and support zooming, just like the VSPrinter control in preview mode.

The picture below shows a drawing with no physical dimensions (which stretches to fill the control), and one with physical dimensions set by the programmer. Notice how the second preserves the aspect ratio of the drawing.

To set the physical page size, choose the drawing dimensions, convert them to twips, and assign the values to the PageWidth and PageHeight properties (or use the SetPageExtent method to set both properties at once). For example, to create a drawing two inches wide and 1.5 inches tall, you could write:

Example Title	Copy Code
vd.SetPageExtent 2 * 1440, 1.5 * 1440

Start Document

This is easy to do: just call the SetPageExtent method. It is always good policy to call this method before starting a drawing, just to make sure you have a clean slate.
Generate Document

This is the main part of the process. Here you will use the DrawLine, DrawRectangle, DrawCircle, Text, and other properties and methods that generate the actual drawing.
Preview/Print/Save Document

At this point, the drawing is ready to be used. You may simply let the user look at it, provide zooming and panning, save the document to disk with the SaveDoc method (which saves a Windows metafile), include the drawing in other documents (by copying its Pictureproperty), or send it to the printer using the PrintDoc method.