VSPrint 7

ComponentOne
VSView8
Copyright  1987-2012 GrapeCity, Inc. All rights reserved.
ComponentOne, a division of GrapeCity

201 South Highland Avenue, Third Floor
Pittsburgh, PA 15206 • USA
Internet: [email protected]
Web site: http://www.componentone.com
Sales
E-mail: [email protected]
Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)
Trademarks
The ComponentOne product name is a trademark and ComponentOne is a registered trademark of GrapeCity, Inc. All other
trademarks used herein are the properties of their respective owners.
Warranty
ComponentOne warrants that the original CD (or diskettes) are free from defects in material and workmanship, assuming
normal use, for a period of 90 days from the date of purchase. If a defect occurs during this time, you may return the defective
CD (or disk) to ComponentOne, along with a dated proof of purchase, and ComponentOne will replace it at no charge. After
90 days, you can obtain a replacement for a defective CD (or disk) by sending it and a check for $25 (to cover postage and
handling) to ComponentOne.
Except for the express warranty of the original CD (or disks) set forth here, ComponentOne makes no other warranties, express
or implied. Every attempt has been made to ensure that the information contained in this manual is correct as of the time it was
written. We are not responsible for any errors or omissions. ComponentOne’s liability is limited to the amount you paid for the
product. ComponentOne is not liable for any special, consequential, or other damages for any reason.
Copying and Distribution

While you are welcome to make backup copies of the software for your own use and protection, you are not permitted to make
copies for the use of anyone else. We put a lot of time and effort into creating this product, and we appreciate your support in
seeing that it is used by licensed users only.
This manual was produced using ComponentOne Doc-To-Help™.

Table of Contents
Overview ........................................................................................................................................................ 3
Product Profile ............................................................................................................................................... 3
Installing VSView 8.0 for ActiveX ................................................................................................................. 4
SetUp Files ....................................................................................................................................... 4
Upgrading from VSView7 ................................................................................................................ 4
Installing Demonstration Versions ................................................................................................... 4
Uninstalling VSView8 ...................................................................................................................... 5
End-User License Agreement ........................................................................................................................ 5
Licensing FAQs ............................................................................................................................................. 5
What is Licensing?............................................................................................................................ 5
How does Licensing Work?.............................................................................................................. 5
Technical Support .......................................................................................................................................... 6
Redistributable Files....................................................................................................................................... 6
Upgrading From Previous Versions ............................................................................................................... 7
Adding the VSView8 Components to the Toolbox........................................................................................ 8
Using ComponentOne ActiveX Controls in the .NET Framework .............................................................. 9
Hints and Troubleshooting .......................................................................................................................... 11
Using the VSPrinter Control........................................................................................................................ 13

VSPrinter Property Groups .......................................................................................................................... 14
Using Unit-Aware Properties ....................................................................................................................... 16
Visual C++ Topics ....................................................................................................................................... 17
Using VSPrinter in MFC projects................................................................................................... 17
Handling ActiveX Optional Parameters in MFC........................................................................... 18
Handling ActiveX Picture Properties in MFC ............................................................................... 18
Dual Interfaces in MFC.................................................................................................................. 19
Using VSPrinter in ATL projects ................................................................................................... 21
Creating Controls Dynamically in ATL......................................................................................... 22
VSPrinter Utilities - VPUtil .......................................................................................................................... 22
Using the VSDraw Control ......................................................................................................................... 23
VSView8 Samples ...................................................................................................................................... 26
iii
Tutorials .................................................................................................................................................... 30
VSPrinter Tutorial - QuickPrinter ................................................................................................................ 30
Step 1: Create the Form.................................................................................................................. 30
Step 2: Opening Files...................................................................................................................... 31
Step 3: Previewing Files.................................................................................................................. 32
Step 4: Printing Files....................................................................................................................... 33
Step 5: Setting up the page and printer ........................................................................................... 34
Step 6: Final touches ...................................................................................................................... 34
VSPrinter Tutorial - Calendar ...................................................................................................................... 35
Step 1: Create the form ................................................................................................................... 35
Step 2: Create the calendar ............................................................................................................. 36
Step 3: Browsing months ................................................................................................................ 40
Step 4: Printing the Calendar.......................................................................................................... 40
Step 5: Exporting to HTML ........................................................................................................... 40
VSDraw Tutorial - Chart.............................................................................................................................. 41
Step 1: Create the Form.................................................................................................................. 41
Step 2: Drawing Pie Charts ............................................................................................................ 42
Step 3: Drawing Bar Charts ............................................................................................................ 45
VSPrinter Examples ..................................................................................................................................... 48
Page n of m ..................................................................................................................................... 49
Shaded Table .................................................................................................................................. 50
Table Formatting ............................................................................................................................ 50
Data-based Tables .......................................................................................................................... 51
Custom NavBar Button .................................................................................................................. 54
Find Text ........................................................................................................................................ 56
Build an Index ................................................................................................................................ 57
Build a Table of Contents ............................................................................................................... 60
Control Reference ...................................................................................................................................... 63

VSPrinter Control ........................................................................................................................................ 63
VSPrinter Properties ....................................................................................................................... 72
VSPrinter Methods ....................................................................................................................... 158
VSPrinter Events .......................................................................................................................... 178
VSDraw Control ........................................................................................................................................ 186
VSDraw Properties ....................................................................................................................... 190
VSDraw Methods ......................................................................................................................... 208
iv
VSDraw Events ............................................................................................................................ 213
VSViewPort Control .................................................................................................................................. 213
VSViewPort Properties ................................................................................................................. 216
VSViewPort Methods ................................................................................................................... 224
VSViewPort Events ...................................................................................................................... 224
VSPDF Control.......................................................................................................................................... 224
VSPDF Properties ........................................................................................................................ 225
VSPDF Methods .......................................................................................................................... 228
v
Product Profile (page 3)
Using the VSPrinter Control (page 13)
Using the VSDraw Control (page 23)
Tutorials (page 30)
1
Overview
Welcome to ComponentOne VSView8, a set of four ActiveX controls designed to support the creation and management
of documents for printing and previewing.
VSView8 is a part of ComponentOne Studio® Enterprise, the largest and most complete component toolset for
developing all layers of Windows, Web, and Mobile applications. You can download a free trial of ComponentOne
Studio Enterprise from our Web site; unlicensed copies will display a ComponentOne banner every time they are loaded
to remind you to license the product. If you like VSView8 and find it useful, you can purchase ComponentOne Studio
Enterprise for a reasonable price.
For additional information on ComponentOne Studio Enterprise, visit our Web site at
http://www.componentone.com.
We are confident that you will like VSView8 for Active X. If you have any suggestions or ideas for new features or tools
that you'd like to see included in a future version please call us or write:
Contact Us
ComponentOne, a division of
GrapeCity
201 South Highland Avenue
3rd Floor
Pittsburgh, PA 15206 • USA
412.681.4343
412.681.4384 (Fax)
http://www.componentone.com
Product Profile
The ComponentOne VSView8 package consists of four custom controls and excellent documentation:
1) VSPrinter
VSPrinter allows you to create documents that can be previewed, printed, and saved to disk. VSPrinter supports multi-
page documents with headers, footers, full character, paragraph, and page formatting, tables, graphics, and pictures. It
also supports HTML and RTF formats, and can be used in a Web browser for accurate previewing of documents
published on your Web site.
2) VSDraw
VSDraw allows you to create complex, scalable images such as charts, diagrams, and maps. The images can be
previewed, saved to disk, and copied to other documents, including VSPrinter documents.
3) VSViewPort
VSViewport allows you to create scrollable areas within your forms so you can fit large (or many small controls) in your
forms. Use it to implement fill-out forms or as an alternative to tab controls.
4) VSPDF8
VSPDF allows you to create and add information to PDF files.
5) Excellent Documentation
VSView8 includes an extensive manual and online help with plenty of tutorials and examples. If you have suggestions
on how we can improve our documentation, please email the Documentation team. Please note that e-mail sent to the
3
Documentation team is for documentation feedback only. Technical Support and Sales issues should be sent directly
to their respective departments.
Installing VSView 8.0 for ActiveX

The following sections provide helpful information on installing VSView8.
SetUp Files
ComponentOne VSView8 can be installed by downloading ComponentOne Studio Enterprise from
www.componentone.com or using the ComponentOne Studio CD and walking through the installation wizard. When
you are prompted, enter your serial number and complete the online registration. You may register any other
ComponentOne products for which you have purchased a serial number at this time as well.
The following files will be installed into your Windows\System32 directory or, if you use Windows NT, into your
WinNT\System and WinNT\System32 directories. To use VSView8 in your Visual Basic projects, you must include
these files in the project:
VSPrint8.ocx Contains the VSPrint8 control.

VSDraw8.ocx Contains the VSDraw8 control.
VSVPort8.ocx Contains the VSViewPort8 control.
VSPDF8.ocx Contains the VSPDF8 control.
The ComponentOne Studio for ActiveX installation program will create the following directory: C:\Program
Files\ComponentOne\Studio for ActiveX. This directory contains the following subdirectories:
VSView8: Contains a README.TXT file with information about the VSView8 library.
Utilities: Contains conversion utility for upgrading projects from version 7.0 to 8.0.
Note: If you are using a 64-bit machine and need to use ComponentOne ActiveX controls in Visual Studio, you
must install both the 32-bit and 64-bit version of the controls.
Upgrading from VSView7

If you are upgrading from VSView7, you will need to use the CONVERT utility supplied with the distribution disk to
upgrade your existing projects. You may still use the original VSView7 for legacy projects and VSView8 for new
projects. Both versions may coexist on the same computer.
Installing Demonstration Versions

If you wish to try VSView8 and do not have a serial number, follow the steps through the installation wizard and use the
default serial number.
The only difference between unregistered (demonstration) and registered (purchased) versions of our products is that
registered versions will stamp every application you compile so a ComponentOne banner will not appear when your
users run the applications.
4
Uninstalling VSView8
To uninstall VSView8:
1. Open the Control Panel and select Add or Remove Programs or Programs and Features.
2. Select ComponentOne Studio for ActiveX and click the Remove button.
3. Click Yes to remove the program.
End-User License Agreement

All of the ComponentOne licensing information, including the ComponentOne end-user license agreements, frequently
asked licensing questions, and the ComponentOne licensing model, is available online at
http://www.componentone.com/SuperPages/Licensing/.
Licensing FAQs
This section describes the main technical aspects of licensing. It may help the user to understand and resolve licensing
problems he may experience when using ComponentOne products.
What is Licensing?
Licensing is a mechanism used to protect intellectual property by ensuring that users are authorized to use software
products.
Licensing is not only used to prevent illegal distribution of software products. Many software vendors, including
ComponentOne, use licensing to allow potential users to test products before they decide to purchase them.
Without licensing, this type of distribution would not be practical for the vendor or convenient for the user. Vendors
would either have to distribute evaluation software with limited functionality, or shift the burden of managing software
licenses to customers, who could easily forget that the software being used is an evaluation version and has not been
purchased.
How does Licensing Work?

ComponentOne uses a licensing model based on the standard set by Microsoft, which works with all types of
components.
Note: The Compact Framework components use a slightly different mechanism for run-time licensing than the
other ComponentOne components due to platform differences.
When a user decides to purchase a product, he receives an installation program and a Serial Number. During the
installation process, the user is prompted for the serial number that is saved on the system. (Users can also enter the
serial number by clicking the License button on the About Box of any ComponentOne product, if available, or by
rerunning the installation and entering the serial number in the licensing dialog.)
ActiveX licensing is handled transparently by .NET in C#.NET and VB.NET, so special consideration is not required
when adding ActiveX controls to a form or user control in .NET.
However, if you put an unlicensed version of the control on a form, or you wish to change licenses, you must remove the
old control and add it back again to get the new licensing. The behavior is identical to that of a VC++ project using an
ActiveX control.
For information on dynamically adding ActiveX controls that require run-time licenses, see the Microsoft Support site.
All ComponentOne products are designed to display licensing information if the product is not licensed. None will throw
licensing exceptions and prevent applications from running.
5
Technical Support
ComponentOne offers various support options. For a complete list and a description of each, visit the ComponentOne
Web site at http://www.componentone.com/SuperProducts/SupportServices/.
Some methods for obtaining technical support include:
 Online Resources
ComponentOne provides customers with a comprehensive set of technical resources in the form of FAQs,
samples and videos, Version Release History, searchable Knowledge base, searchable Online Help and
more. We recommend this as the first place to look for answers to your technical questions.
 Online Support via our Incident Submission Form
This online support service provides you with direct access to our Technical Support staff via an online
incident submission form. When you submit an incident, you'll immediately receive a response via e-mail
confirming that you've successfully created an incident. This e-mail will provide you with an Issue
Reference ID and will provide you with a set of possible answers to your question from our
Knowledgebase. You will receive a response from one of the ComponentOne staff members via e-mail in 2
business days or less.
 Peer-to-Peer Product Forums
ComponentOne peer-to-peer product forums are available to exchange information, tips, and techniques
regarding ComponentOne products. ComponentOne sponsors these areas as a forum for users to share
information. While ComponentOne does not provide direct support in the forums, we periodically monitor
them to ensure accuracy of information and provide comments when appropriate. Please note that a
ComponentOne User Account is required to participate in the ComponentOne Product Forums.
 Installation Issues
Registered users can obtain help with problems installing ComponentOne products. Contact technical
support by using the online incident submission form or by phone (412.681.4738). Please note that this
does not include issues related to distributing a product to end-users in an application.
 Documentation
Microsoft integrated ComponentOne documentation can be installed with each of our products, and
documentation is also available online. If you have suggestions on how we can improve our documentation,
please e-mail the Documentation team. Please note that e-mail sent to the Documentation team is for
documentation feedback only. Technical Support and Sales issues should be sent directly to their
respective departments.
Note: You must create a ComponentOne Account and register your product with a valid serial number to obtain
support using some of the above methods.
Redistributable Files
ComponentOne VSView8 is developed and published by GrapeCity, Inc. You may use it to develop applications in
conjunction with Microsoft Visual Studio or any other programming environment that enables the user to use and
integrate the control(s). You may also distribute, free of royalties, the following Redistributable Files with any such
application you develop to the extent that they are used separately on a single CPU on the client/workstation side of the
network:
 vsdraw8.ocx
 vspdf8.ocx
 vsppgvp8.dll
6
 vsprint8.ocx
 vsvport8.ocx
Site licenses are available for groups of multiple developers. Please contact [email protected] for details.
Upgrading From Previous Versions

Visual Basic projects that use VSView7 may be upgraded to VSView8 using the conversion utility provided in the
distribution package.
The conversion utility is a Visual Basic program called Convert7to8, and its source code is included should you want to
see exactly what it does. It is installed to C:\Program Files\ComponentOne Studio\Utilities by default. Please note that it
may be installed elsewhere if you installed the product to another location.
Convert7to8 reads the name of an existing Visual Basic project, parses the names of all forms, then makes all the
changes needed to each file. The routine saves the original files with a "bak" extension that is appended to the original
file name (e.g., "Form1.frm" becomes "Form1.frm.bak").
Changes from VSView7 to VSView8
VSView8 is highly compatible with VSView7 on a source-code level. Most of the changes made to the library consist of
new properties, events, methods, and settings to existing properties. These changes do not affect existing code.
There are a few exceptions, however. Fortunately, these are handled automatically for you by the Convert7to8 utility
included with VSView8. The list below describes all the changes that may affect your code and the reasons why they
were made:
Packaging Changes
In VSView7, a single OCX file contained the three controls. In VSView8, each control is contained in a separated file
(VSPrint8.ocx, VSDraw8.ocx, VSVPort8.ocx. and VSPDF8.ocx). This change was made mainly to facilitate deployment
of applications over the Internet. Applications that use only one of the controls no longer need to install the other two.
Property Changes
The MouseScroll, MouseZoom, and MousePage properties have been replaced with the new Navigation property. This
change was necessary because the new control supports navigation with the mouse wheel and keyboard, and the new
Navigation property covers all navigation modes.
The HTMLFileName, HTMLStyle, and TextHTMLRaw properties have been replaced with the new ExportFile,
ExportFormat, and ExportRaw properties. This change was made to support the new RTF export capability of the
control.
Method Changes
The DrawPicture method has two new optional parameters, Align and Shade, which give better control over the scaling
and placement of the picture within the specified rectangle. Since the new parameters are optional, this change does not
affect VB source code, but it may affect MFC-based C++ projects.
The PrintDoc method now allows you to pass a string as the FromPage parameter. When used in this way, the string
should contain a page range encoded as comma-separated numbers and hyphen-separated subranges, for example, 1-3, 5,
7, 8-12. This change does not affect any source code.
Event Changes
The MouseZoom, MousePage, and MouseScroll events have been replaced with the new BeforeUserZoom,
AfterUserZoom, BeforeUserPage, AfterUserPage, BeforeUserScroll, and AfterUserScroll. This change was made
for two reasons. First, the new control supports zooming with the mouse, wheel and keyboard, so the old naming became
inadequate. Second, the old events were fired before and after the events, which was confusing.
The NewTableCell event has been replaced with the new BeforeTableCell and AfterTableCell events. This change
was made to make the rendering of tables more flexible and efficient. The new events have parameters that allow you to
7
turn off the events, thus increasing speed, and the AfterTableCell event allows you to draw additional elements over the
table cell after it has been rendered.
Upgrading Visual Basic projects
Upgrading existing projects from VSView7 to VSView8 is easy. The CONVERT.EXE utility provided will convert
almost any VB project in a completely automatic way. The utility is provided in source code format, so you can see
exactly what is being done to your projects.
Using CONVERT is simple: just run the utility, pick the project you want to convert, and click OK. The utility will
create a backup copy of all files in the project, make all changes needed to the project files, and also warn you of any
potential problems.
After running CONVERT, open the converted project in VB and compile it just to make sure the new project is 100%
syntactically correct. In a few cases, you may need to make a few additional changes by hand.
Upgrading C++ Projects
Converting C++ projects requires more work, and there is no utility to help you with the process, which is easy but
tedious. Here is the sequence of steps we recommend:
1. Open each dialog that contains VSView7 controls.
2. Remove each VSView7 control and use the Class Wizard to delete its member variable (for example,
m_Printer).
3. For each control you removed, add a corresponding VSView8 control and use the Class Wizard to create a
member variable with the same name as the control you deleted (for example, m_Printer). Also make sure
the new control has the same resource ID as the one that was deleted.
4. Build the project and fix any syntax errors found by the compiler. Most should be because of variable type
changes and easy to fix.
5. You may also want to remove the old control wrapper classes from your project. Go to the Project Window
and delete files vsprinter.cpp and vsprinter.h (there should be new ones called vsprinter1.cpp and
vsprinter1.h).
Converting controls that are created dynamically (for example, not drawn on a dialog) follows a similar process. You
still need the class wrapper files for the new controls, which VC++ creates for you. Then you must change the
declaration of the control member variables (for example, m_Printer) to use the class name declared in the new
wrappers. From then on, follow steps 4 and 5 described above.
Adding the VSView8 Components to the Toolbox

VSPrint, VSDraw, VSVPort and VSPDF are used to support the creation and management of documents for printing and
previewing.
To use the VSView8 controls, they must be added to the Visual Studio Toolbox:
1. Open the Visual Basic IDE (Microsoft's Integrated Development Environment). Make sure the Toolbox is
visible (if necessary, select Toolbox in the View menu).
To set up the VSView8 components to appear on their own tab, right-click anywhere in the Toolbox and
select Add Tab from the context menu. Enter a tab name, VSView8, for example in the dialog box. Select
the new tab.
8
2. Right-click the gray area under that tab and select Components from the context menu. The Components
dialog box opens.
3. In the Components dialog box, find and place a checkmark in the checkbox beside the following:
 ComponentOne VSDraw 8.0 Control
 ComponentOne VSPrinter 8.0 Control
 ComponentOne VSViewPort 8.0 Control
 ComponentOne VSPDF 8.0 Control
4. Click OK.
Using ComponentOne ActiveX Controls in the .NET

Framework
All of the ComponentOne ActiveX controls are supported in the Microsoft .NET Framework. To use a ComponentOne
ActiveX control in Visual Studio, follow these steps:
1. Open Visual Studio and select File | New | Project. The New Project dialog box opens.
2. Under Installed Templates, expand the desired programming language node, and select Windows. Note
that you may need to expand Other Languages to find the language you want to use.
3. Select a .NET Framework version, and then select Windows Forms Application.
9
4. Enter a project name in the Name field, enter or browse for a project location in the Location field, and
then click OK. A new Microsoft Visual Studio .NET project is created in the specified location.
5. Make sure the Toolbox is visible (if necessary, select Toolbox in the View menu).
6. To place the ComponentOne ActiveX components on their own tab, right-click anywhere in the Toolbox
and select Add Tab from the context menu.
7. Enter a tab name, for example "C1 ActiveX", in the caption text box and click OK.
8. Right-click the tab and select Choose Items.
9. Click the COM Components tab, click the Name header to sort alphabetically, and scroll to find the
ComponentOne controls.
10. Select the checkbox next to any of the ComponentOne ActiveX controls that you would like to add to the
Toolbox and click OK.
11. Drag the control from the Toolbox onto the form.
Smart Tags and Tasks Menus
You can invoke each control's Tasks menu by clicking the smart tag ( ) in the upper-right corner of the control. A smart
tag represents a short-cut tasks menu that provides the most commonly used properties in each control. For example,
here is the Chart 8.0 2D control's Tasks menu:
10
Context Menus
You can invoke each control's context menu by right-clicking the control in Design view. The context menu provides
access to common actions when using the control.
Hints and Troubleshooting

1) How can I clear the contents of the VSPrinter control?
Use the Clear method.
2) How can I use printer fonts with VSPrinter?
Just assign the font name to the Font.Name or FontName properties as usual. The preview will look a little different
from the printed output, because Windows will have to select the screen font that best approximates the printer font you
selected, and the match won't be perfect.
Using printer fonts has one additional point that may cause some confusion. If you read the font name back from the
FontName property, it will return the actual printer font name. But if you read it back from the Font.Name property,
11
you will get the name of the screen font instead. This happens because FontName returns the original name that was
assigned to the property, while the Font object returns the name of the screen font that best approximates the original
selection.
For example, assuming that vp is a VSPrinter control:
?vp.Device
HP LaserJet 4L
vp.FontName = "Antique Olive"
?vp.FontName
Antique Olive
?vp.Font.Name
Times New Roman
3) Why do so many methods have parameters of type Variant?

Only Variant parameters can be specified as optional. A Boolean parameter, for example, cannot be optional. This is part
of the ActiveX architecture.
Many VSPrinter methods have optional parameters, because default values are provided that handle the vast majority of
the calls. All of these must be of type Variant.
Also, VSPrinter allows you to use unit-aware measurements, which can be specified as strings or numbers, and thus
need to be of type Variant. For example:
vp.MarginLeft = "2.2in"
vp.SpaceAfter = 300 ' twips
4) How can I include Pictures, Headers, and Footers in my RTF output files?
Pictures, headers, and footers are not automatically included in VSPrinter8 RTF or HTML export files. You can include
them using the ExportRaw property. For example, the following routine includes a picture file into RTF or HTML
export files:
Sub ExportPicture(vp As VSPrinter, sPicFile As String)
' no export file? no work!

If Len(vp.ExportFile) = 0 Then Exit Sub
' HTML
If vp.ExportFormat < vpxRTF Then
Dim ml!
ml = vp.IndentLeft / 1440
vp.ExportRaw = vbCrLf & _
"<img style='margin-left:" & _
ml & "in;' src=" & sPicFile & ">" & vbCrLf
Exit Sub
End If
' RTF
Dim sPicFileEsc$
sPicFileEsc = Replace(sPicFile, "\", "\\\\")
' save it
vp.ExportRaw = vbCrLf & _
"{\field{\*\fldinst { INCLUDEPICTURE " & _
sPicFileEsc & " \\* MERGEFORMAT \\d }}}" & vbCrLf
End Sub
For a more complete example, including headers and footers, see the PicExport sample on the HelpCentral Samples
page.
5) How can I make table cells break across page breaks?
By default, VSPrinter tries to keep table rows together on a page. If a cell contains a lot of text, though, you may want to
allow the row to break across page breaks. To do this, set the TableCell(tcRowKeepTogether) property to False.
12
Using the VSPrinter Control
The VSPrinter control makes it easy to create documents and reports for printing and print previewing from your
applications. It only takes one statement to print plain text or RTF files, and a little more work to print graphics, tables,
and formatted text. You have complete control over the printing device and document layout, including paper size and
orientation, number of columns, headers and footers, page borders, shading, fonts, and so on.
The diagram below shows the basic sequence of steps required to create a VSPrinter document:
As the diagram shows, there are six main steps to using the VSPrinter control.
1) Set up the Output Device:
Here you define what kind of output you want to create. There are three main options.
 Print Preview: Set the Preview property to True. If you want to use a specific printer (as opposed to the
default printer), set the Device property to the name of the printer you want to use. This option generates
the document in memory. When the document is finished, it can be previewed, saved to disk or sent to the
printer.
 Direct Printer Output: Set the Preview property to False. If you want to use a specific printer, set the
Device property to the name of the printer you want to use. To allow the user to select a printer, use the
PrintDialog method.
13
This option sends all output directly to the printer, and there's no preview (the control remains blank.)
 Export File (RTF or HTML): Set the Preview property to True, set the ExportFile and ExportFormat
properties to the name and type of file you want to create. The file name should include the path and
extension. The format may be RTF, plain HTML, DHTML, or paged HTML (multiple hyperlinked files).
This option generates a regular preview document, and also an RTF or HTML output file that can be
viewed and edited with other software such as word processors and Web browsers.
For a complete list of properties related to this step, see the Device Control and User Interface property
groups below.
2) Set up the Document:
Here you define the document layout properties. VSPrinter provides reasonable defaults for these properties, but you
may want to customize some of them. Typically, you will set the Font, MarginLeft, MarginTop, MarginRight,
MarginBottom, Header and Footer properties.
For a complete list of properties related to this step, see the Document Layout property group below.
3) Start the document:
Use the StartDoc method to start creating the document.
4) Create the document:
This is the main part of the process. Here you will use the Paragraph, AddTable, and other properties and methods that
generate the document contents. When generating long documents, you should check the Error property periodically. If
an error is detected while the document is being generated, you can exit any long loops you may have and cancel the
document.
For a complete list of properties related to this step, see the Output Generation property group below.
5) End the Document:
Use the EndDoc method to finish creating the document.
6) Save/Print/Preview Document:
At this point, if the document was created with the Preview property set to True, it is ready to be previewed, saved to
disk, or sent to the printer.
For a complete list of properties related to this step, see the User Interface and Document Management property groups
below.
VSPrinter Property Groups

The VSPrinter control has a rich set of properties, methods, and events. You do not have to know all of them in order to
use the control effectively.
The reference below shows the most important properties, methods, and events, grouped by type of usage. Some
elements appear in more than one group. For details on specific properties, events, or methods, refer to the reference part
of this document.
1) User Interface Properties:
 Control Appearance
Appearance, BackColor, BorderStyle, EmptyColor, NavBar,
NavBarColor.
 Abort Dialog (displayed while printing a document)
AbortWindow, AbortWindowPos, Error, AbortCaption, AbortTextButton,
AbortTextDevice, AbortTextPage.
14
 Previewing
Preview, PreviewPage, PreviewPages, ShowGuides, Navigation,
Zoom, ZoomMode, ZoomMax, ZoomMin, ZoomStep,
ProportionalBars, Track, ScrollLeft,
ScrollTop, LargeChangeHorz, LargeChangeVert,
SmallChangeHorz, SmallChangeVert, ReadyState.
2) Device Control Properties:
 Device Selection
Preview, OutputFileName, ExportFile, ExportFormat, Device, Devices,
NDevices, DefaultDevice, Driver.
 Device Driver Settings
PhysicalPage, Collate, ColorMode, Copies, DPI, Duplex, Orientation, PaperBin,
PaperBins, PaperSize, PaperSizes, PaperWidth, PaperHeight, PrintQuality,
ResetDC, ScaleOutput, TrueType, ReadyState.
3) Document Layout Properties:
 Page Size
Orientation, PhysicalPage, PageHeight, PageWidth.
 Page Layout
MarginLeft, MarginTop, MarginRight, MarginBottom, GetMargins, Columns,
ColumnSpacing, PageBorder.
 Headers and Footers
Header, Footer, HdrColor, HdrFont, MarginHeader, MarginFooter, AfterFooter,
AfterHeader, BeforeHeader, BeforeFooter.
4) Output Generation:
 Formatting
CurrentX, CurrentY, GetMargins, PageHeight, PageWidth,
IndentFirst, IndentLeft, IndentRight, IndentTab, LineSpacing,
SpaceBefore, SpaceAfter, Font, TextColor, TextAlign,
TextAngle, AutoRTF, Styles.
 Text
Paragraph, Text, TextBox, TextRTF, ExportRaw, CurrentColumn,
CurrentLine, CurrentPage.
 Tables
Table, AddTable, AddTableArray, StartTable, EndTable, TableCell, TableBorder,
TablePen, TablePenTB, TablePenLR, BeforeTableCell, AfterTableCell.
 Graphics
BrushColor, BrushStyle, PenColor,
15
PenStyle, PenWidth, DrawCircle,
DrawEllipse, DrawLine, DrawRectangle,
Polygon, Polyline, Draw, X1,
Y1, X2, Y2.
 Pictures
DrawPicture, RenderControl, PalettePicture, Picture,
X1, Y1, X2, Y2.
 Overlays
StartOverlay, EndOverlay.
 Active Contents
ClientToPage, PageToClient, FindText, RetrieveText,
ScrollIntoView, StartTag, EndTag, FindTag, RetrieveTag.
 Measuring
GetMargins, PageHeight, PageWidth, CalcParagraph,
CalcText, CalcTextRTF, CalcTable, CalcPicture, Measure, TextHei, TextWid,
TextHeight, TextWidth, TwipsPerPixelX, TwipsPerPixelY,
Measuring.
5) Document Management Properties:
 Document Management and Information
StartDoc, EndDoc, KillDoc, NewPage, NewColumn, NewLine, EndPage,
PrintDoc, PrintFile, PageCount, DocName, Error, ReadyState,
ReadyStateChange.
 Disk Operations
Archive, ArchiveInfo, LoadDoc, LoadingDoc, SaveDoc,
SavingDoc.
6) Windows API Support:
hWnd, hDC.
Using Unit-Aware Properties

VSPrinter 8 allows you to specify virtually all measurements and positioning properties and parameters as a value
followed by a unit (To allow this type of assignment, all unit-aware properties and method parameters are of type
Variant.)
For example, the MarginLeft property may be assigned in several ways:
vp.MarginLeft = 1440 ' no units, assume twips
vp.MarginLeft = "1in" ' one inch
vp.MarginLeft = "62pt" ' 62 points
vp.MarginLeft = "2.3cm" ' 2.3 centimeters
When the assignment is made, VSPrinter converts the given measurement into the default units. This is done to allow
the property to be used in mathematical expressions. For example:
16
vp.MarginLeft = "1in" ' one inch
vp.MarginLeft = 2 * vp.MarginLeft
Debug.Print vp.MarginLeft " twips (default unit)"
2440 twips (default unit)
The table below shows the units recognized by the VSPrinter control:
Symbol Unit
none Default unit (twips, except for the LineSpacing property).
in, " Inches.
twip Twips (one twip = 1/20th of a point).
pt, point Points.
cm Centimeters.
mm Millimeters.
pix Printer pixels.
% Percentage.
When you use percentage units, the meaning is context-dependent. For the LineSpacing property, 100% is single-space.
For rendering pictures, 100% is actual size. For horizontal margins and table column widths, 100% is the page width.
Visual C++ Topics

The VSPrinter and VSDraw controls can be used in Visual C++ as well as in Visual Basic.
This part of the manual was written to help experienced C++ programmers get started using the VSPrinter control in
VC++. If you don't know C++, MFC, or ATL, you may skip this section as it probably won't make much sense to you.
Until recently, using ActiveX controls in Visual C++ meant you had to use the MFC (Microsoft Foundation Classes)
framework, because this was the only reasonable way to get the ActiveX hosting capabilities and Wizard support most
programmers want. With the release of Microsoft Visual Studio 6, however, this situation has changed. You can now use
ATL (Active Template Library) and native compiler support for COM to create projects that do not depend on MFC. In
fact, even if your project is based on MFC you should consider taking advantage of the native COM support to improve
the performance of your applications.
Using VSPrinter in MFC projects

To use the VSPrinter control in MFC projects, you will normally follow these steps:
1. Create a new dialog-based MFC project, making sure to leave checked the ActiveX Controls option in the
Wizard.
2. Go to the resource editor, open the dialog, right-click on it, select Insert ActiveX control, and pick the
VSPrinter control from the list (if the control is not on the list, it hasn't been registered on your computer).
3. Hold down the CTRL key and double-click on the control. This will cause Developer Studio to generate
wrapper classes through which you can interact with the control. When the wrapper classes are ready,
select a name for the control (for example, m_Printer).
4. From now on, things are pretty much the same as in VB. You can right-click on the control to implement
event handlers, and access the controls properties and methods through the m_Printer variable. Most
properties are exposed through GetPropertyName and SetPropertyName member functions. Unfortunately,
enumerated values get translated into longs instead of their proper enumeration symbols, but that is a
relatively minor inconvenience. (And one that can be avoided, read on).
17
If you look at the CVSPrinter wrapper generated by Developer Studio, you will see that the class is derived from
CWnd. This means you can manipulate the control as if it were a regular window. Move, size or hide the control using
the CWnd methods. The wrapper class also has a handy Create function that lets you create new instances of the
control. For example, if you add this declaration to the main dialog's header file:
class CMyDlg : public Cdialog
{
// Construction
public:
CMyDlg(CWnd* pParent = NULL); // standard constructor
CVSPrinter m_PrinterDynamic; // VSPrinter control
...
You can create the control by adding the following code to the dialog's OnInitDialog function:
BOOL CMyDlg::OnInitDialog()
{
// calculate size of the new VSPrinter control
RECT rc;
GetClientRect(&rc);
InflateRect(&rc, -5, -5);
// create the VSPrinter control and

// attach it to the dialog
m_PrinterDynamic.Create(NULL, WS_VISIBLE, rc, this, 100);
return TRUE;
}
The problem with this second approach is that you have to hook up the event handlers manually. You can do this by
copying the code created by the Wizard for the first control (it involves using several macros to define an "event sink").
Hooking up the events manually is not difficult, but it is a tedious and error-prone process. Unless you have a good
reason to create the controls dynamically, you should stick to the resource editor and the Wizard.
This covers most of what you need to know about using ActiveX controls in MFC. However, the following issues
deserve additional explation: handling optional parameters, Picture properties and dual interfaces.
Handling ActiveX Optional Parameters in MFC

Optional parameters in COM interfaces are always of type VARIANT. To omit them in Visual Basic, you simply don't
supply a value for them at all. The wrapper classes created by the MFC Wizard, however, require that you supply
VARIANTS for all parameters, optional or not. In these cases, what you need to do is create a VARIANT of type
VT_ERROR, and use that in place of the optional parameters.
For example, the VSPrinter control has a DrawLine X1,Y1,[X2,][Y2] method that takes two optional parameters. To
invoke DrawLine omitting the optional parameters, you could write:
COleVariant vNone(0L, VT_ERROR);
m_Printer.DrawLine(X1, Y1, vNone, vNone);
Notice that the VARIANT is created with a 0L value instead of simply 0. This is required by the compiler to resolve the
ambiguity between the short and long types.
Handling ActiveX Picture Properties in MFC

OLE Pictures are objects in their own right. They have methods that retrieve their size, type, and so on. As such, setting
or retrieving Picture properties involves dealing with their IDispatch pointers (IDispatch is the basic type of
Automation COM interface). The question is how do I create one of these interfaces to give to the control? The easiest
way is through an MFC helper class called CPictureHolder. This class, declared in the AFXCTL.H file, has methods
that allow you to create and manage OLE pictures.
The code below shows how you can use the CPictureHolder class with the VSPrinter control's DrawPicture method:
#include <afxctl.h> // declare CPictureHolder class
void CMyDlg::OnButton1()
{
18
// start VSPrinter document
m_Printer.StartDoc();
m_Printer.SetParagraph("Here is a picture:");
// create CPictureHolder from a bitmap resource

CPictureHolder pic;
pic.CreateFromBitmap(IDB_BITMAP1);
// get the LPDISPATCH pointer (must release later)

LPDISPATCH pPic = pic.GetPictureDispatch();
// draw the picture

COleVariant v1in("1in");
COleVariant v3in("3in");
m_Printer.DrawPicture(pPic, v1in, v3in,
v3in, v3in, vNone, vNone);
// don't forget to release the LPDISPATCH

pPic->Release();
// finish document
m_Printer.EndDoc();
}
Besides setting the picture property, the code above illustrates an important point when dealing with COM interfaces.
Notice how the LPDISPATCH pointer is obtained, used, and released. Failing to release COM pointers results in objects
dangling in memory and wasting resources. (This type of potential problem is one of the motivations that led to the
creation of smart pointers, both the CComPtr ATL and the _com_ptr_t compiler COM support class, which we'll
mention later.)
Some properties and methods require that you pass pictures in VARIANT parameters (for example, the Cell property).
To do this, initialize a COleVariant as follows:
COleVariant vPic;
V_VT(&vPic) = VT_DISPATCH;
V_DISPATCH(&vPic) = pic.GetPictureDispatch();
Notice that in this case you must not release the LPDISPATCH pointer, because the COleVariant destructor will do that
automatically when vPic goes out of scope.
Dual Interfaces in MFC

The wrapper classes created by the MFC wizard are very helpful, and for a while they were the best you could get. With
Visual Studio 6, however, the compiler has built-in COM support, including a different way to create wrapper classes for
ActiveX objects through the new #import compiler directive. These "native" wrapper classes are faster and more
flexible than the ones generated by MFC:
 The MFC wrappers are based on the IDispatch interface, so every method or property you access needs to
pack its parameters into VARIANTS and go through a call to the Invoke method. The native wrappers, by
contrast, take advantage of dual interfaces to access properties and methods via direct calls, which is much
faster.
 The native wrappers are more complete and configurable. They include object-defined enumerations,
default values for optional parameters, and an optional VB-like syntax for accessing properties. These new
features allow you to write
m_spPrinter->NavBar = vpnbTopPrint;
m_spPrinter->DrawLine(1440L, 1440L);
instead of
m_Printer.SetNavBar(3);
COleVariant v1in(1440L);
m_Printer.DrawLine(v1in, v1in, vNone, vNone);
19
 The native wrappers are based on COM support classes that make the handling of strings, variants and
COM pointers less error-prone.
Taking advantage of dual interfaces in existing MFC projects is easy. All you have to do is include the appropriate
#import statement in your StdAfx.h file, then create a pointer and assign it to the existing control. For example,
assuming you have an MFC-based m_Printer control, all the extra code you would need would be this:
// include this statement in the StdAfx.h file
#import "c:\windows\system\vsprint8.ocx" no_namespace
Then, instead of using the control in the usual way, declare a variable of type IVSPrinterPtr, initialize it by setting it to
m_Printer.GetControlUnknown(), and use it instead of m_Printer. The two routines listed below illustrate the
difference between the two approaches (both routines create a table with 10,000 rows and report how long it took to do
it):
// Using the MFC-generated wrapper class
void CMyDlg::BenchDispatchClick()
{
// keep track of the start time
DWORD tStart = GetTickCount();
// generate the document

m_Printer.StartDoc();
m_Printer.StartTable();
m_Printer.AddTable("1000|2000|2000", "Col1|Col2|Col3", "",
vNone, vNone, vNone);
m_Printer.SetTableCell(1 /*tcRows*/, vNone, vNone,
vNone, vNone, COleVariant(1000L));
for (long r = 1; r <= 10000; r++) {
for (long c = 1; c <= 3; c++) {
CString str;
str.Format("R%d C%d", r, c);
m_Printer.SetTableCell(18 /*tcText*/,
COleVariant(r), COleVariant(c),
vNone, vNone, COleVariant(str));
}
}
m_Printer.EndTable();
m_Printer.EndDoc();
// report how long it took

DWORD tElapsed = GetTickCount() - tStart;
CString str;
str.Format("Done in %d seconds using dual interface.",
(int)(tElapsed / 1000));
MessageBox(str);
}
// Using the native wrapper class (#import-based)
void CMyDlg::BenchDualClick()
{
// keep track of the start time
DWORD tStart = GetTickCount();
// get VTBL (dual) interface

IVSPrinterPtr spPrinter = m_Printer.GetControlUnknown();
// generate the document

spPrinter->StartDoc();
spPrinter->StartTable();
spPrinter->AddTable("1000|2000|2000", "Col1|Col2|Col3", "");
spPrinter->PutTableCell(tcRows, vtMissing, vtMissing,
vtMissing, vtMissing, 1000L);
for (long r = 1; r <= 10000; r++) {
for (long c = 1; c <= 3; c++) {
CString str;
str.Format("R%d C%d", r, c);
spPrinter->PutTableCell(tcText, r, c, vtMissing, vtMissing,
(LPCTSTR)str);
}
20
}
spPrinter->EndTable();
spPrinter->EndDoc();
// report how long it took

DWORD tElapsed = GetTickCount() - tStart;
CString str;
str.Format("Done in %d seconds using dual interface.",
(int)(tElapsed / 1000));
MessageBox(str);
}
The code looks very similar, except for the dot notation used with the m_Printer variable and the arrow used with the
spPrinter variable. The difference is in execution speed. The MFC/Dispatch version takes 8 seconds to create the table,
while the native/dual version takes only 6 seconds. The dual version is 25% faster than the traditional MFC/Dispatch
version.
In functions that only set a few properties, it probably doesn't matter much which type of wrapper class you choose. But
in functions with lengthy for statements, that access properties or methods several hundred times, you should definitely
consider using the #import statement and the dual interface.
Using VSPrinter in ATL projects

Using the VSPrinter control in ATL is not much different than using it in MFC projects. You can still use Wizards and a
rich set of low-level support classes. What you don't get is the higher-level classes, document/view architecture, and
other amenities offered by MFC.
To use the VSPrinter control in ATL projects, you will normally follow these steps:
1. Create a new ATL COM project of type "Executable".
2. Select the New ATL Object option in the Insert menu, select the Miscellaneous object type, then choose
Dialog. Pick any name for the dialog.
3. Go to the resource editor, open the dialog, right-click on it, select Insert ActiveX control, and pick the
VSPrinter control from the list (if the grid is not on the list, it hasn't been registered on your computer).
You may also want to set the dialog's ClipChildren property to True to make it repaint more smoothly.
4. Right-click on the control and select the Events option. Then select the grid control from the list on the
right and the list on the left will show all the events available for the control. Select the ones you want to
handle by double-clicking them, and click OK when you are done. This will automatically insert an
#import statement into the dialog header file.
5. You may want to edit the #import statement and leave only the no_namespace qualifier, otherwise only a
very thin wrapper will be generated.
6. Now the control is on the form, but you can't talk to it yet. To get a pointer to the control, open the dialog
header file and edit the OnInitDialog function so it looks like this:
IVSPrinterPtr m_spPrinter; // pointer to the control
CAxWindow m_wndPrinter; // pointer to the host window
LRESULT OnInitDialog(UINT uMsg, WPARAM wParam,
LPARAM lParam, BOOL& bHandled)
{
m_wndPrinter = GetDlgItem(IDC_VSPRINTER1); // get host window
m_wndPrinter.QueryControl(&m_spPrinter); // get control
m_wndPrinter.SetFocus(); // activate control
AtlAdviseSinkMap(this, true); // hook up events
return 1; // Let the system set the focus
}
This code declares a pointer to the control and one to the control's host window. When the dialog initiates,
the code makes m_wndPrinter point to the host window and queries it for the contained control, which is
stored in the m_spPrinter variable. From now on, you may move and resize the control through its host
window (m_wndPrinter) and access the control's properties and methods through the control pointer
(m_spPrinter).
21
7. The only thing missing is the code that displays the dialog. That needs to be added to the project's main cpp
file. Here's the code that you will need:
#include "MyProject_i.c"
#include "MyDlg.h" // add this line
extern "C" int WINAPI _tWinMain(HINSTANCE hInstance,

HINSTANCE /*hPrevInstance*/,
LPTSTR lpCmdLine, int /*nShowCmd*/)
{
CMyDlg dlg; // create the dialog
dlg.DoModal(); // show the dialog
//MSG msg; // comment these lines out

//while (GetMessage(&msg, 0, 0, 0))
// DispatchMessage(&msg);
}
That's about it. You could clean up this project by removing the references to the idl and rgs files, which it doesn't need
(it is just an EXE, not a COM server). See the samples on the distribution CD to find out what changes are necessary.
Creating Controls Dynamically in ATL

As in MFC, you can create controls dynamically with ATL. The steps required are these:
1. Insert the appropriate #import statement in the dialog header file or in the StdAfx.h file.
2. Add two member variables to your dialog or window class:
CAxWindow m_wndPrinter; // host window
IVSPrinterPtr m_spPrinter; // pointer to control
3. When the dialog or window is created, create the control and its host window.
// initialize ATL ActiveX hosting
AtlAxWinInit();
// create the control (will fail if not registered)

m_spPrinter.CreateInstance(__uuidof(VSPrinter)));
ATLASSERT(m_spPrinter != NULL);
// create the host window (nID = IDC_VSPRINTER1)

// the nID is needed if you want to sink events.
RECT rc;
GetClientRect(&rc);
m_wndPrinter.Create(m_hWnd, rc, NULL, WS_CHILD | WS_VISIBLE,
0, IDC_ VSPRINTER1);
4. Attach the control to the host window.

CComPtr<IAxWinHostWindow> spHost;
m_wndPrinter.QueryHost(&spHost);
spHost->AttachControl(m_spPrinter, m_wndPrinter);
As in MFC, this approach requires you to hook up the event handlers manually. You can also copy wizard-generated
code, which does two things: it adds an IDispEventImpl declaration to your class so it inherits the ATL event handling
mechanisms and adds an event sink map to your class using BEGIN_SINK_MAP, SINK_ENTRY and
END_SINK_MAP macros. You still need to add the call to AtlAdviseSinkMap in order to start getting the events.
VSPrinter Utilities - VPUtil

VSPrint 8 includes a set of utilities provided in source code form. The utilities are implemented in files VPUtil.BAS
(for Visual Basic users) and VPUtil.cpp (for Visual C++ users.)
The utilities include the following routines:
22
VPSaveState and VPRestoreState: these functions save and restore the current state of the VSPrinter control. They are
useful when you want to apply style changes to the document, and restore its previous state when you are done. The
functions implement a "state-stack", so you can nest calls to the routines.
VPRenderHTML: this routine takes an HTML string as a parameter and renders it on a VSPrinter control. The routine
handles character and paragraph formatting, and tables. It ignores unknown HTML tags such as links and pictures.
There are three main reasons for providing these functions as source code rather than building them into the control:
1. You can study the source code and learn useful techniques for programming the control. You can also
customize the routines if they don't do exactly what you want.
2. By keeping the utilities separate from the control, we avoid increasing the size and complexity of the
control. Users who don't need the extra functionality can leave it out of their projects.
3. The utilities can be extended and updated easily, without affecting the control and existing applications.
Note: VSPrinter 8 provides a new Styles property that makes VPSaveState and VPRestoreState obsolete, you should
not need to use them in new projects. However, they are provided to facilitate upgrading existing projects. They are also
useful as sample code and may be customized should you want to change the way they behave.
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 VSPrinter documents, 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:
23
As the diagram shows, there are five main steps to using the VSDraw control.
1) 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:
24
The VSDraw tutorial in this manual (see the Tutorials (page 30) 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:
' 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:
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.
2) Set Page Size
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.
25
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:
vd.SetPageExtent 2 * 1440, 1.5 * 1440
3) 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.
4) 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.
5) 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 Picture property), or send it to the printer using the PrintDoc method.
VSView8 Samples
Please be advised that this ComponentOne software tool is accompanied by various sample projects and/or demos, which
may make use of other development tools included with ComponentOne Studio Enterprise.
Note: The ComponentOne Samples are also available at

http://helpcentral.componentone.com/ProductResources.aspx?View=Samples.
26
Visual Basic Samples
Sample Description
AlignCurrency Align currency figures on tables. This sample uses the VSPrinter control.
Convert VSPrinter3 projects that used the ta*Baseline settings for TextAlign.
This sample uses a function called SetCursorBaseline that sets the cursor at the
BaseLine
appropriate position for compatibility with the ta*Baseline settings available in
VSPrinter3. This sample uses the VSPrinter control.
Builds an HTML calendar for the current month. This sample uses the VSPrinter
Calendar
control.
Shows how to control inter-character spacing. This sample uses the VSPrinter
CharSpacing
control.
Shows how to create a document with columns of different sizes. This sample
ColSizes
uses the VSPrinter control.
Shows how to implement decimal tab stops. This sample uses the VSPrinter
DecTabs
control.
Shows how to implement file drag/drop into a VSPrinter control. This sample
DragDrop
This sample shows how you can encode VSPrinter documents (binary files
saved with the SaveDoc command) into strings, re-encode them so that
Encode VSPrinter can read them. This technique may be useful if you need to store
VSPrinter documents as memo fields in a database. This sample uses the
VSPrinter control.
Shows how to implement fill-out pre-printed forms. This sample uses a

VSViewPort control to display a picture of a pre-printed form and input fields
FaxForm where the user can type the information to fill out the form. The FocusTrack
property is used to keep the field that has the focus visible to the user. This
sample uses the VsViewPort and VSPrinter controls.
Load an RTF document and search for strings.This sample uses the VSPrinter
FindText
control.
Create a simple flow chart in a VSPrinter control. The sample illustrates how
FlowChart you can add print/preview capabilities to your own custom objects using
VSPrinter. This sample uses the VSPrinter control.
Create a table showing all fonts installed on the computer. This sample uses the
FontSampler
VSPrinter control.
Shows how you can highlight parts of a document using two methods. (1) By
HighLight changing styles while the document is generated, or (2) By adding the highlights
as overlays. This sample uses the VSPrinter control.
Shows how you can build an index. This sample loads an RTF file and a plain
Index text file containing a list of index words. Then it finds every location of each
index word in the document and creates an index for the document. This sample
27
Calculate how many lines will fit on a page. This sample uses the VSPrinter
LineSpacing
control.
Allow users to adjust margins using the mouse. This sample uses the VSPrinter
Margins
control.
MultiRowHdr Create tables with multi-row headers. This sample uses the VSPrinter control.
Add custom buttons to the navigation bar. The custom buttons are implemented
NavButton using standard VB controls (Picture and Image boxes). This sample uses the
VSPrinter control.
Add custom buttons to the navigation bar. The custom buttons are implemented
NavButton2 using standard VB controls (Picture and Image boxes). This sample uses the
VSPrinter control.
Shows most of the new features in the VSPrinter7 control. This sample uses the
NewStuff
VSPrinter control.
Create an Outline tree for a VSPrinter document. The sample creates a document
and marks headings with specially formatted tags. When the document is ready,
Outline the sample scans the document for heading tags and uses them to build an
Outline Tree using a TreeView control. This sample uses the VSPrinter and
TreeView control.
Use a picture as a background for your documents (watermark-style). The

PicBkg sample also shows how you can render charts on VSPrinter documents. This
sample uses the VSPrinter and MSChart control.
Export documents with pictures, headers, and footers. This sample uses the
PicExport
VSPrinter and RichTextBox control.
Shrink an image reducing its resolution, so it takes up less room. This sample
PicRes
Fill polygons with picture. This sample uses Windows APIs to create a clipping
PolyPicture region based on a polygon, and then fills the polygon by tiling the clipping area
with a picture. This sample uses the VSPrinter control.
Render database tables (recordsets) using the AddTableArray method. This

Recordset
sample uses the VSPrinter control.
Render database tables (recordsets) using the AddTableArray method. This

Recordset2
Create documents based on RTF text stored in a database. The document

generation routine has a Recordset MoveFirst/MoveNext loop that generates one
RTFDB
page for each record. The pages have an image, a title, and the body containing
RTF text. This sample uses the VSPrinter control.
Export RTF with absolute positioning. The sample creates RTF output with
RTFExport tables, textboxes, and lines. This sample uses the VSPrinter and the
RichTextBox control.
28
Render RTF text from a RichTextBox control preserving the line breaks. This
RTFLineBrk
sample uses the RichTextBox and VSPrinter control.
RTFWidth Measure the width of an RTF string. This sample uses the VSPrinter control.
Use the VSPrinter's hDC property to make Windows GDI calls. This sample
SimpleGDI
Shows the effect of properties on paragraph spacing, indentation, and alignment.

Spacing
This sample uses the VSPrinter control.
Creates a compressed version of the image file and renders up to 12 images of

Stretch
the compressed image. This sample uses the VSPrinter control.
StrokePath Use GDI calls to render font outlines. This sample uses the VSPrinter control
Shows several new table-related features in VSPrinter7. This sample uses the
TableEffects
VSPrinter control.
Create an active table of contents for a VSPrinter document. This sample uses
TOC
the VSPrinter control.
Insert VSDraw drawings into VSPrinter documents. This sample uses VSPrinter
VSDraw
and VSDraw control.
Visual C++ Samples
Sample Description
Use VSPrinter to create and preview various types of documents. The sample
shows how to create documents with text, images, tables, and styles, and how to
BigDemo
preview, print, and export these documents. This sample uses the VSPrinter
control.
Compare the performance of dispatch and dual interfaces. The demo compares
the performance of the control when using the dispatch-based wrapper classes
MFCDEMO
created by MFC and the dual interfaces created using the #import statement.
This sample uses the VSPrinter control.
Export images, headers, and footers to RTF and HTML. This sample uses the
PicExport
VSPrinter control.
Shows several new table-related features in VSPrinter8. This sample uses the
TableEffects
VSPrinter control.
Use the LayoutThumbnails to control how thumbnail images are displayed. This
Thumbnail
29
Tutorials
The following tutorials walk you through the creation of simple projects using the VSPrinter and VSDraw controls. The
sample projects illustrate the main aspects of using the controls, so after completing the tutorials you will have a solid
understanding of their operation.
The tutorials are short, but some of them contain a fair amount of code. The easiest way to use the tutorials is using the
on-line help, and copying the code directly from the documentation into your sample project as you develop it.
After the tutorials, there is also a set of examples. The examples contain useful and interesting routines and code
snippets. You may find some of the samples useful in your projects.
VSPrinter Tutorial - QuickPrinter

This section walks you through the development of a simple application called QuickPrinter that lets you preview and
print files, including plain text, RTF, and HTML.
In just a few short steps you can create a printing and previewing application with complete functionality.
Step 1: Create the Form

Start a new VB project, and then add the following controls to the main form:
 A ComponentOne VSPrinter 8 control (from VSPrint8.OCX).
 A Microsoft CommonDialog control (from ComDlg32.OCX).
 Three command buttons.
Set the Name property of the controls to the following:
 VSPrinter control to vp.
 CommonDialog control to dlg.
 Command buttons to cmdOpen, cmdPrint, and cmdSetup.
Set the Caption property of the command buttons to the following:
 &Open…
 &Print
 Page &Setup…
Align the command buttons along the top of the form and size the vp control so that it fills the remaining portion of the
form. Your form should look like this:
30
Step 2: Opening Files
Double-click on the Open button, and add the following code to the cmdOpen_Click event handler:
Private Sub cmdOpen_Click()
' get file to open

dlg.FileName = FileName
dlg.ShowOpen
If dlg.FileName = "" Then Exit Sub
FileName = dlg.FileName
' do it
RenderFile
End Sub
The routine is simple: it uses the CommonDialog control dlg to present a file selection dialog to the user, then saves the
selected file name in a global variable called FileName, and defers the real work to the RenderFile routine, which still
needs to be written.
Before getting into the RenderFile routine, go to the declarations part of the form and declare the global variable
FileName. The declarations section of the form should look like this:
Option Explicit
Option Compare Text
' keep track of file being previewed

Dim FileName$
31
Step 3: Previewing Files
The RenderFile routine is where most of the work is done. Here is what it looks like:
Sub RenderFile()
' no file? quit

If Len(FileName) = 0 Then Exit Sub
' set up document

vp.DocName = "VSPrint8 QuickPrinter"
vp.Header = "QuickPrinter||Page %d"
vp.Footer = Format(Now, "dd-mmm-yy") & "||" & FileName
vp.PageBorder = pbAll
' read the file into a big string

Dim sText$
On Error Resume Next
Open FileName For Binary As #1
sText = Input$(LOF(1), 1)
Close #1
On Error GoTo 0
' start document

vp.StartDoc
If LCase(Left(sText, 6)) = "<html>" Then
VPRenderHTML vp, sText ' render html
Else
vp = sText ' render regular text and RTF
End If
vp.EndDoc
' update the form caption

ShowCaption
End Sub
Here is what the RenderFile routine does, piece by piece:

' no file? quit
If FileName = "" Then Exit Sub
This makes sure we have a document to render. It is good defensive programming.

' set up document
vp.DocName = "VSView7 QuickPrinter"
This line sets the VSPrinter control's document name. This name will appear in the Windows print manager window
and in the abort window that pops up while the document is printing.
vp.Header = "QuickPrinter||Page %d"
vp.Footer = Format(Now, "dd-mmm-yy") & "||" & FileName
Here we build the header and footer for the document. The header has a left aligned part that says "QuickPrinter", a
center aligned part that is empty, and a right-aligned part that has a page counter (the %d works as a placeholder for the
current page being created). The footer contains the current date and the name of the file being printed.
vp.PageBorder = pbAll
This line sets the page borders for the entire document. The color, style, and width for the borders are determined by the
PenWidth, PenColor, and PenStyle properties, but we'll just use the defaults here.
' read the file into a big string
Dim sText$
Open FileName For Input As #1
sText = Input$(LOF(1), 1)
Close #1
On Error GoTo 0
32
This block of code reads the entire file into a string that will be printed later. Alternatively, we could render plain text
one line at a time, but that would not work for RTF or HTML text. To keep the code simple, we treat all files types the
same way.
' start document
vp.StartDoc
This statement tells the VSPrinter control we are about to start creating a document. Because the Preview property is
True by default, this will be a preview document and will not be sent to the printer immediately.
If LCase(Left(sText, 6)) <> "<html>" Then
vp.Paragraph = sText ' render regular text and RTF
Else
VPRenderHTML vp, sText ' render html
End If
This block of code is responsible for rendering the file into the VSPrinter control. VSPrinter has built-in support for
plain text and RTF. Because the AutoRTF property is set to True, simply assigning the text to the Paragraph property
will render plain text and RTF.
Handling HTML requires an extra step. VSPrinter does not have built-in support for rendering HTML text, but the
VPUtil.BAS module provides a VPRenderHTML function that renders HTML (there is also an equivalent routine in
C++). To make the VPRenderHTML function available to the code, add the VPUtil.BAS module to the project. (To
add a module to the project, use the Project | Add File menu option and choose the VPUtil.BAS file).
vp.EndDoc
This statement tells the VSPrinter control we are done creating the document. At this point, the document is available
for previewing, saving to disk, or sending to the printer.
The NavBar property is set to vbnpBottom by default, so the control will display a navigation bar so the user can flip
preview pages and zoom with the mouse. The Navigation property is set to vpnvMouseWheel by default, so the user
can scroll the preview using the mouse and the mouse wheel.
' update the form caption
ShowCaption
This last statement updates the form caption so it shows the name of the file being previewed. The ShowCaption routine
is short and simple:
Sub ShowCaption()
Dim s$
' refresh form caption
s = "ComponentOne VSPrinter8"
If Len(FileName) > 0 Then s = s & " - " & FileName
Caption = s
End Sub
Step 4: Printing Files

Once the preview document has been created, printing it is very easy. All you need to do is call the PrintDoc method. To
add the code, double-click on the Print command button and type the following;
Private Sub cmdPrint_Click()
' if we have a document in memory, print it

If vp.PageCount > 0 Then vp.PrintDoc
End Sub
Before printing the document, we do a check to make sure we have a document available for printing.
When the user clicks on the Print button, a progress dialog will appear showing which document is being printed on
which printer, and the current page. The dialog has a Cancel button that allows the user to stop printing the document if
he changes his mind.
If you don't want this dialog to appear, or want to provide your own dialog instead, set the AbortWindow property to
False.
33
Step 5: Setting up the page and printer
The next step is to allow the user to set up the page. This can be done easily using the VSPrinter's PrintDialog method.
The PrintDialog method shows a system dialog that allows the user to select the page orientation, margins, paper type,
and paper source. The dialog also has a button that allows the user to select the printer and set its properties.
After the user changes the page and printer properties, we have to render the document again, to reflect the new
selections. Here's the code that does all this:
Private Sub cmdSetup_Click()
' let user setup the printer and the page

vp.PrintDialog pdPageSetup
' render current document again

If FileName <> "" Then RenderFile
End Sub
Step 6: Final touches

Our sample project is almost done. We will finish it with a little more code to initialize the form caption when the
program starts and to make the control resize when the form is resized. Here is the code:
Private Sub Form_Load()
' initialize form caption

ShowCaption
End Sub
When the form loads, we call the SetCaption routine defined earlier.
Private Sub Form_Resize()

With vp
.Move .Left, .Top, _
ScaleWidth - 2 * .Left, _
ScaleHeight - .Top - .Left
End With
End Sub
This is the resizing code. Note the error handling to prevent errors in case the user makes the form extremely small and
some of the calculated dimensions become negative.
That's it. The QuickPrinter application is done. Run it and pick a few files. Don't forget to try some RTF and HTML
files. Here's a snapshot of the final application in action:
34
If you want a challenge, extend QuickPrinter so it lets you choose the font, header, footer, number of columns, or select
several files for printing at once.
VSPrinter Tutorial - Calendar

This section walks you through the development of a simple application called Calendar that lets you create and print
calendars. The application illustrates the advanced table formatting capabilities in the VSPrinter control.
The application also allows you to export the calendar to an HTML file that can be viewed with your favorite browser.
This illustrates VSPrinter's HTML export capabilities.
Step 1: Create the form

Start a new VB project, then add the following controls to the main form:
 A ComponentOne VSPrinter control (from VSPrint8.OCX).
 Four command buttons.
 VSPrinter control to vp.
 Command buttons to cmdPrev, cmdNext, cmdPrint, and cmdHTML.
 <<
 >>
 &Print
 View &HTML
Set the form's Caption property to "VSPrinter Calendar".
35
Align the command buttons along the top of the form and size the vp control so that it fills the remaining portion of the
form. Your form should look like this:
Step 2: Create the calendar

To create the calendar, we will start with a base date, which will be stored in a global variable called TheDate.
Here is the code that declares the global variable and initializes it:
Option Explicit
' base date used to build the calendar

Dim TheDate As Date
This code declares the global variable TheDate.

' initialize date

TheDate = Now
' show calendar

ShowCalendar
End Sub
This code initializes the global variable to the current date and calls ShowCalendar, the main routine in this application,
to generate the initial calendar. The ShowCalendar routine uses VSPrinter's table formatting properties to create the
calendar. Here it is:
Private Sub ShowCalendar()
Dim r%, c%
' build calendar for the given date

' return TheDate's row and column in r, c
ReDim cal(7, 1) As Variant
BuildCalendar TheDate, cal, r, c
36
' start document
vp.StartDoc
' start table, don't render till we're done

vp.StartTable
' set header and bind to calendar array

' (use dummy column widths for now)
vp.AddTableArray "||||||", _
"Sun|Mon|Tue|Wed|Thu|Fri|Sat", cal
' format table using the TableCell property:

' note that TableCell indices are 1-based
' set column widths and row heights to .8 in

vp.TableCell(tcColWidth) = "0.8in"
vp.TableCell(tcRowHeight) = "0.8in"
' align cells to center

vp.TableCell(tcAlign) = taCenterMiddle
' set body font

vp.TableCell(tcFontName) = "Times New Roman"
vp.TableCell(tcFontSize) = 24
vp.TableCell(tcFontItalic) = True
' set Sunday back color

vp.TableCell(tcBackColor, , 1) = vbRed
' format header row (week days)

vp.TableCell(tcRowHeight, 0) = ".5in"
vp.TableCell(tcFontBold, 0) = True
vp.TableCell(tcFontItalic, 0) = False
vp.TableCell(tcBackColor, 0) = vbBlue
' highlight today (note 1-based indices)
vp.TableCell(tcFontBold, r + 1, c + 1) = True
vp.TableCell(tcBackColor, r + 1, c + 1) = vbYellow
' append a row with the current month and year

r = vp.TableCell(tcRows) + 1
vp.TableCell(tcRows) = r
vp.TableCell(tcText, r, 1) = _
"Calendar for " & _
Format(TheDate, "mmmm yyyy")
vp.TableCell(tcColSpan, r, 1) = 7
vp.TableCell(tcRowHeight, r) = ".5in"
vp.TableCell(tcAlign, r) = taCenterMiddle
vp.TableCell(tcBackColor, r) = vbBlue
vp.TableCell(tcFont, r, 1) = _
vp.TableCell(tcFont, 0, 1)
' done, render the table

vp.EndTable
' done, finish the document

vp.EndDoc
End Sub
The ShowCalendar routine is not very complicated, but it deserves some explanation. Here's a breakdown of what each
part does:
' build calendar for the given date
' return TheDate's row and column in r, c
ReDim cal(7, 1) As Variant
BuildCalendar TheDate, cal, r, c
This code dimensions a variant array that will contain the calendar data. It uses a separate auxiliary routine,
BuildCalendar, which does most of the work. BuildCalendar fills out the variant array and returns in the r, c
parameters the array indices that correspond to the given date.
37
' start document
vp.StartDoc
This statement tells the VSPrinter control we want to create a new document. Because the Preview property is True by
default, this will be a preview document and will not be sent to the printer immediately.
' start table, don't render till we're done
vp.StartTable
This statement tells the VSPrinter control we want to create a new table. The control will build the table in memory, and
will not render it until we issue the matching EndTable statement.
' set header and bind to calendar array
' (use dummy column widths for now)
vp.AddTableArray "||||||", _
"Sun|Mon|Tue|Wed|Thu|Fri|Sat", cal
This statement builds a table with seven columns, and binds it to the data in the cal variant array. The contents of the
array determine the number of table rows and the cell contents. Now we are ready to embellish the table using the
TableCell property.
' set column widths and row heights to .8 in
vp.TableCell(tcColWidth) = "0.8in"
vp.TableCell(tcRowHeight) = "0.8in"
Here we set the width and height of all columns and rows to 0.8 inches. By omitting indices in the call to TableCell, the
setting applies to all elements. As with any other measurements, VSPrinter interprets the units. (The default unit is
twips.)
' align cells to center
vp.TableCell(tcAlign) = taCenterMiddle
Again, we omit the indices to align all table cells to the center. The valid settings for tcAlign are the same that apply to
the TextAlign property.
' set body font
vp.TableCell(tcFontName) = "Times New Roman"
vp.TableCell(tcFontSize) = 24
vp.TableCell(tcFontItalic) = True
Setting the font for all table cells is similar to setting the alignment.
' set Sunday back color
vp.TableCell(tcBackColor, , 1) = vbRed
This statement sets the background color for the first column (Sunday) to red. Note that the row argument was omitted,
causing the setting to apply to the entire column, and the column argument was set to one, since table indices are one-
based.
' format header row (week days)
vp.TableCell(tcRowHeight, 0) = ".5in"
vp.TableCell(tcFontItalic, 0) = False
vp.TableCell(tcBackColor, 0) = vbBlue
This code formats the header row, which has index zero. It sets the font, row height, and background color.
' highlight today (note 1-based indices)
vp.TableCell(tcFontBold, r + 1, c + 1) = True
vp.TableCell(tcBackColor, r + 1, c + 1) = vbYellow
This line makes the base date, whose coordinates were returned by the call to BuildCalendar, bold on a yellow
background.
' append a row with the current month and year
r = vp.TableCell(tcRows) + 1
vp.TableCell(tcRows) = r
vp.TableCell(tcColSpan, r, 1) = 7
vp.TableCell(tcText, r, 1) = _
"Calendar for " & _
Format(TheDate, "mmmm yyyy")
38
This code appends a row to the table by writing to the tcRows attribute. Then it sets the tcColSpan attribute of the first
cell to 7, causing it to span the entire row. Finally, it sets the text of the first cell to a string containing the calendar's
month and year. This illustrates how you can mix data that comes from the array with custom data.
vp.TableCell(tcRowHeight, r) = ".5in"
vp.TableCell(tcAlign, r) = taCenterMiddle
vp.TableCell(tcBackColor, r) = vbBlue
vp.TableCell(tcFont, r, 1) = _
vp.TableCell(tcFont, 0, 1)
Finally, the row that was just appended to the table is formatted. Note how the font is set with a single reference to the
tcFont attribute, which is faster and more concise than copying the font's name, size, and so on.
vp.EndTable
This statement closes the table that was started with the StartTable statement and renders it on the document.
' done, finish the document
vp.EndDoc
This statement tells the VSPrinter control we are done creating the document. At this point, the document is available for
previewing, saving to disk, or sending to the printer.
The NavBar property is set to vbnpBottom by default, so the control will display a navigation bar so the user can flip
preview pages and zoom with the mouse. The Navigation property is set to vpnvMouseWheel by default, so the user can
scroll the preview using the mouse and the mouse wheel.
That was a lot of code, but well worth it because it covers most aspects of advanced table formatting in VSPrinter. We
are still missing the BuildCalendar routine, which is pretty simple:
Private Sub BuildCalendar(TheDay As Date, _
ByRef TheCal(), _
ByRef TheDayRow, ByRef TheDayCol)
Dim dt As Date
' clear array

ReDim TheCal(7, 1)
' initialize date to the first of the month

dt = TheDay
While Day(dt) > 1
dt = dt - 1
Wend
' fill array with dates for current month

Dim r%, c%
r = 0
c = WeekDay(dt) - 1
While Month(dt) = Month(TheDay)
' add row if we have to

If c >= 7 Then
c = 0
r = r + 1
ReDim Preserve TheCal(7, r)
End If
' save day value in the calendar

TheCal(c, r) = Day(dt)
' return TheDate's row and column

If dt = TheDay Then
TheDayRow = r
TheDayCol = c
End If
' increment day

dt = dt + 1
c = c + 1
Wend
39
End Sub
Step 3: Browsing months

The next step is to add code to the browsing buttons. To achieve this, all we need to do is add or subtract a month from
the global variable TheDate and regenerate the calendar. Double-click each of the browsing buttons, and then add the
following code to the Click event handler:
Private Sub cmdPrev_Click()
TheDate = TheDate - 30
ShowCalendar
End Sub
Private Sub cmdNext_Click()
TheDate = TheDate - 30
ShowCalendar
End Sub
Step 4: Printing the Calendar

Printing the calendar is also pretty easy. Since we already have the preview document, all we need to do is call the
PrintDoc method. Double-click the Print button and add this code to the cmdPrint_Click event handler:
Private Sub cmdPrint_Click()
vp.PrintDoc
End Sub
Step 5: Exporting to HTML

Exporting the calendar to HTML is also very easy, because the VSPrinter control has built-in HTML export capability
through the ExportFile and ExportFormat properties.
To launch the browser and allow the user to see the calendar, we need to declare the ShellExecute Windows API. Here
is the declare statement needed:
Option Explicit
' use the current browser to show HTML file

Private Declare Function ShellExecute _
Lib "shell32.dll" Alias "ShellExecuteA" ( _
ByVal hwnd As Long, ByVal lpOperation As String, _
ByVal lpFile As String, _
ByVal lpParameters As String, _
ByVal lpDirectory As String, _
ByVal nShowCmd As Long) As Long
' base date used to build the calendar

Dim TheDate As Date
Once the ShellExecute function has been declared, exporting the calendar to HTML and showing it to the user is pretty
simple. Double-click the View HTML button and add the following code to the cmdHTML_Click event handler:
Private Sub cmdHTML_Click()
' set name of HTML output file

vp.ExportFile = App.Path & "\cal.htm"
vp.ExportFormat = vpxDHTML
' refresh calendar

ShowCalendar
' show file in browser

ShellExecute hwnd, "open", vp.ExportFile, 0, 0, 0
' clear HTML output file

vp.ExportFile = ""
End Sub
40
The code starts by setting the ExportFile and ExportFormat properties, which define the type of export file you want
and its name and location on disk. Then, the calendar is regenerated, creating the HTML file.
Finally, the ShellExecute function is called to display the HTML file, and the ExportFile property is cleared to avoid
accidentally overwriting the HTML file.

Our sample project is almost done. We will finish it with a little more code to make the vp control resize when the form
is resized. Here is the code:

With vp
.Move .Left, .Top,
End With
End Sub
This is the resizing code. Note the error handling to prevent errors in case the user makes the form extremely small and
some of the calculated dimensions become negative.
That's it. The VSPrinter Calendar application is done. Here's a snapshot of the final application in action:
VSDraw Tutorial - Chart

This section walks you through the development of a simple application called Chart that creates bar and pie charts using
the VSDraw control.
You can use this code as a starting point for your own chart generator. The advantage of using custom code instead of a
commercial chart component is that the charts will be easier to customize and the resulting application will be smaller
and have fewer dependencies.
Step 1: Create the Form

Start a new VB project, and then add the following controls to the main form:
 A ComponentOne VSDraw control (from VSVIEW7.OCX).
41
 A CheckBox control.
 Two command buttons.
 VSDraw control to vd.
 CheckBox control to chk.
 Command buttons to cmdPie, and cmdBar.
 &Pie Chart
 &Bar Chart
Set the Caption property of the CheckBox to the following:
 Actual Size
Also, set the form's Caption property to "VSDraw Charts" or something more meaningful than "Form1".
Align the command buttons and check box along the top of the form and size the vd control so that it fills the remaining
portion of the form. Your form should look like this:
Step 2: Drawing Pie Charts

To draw a pie chart, we will start with some random data, and then call a general-purpose pie drawing routine. Double-
click on the Pie Chart button and add the following code to the cmdPie_Click event handler:
Private Sub cmdPie_Click()
' set up chart data in variant array:

' col 0 has values, col 1 has labels, and
' col 2 has colors
' negative values create exploded slices
Dim cd(2, 6)
42
cd(0, 0) = 30: cd(1, 0) = "Phone"
cd(0, 1) =-65: cd(1, 1) = "Payroll"
cd(0, 2) = 42: cd(1, 2) = "Equipment"
cd(0, 3) = 24: cd(1, 3) = "Rent"
cd(0, 4) =-52: cd(1, 4) = "Advertising"
cd(0, 5) = 12: cd(1, 5) = "Production"
cd(0, 6) = 22: cd(1, 6) = "Other"
cd(2, 0) = vbRed
cd(2, 1) = vbBlue
cd(2, 2) = vbGreen
cd(2, 3) = vbYellow
cd(2, 4) = vbCyan
cd(2, 5) = vbMagenta
cd(2, 6) = vbBlack
' draw chart

vd.FontName = "Tahoma"
DrawPieChart vd, cd, _
"Expense Report - March 1999" & vbCrLf & _
"(values in 1,000 US$)"
End Sub
The routine sets up a variant array with some values, labels and colors, and then calls the DrawPieChart routine.
DrawPieChart is a generic pie-chart routine for the VSDraw control. It is not trivial code, but it is not very difficult
either. You should be able to understand what it does and to customize it without trouble.
Here is the DrawPieChart routine (it is pretty long, so we suggest you copy it to the clipboard and paste into your
project rather than typing it):
Sub DrawPieChart(vd As VSDraw, _
ByRef ChartData(), _
tit$)
Const Pi = 3.1416
Const Radius = 500
Dim i%, arc#, start#, tot#, a#, cx#, cy#
With vd
'---------------------------------------------
' clear control
.Clear
'---------------------------------------------
' setup scale based on pie radius
' use negative ScaleHeight so positive is up
.ScaleWidth = 2.75 * Radius
.ScaleLeft = 0
.ScaleHeight = -.ScaleWidth
.ScaleTop = .ScaleWidth
'---------------------------------------------
' calculate total value to scale pie slices
For i = 0 To UBound(ChartData, 2)
tot = tot + Abs(ChartData(0, i))
Next
'---------------------------------------------
' set up to draw pie slices
.PenColor = vbBlack
.PenWidth = 0
.PenStyle = psSolid
.BrushStyle = bsSolid
'---------------------------------------------
' draw shadow slices in gray
.BrushColor = RGB(90, 90, 90)
' calculate arc
arc = Abs(ChartData(0, i)) / tot * 2 * Pi
a = start + arc / 2
' get slice origin
cx = .ScaleWidth / 2 + Radius / 20
cy = .ScaleWidth / 2 + Radius / 20
43
' explode slices with negative amounts
If ChartData(0, i) < 0 Then
cx = cx + Radius / 10 * Cos(a)
cy = cy + Radius / 10 * Sin(a)
End If
' draw slice
If arc > 0 Then
.DrawCircle cx, cy, Radius, start, start + arc
End If
' update start
start = start + arc
Next
'---------------------------------------------
' draw real slices in given colors
start = 0
' set color
.BrushColor = ChartData(2, i)
' calculate arc
a = start + arc / 2
' get slice origin
cx = .ScaleWidth / 2
cy = .ScaleWidth / 2
End If
' draw slice
If arc > 0 Then
.DrawCircle cx, cy, Radius, start, start + arc
End If
' update start
start = start + arc
Next
'---------------------------------------------
' set up to draw slice labels
.TextAlign = tadCenter
.TextColor = vbWhite
.FontBold = True
.FontSize = Radius / 10
'---------------------------------------------
' draw slice labels
start = 0
' calculate arc
a = start + arc / 2
' get slice origin
cx = .ScaleWidth / 2
cy = .ScaleWidth / 2
End If
' draw label
If arc > 0 Then
a = start + arc / 2
.X1 = cx + Radius * 2 / 3 * Cos(a)
.Y1 = cy + Radius * 2 / 3 * Sin(a) + .FontSize
.Text = ChartData(1, i) & vbCrLf & _
Abs(ChartData(0, i))
End If
' update start
start = start + arc
Next
'---------------------------------------------
' draw chart title
.X1 = .ScaleWidth / 2
44
.Y1 = .ScaleTop + .ScaleHeight + .FontSize * 2.5
.TextColor = vbBlack
.Text = tit
End With
End Sub
Step 3: Drawing Bar Charts

Drawing bar charts is very similar to drawing pie charts. We will use exactly the same data structure and organization
and add a new routine to draw the bar chart. Double-click on the Bar Chart button and add the following code to the
cmdBar_Click event handler:
Private Sub cmdBar_Click()
' set up chart data in variant array:

' col 0 has values, col 1 has labels, and
' col 2 has colors
Dim cd(2, 6)
cd(0, 0) = 30: cd(1, 0) = "Phone"
cd(0, 1) = 65: cd(1, 1) = "Payroll"
cd(0, 2) = 42: cd(1, 2) = "Equipment"
cd(0, 3) = 24: cd(1, 3) = "Rent"
cd(0, 4) = 52: cd(1, 4) = "Advertising"
cd(0, 5) = 12: cd(1, 5) = "Production"
cd(0, 6) = 22: cd(1, 6) = "Other"
cd(2, 0) = vbRed
cd(2, 1) = vbBlue
cd(2, 2) = vbGreen
cd(2, 3) = vbYellow
cd(2, 4) = vbCyan
cd(2, 5) = vbMagenta
cd(2, 6) = vbBlack
' draw chart

vd.FontName = "Tahoma"
DrawBarChart vd, cd, _
"Expense Report - March 1999" & vbCrLf & _
"(values in 1,000 US$)"
End Sub
As you can see, this routine is virtually identical to the one we used to draw the pie charts. The only differences are we
no longer use negative values, and the drawing routine is DrawBarChart. DrawBarChart is a generic bar-chart routine
for the VSDraw control. It is simpler than the pie chart routine, and shows some interesting scaling and text output
techniques.
Here is the DrawBarChart routine (again, we suggest you copy it to the clipboard and paste into your project rather
than typing it):
Sub DrawBarChart(vd As VSDraw, _
ByRef ChartData(), _
tit$)
Dim i#, max#, barwid#, stp#
With vd
'---------------------------------------------
' clear control
.Clear
'---------------------------------------------
' setup scale so chart will be scaled to the
' rectangle from (0,0) to (1000,1000)
.ScaleWidth = 1300
.ScaleLeft = -200
.ScaleHeight = -1300
.ScaleTop = 1100
.FontSize = 50
.FontBold = True
'---------------------------------------------
' calculate maximum amount for scaling bars
45
If ChartData(0, i) > max Then
max = ChartData(0, i)
End If
Next
'---------------------------------------------
' draw fat black box around chart
.PenColor = vbBlack
.PenStyle = psSolid
.PenWidth = 5
.BrushColor = BackColor
.DrawRectangle 0, 0, 1000, 1000
'---------------------------------------------
' draw horizontal grid
.FontBold = False
.TextAlign = tadRight
.PenWidth = 0
.PenStyle = psDot
stp = 1
If max > 30 Then stp = 10
If max > 30000 Then stp = 10000
For i = 0 To max Step stp
.X1 = -25
.Y1 = 1000 * i / max + .FontSize / 2
.Text = i
.Y1 = 1000 * i / max
If i > 0 And i < max Then
.DrawLine 0, .Y1, 1000, .Y1
End If
Next
'---------------------------------------------
' set up to draw bars
.PenWidth = 0
.PenStyle = psSolid
barwid = 1000 / 2 / (UBound(ChartData, 2) + 1)
'---------------------------------------------
' draw bars
.TextAlign = tadLeft
.TextAngle = -900
.TextColor = vbWhite
.FontBold = True
' set color
.BrushColor = ChartData(2, i)
' draw bar
.X1 = barwid + i / UBound(ChartData, 2) * _
(1000 - 2 * barwid)
.DrawRectangle .X1 - barwid / 2, 0, _
.X1 + barwid / 2, _
1000 * ChartData(0, i) / max
' draw label
.X1 = .X1 - .FontSize / 2
.Y1 = barwid / 2
.Text = ChartData(1, i) & _
" (" & ChartData(0, i) & ")"
Next
'---------------------------------------------
' draw chart title
.TextAlign = tadCenter
.TextAngle = 0
.TextColor = vbBlack
.FontSize = 50
.X1 = .ScaleLeft + .ScaleWidth / 2
.Y1 = .ScaleTop + .ScaleHeight + 3 * .FontSize
.Text = tit
End With
End Sub
46
That's it. The application can already draw pie and bar charts. We're almost done now.

We will add our standard Form_Resize event handler to make the VSDraw control resize with the form. Here it is:
With vd
.Move .Left, .Top, _
End With
End Sub
Note the error handling to prevent errors in case the user makes the form extremely small and some of the calculated
dimensions become negative.
Now, if you run the project and create a chart, you will notice that it resizes with the form. If you resize the form and
change its aspect ratio a lot, the charts may look a little distorted.
Our very last touch will give the user the option of keeping the chart size constant and scrolling to see whatever he
chooses. This is easy to do with the VSDraw's new properties Zoom, ZoomMode, PageWidth, and PageHeight. Just
add the following code to the chk_Click event handler:
Private Sub chk_Click()
' to use actual size, set zoom and drawing size

If chkActualSize.Value Then
vd.PageWidth = 8000
vd.PageHeight = 8000
vd.Zoom = 100
' otherwise, just stretch to fill the control

Else
vd.ZoomMode = zmStretch
End If
End Sub
The code is quite simple. If the user checks the Actual Size checkbox, the control sets the drawing size to 8000 by 8000
pixels, and the Zoom to 100%. This will add scrollbars to the control, if necessary. If the user unchecks the box, the
control sets the ZoomMode property to zmStretch and the drawing stretches to fill the control as usual.
Here is a picture of the final application in action:
47
This concludes the VSDraw Chart tutorial. You may want to customize the DrawPieChart and DrawBarChart
routines or to use them as a starting point to create other chart types (lines, multiple series, and so on) or a VB
UserControl-based chart control.
VSPrinter Examples
The following sections show examples that illustrate common techniques you can use when programming the VSPrinter
control. You can study the source code on the printed manual, or work on-line, copying the code from the help file into
VB.
Here is a list of the examples available:
Page n of m Shows two ways to generate document footers that contain

the current page number and the page count (with and without
overlays).
Shaded Table Shows simple table formatting using the AddTable method.
Table Formatting Shows simple table formatting using the TableCell property.
Data-based Tables Shows how you can use the AddTableArray method to
render data from databases.
Custom NavBar Button Shows how you can add custom buttons to the VSPrinter's
built-in document navigation bar.
Build an Index Shows how you can build an index for an existing document
based on a word list stored in a file. Uses the FindText
property.
Build a Table of Contents Shows how you can build a live table of contents. Uses
48
document tags (FindTag, RetrieveTag) to implement
hyperlinks.
Find Text Shows how you can search for string (find first/next) in a
VSPrinter document. Uses the FindText property.
Note: We provide many sample projects on the distribution CD, and more as posted on our Web site as they become
available. If you have an interesting sample you would like to share with others or a suggestion for one, please let us
know.
Page n of m
This example shows two methods for getting headers that indicate the total number of pages in the document (Page n of
m).
Method 1: Two Passes
This method is simple and adequate for short documents. It consists of creating the document twice: once just for
counting the pages, and once for creating the complete document.
Assuming the VSPrinter control is called vp and that there is a routine called CreateDocument that creates the
document, the following code would create the headers we want:
' pass 1: count the pages
vp.Header = "Page %d of ?" 'just a placeholder for now
vp.StartDoc
CreateDocument
vp.EndDoc
' pass 2: set the header, then create the document again
vp.Header = "Page %d of " & vp.PageCount ' actual page count
vp.StartDoc
CreateDocument
vp.EndDoc
This method is simple and works well, but it requires the document to be generated twice. This can be slow if the
document is long (over 30 pages or so) or if generating the document requires extensive work such as database access or
retrieving data from a network. For these situations, try the single-pass method, described below.
Method 2: Single Pass
This method uses overlays to accomplish the same tasks in a single pass. The headers are drawn on each page after the
document is complete. Here is the code:
' pass 1: create the document with no header
vp.Header = " "
vp.StartDoc
CreateDocument
vp.EndDoc
' pass 2: add the headers (not really a "pass"...)

vp.FontName = "Courier"
vp.FontSize = 10
For i = 1 To vp.PageCount
vp.StartOverlay i
vp.CurrentX = vp.MarginLeft
vp.CurrentY = vp.MarginTop - 300
vp = "Page " & i & " of " & vp.PageCount
vp.EndOverlay
Next
Try both methods with a document over 20 pages long and you should notice the difference in speed. The single pass
method is substantially faster, especially if the document is complex (with pictures, tables, and RTF text).
49
Shaded Table
This example shows how you can use the AddTable method to draw a table with rows of alternating colors.
Sub ShowTable()
' create format string (widths in Twips)

Dim f$
f = "+1440|+^1000|+^1000|+>700;"
' create header string (repeat across page breaks)

Dim h$
h = "Network|Country|Language|Code;"
' create some dummy data

ReDim b$(7)
b(1) = "Cartoon Network|USA|English|CAR;"
b(2) = "Deutsche Welle|Germany|German, English|DWL;"
b(3) = "Discovery|USA|English, Spanish|DCY;"
b(4) = "FOX|USA|English|FOX;"
b(5) = "TV5|Canada, France|French, Spanish|TV5;"
b(6) = "MTV|USA|English, Spanish|MTV;"
b(7) = "RAI Uno|Italy|Italian, English|RAI;"
' start document

vp.StartDoc
' show header and green first row

vp.AddTable f, h, b(1), vbYellow, vbGreen
' append row pairs (white, green)

Dim i%
For i = 2 To 6 Step 2
vp.AddTable f, h, b(i), vbYellow, , True
vp.AddTable f, h, b(i + 1), vbYellow, vbGreen, True
Next
' done
vp.EndDoc
End Sub
The above code creates this output:
Table Formatting
This example shows how to use the TableCell property to create and format a table.
With vp
.StartDoc
' start table definition

.StartTable
50
' create table with four rows and four columns
.TableCell(tcCols) = 4
.TableCell(tcRows) = 4
' set some column widths (default width is 0.5in)

.TableCell(tcColWidth, , 1) = "1in"
.TableCell(tcColWidth, , 2) = "1.3in"
' assign text to each cell

Dim r%, c%
For r = 1 To 4
For c = 1 To 4
.TableCell(tcText, r, c) = "Row " & r & " Col " & c
Next c
Next r
' format cell (1,1): make it span two columns, with a

' blue background, center alignment, and bold
.TableCell(tcColSpan, 1, 1) = 2
.TableCell(tcBackColor, 1, 1) = vbBlue
.TableCell(tcAlign, 1, 1) = taCenterMiddle
.TableCell(tcFontBold, 1, 1) = True
' set row height for row 1

' (default height is calculated to fit the contents)
.TableCell(tcRowHeight, 1) = "0.2in"
' format cell (3,2): make is span two columns, with a

' yellow background, center alignment, and bold
.TableCell(tcColSpan, 3, 2) = 2
.TableCell(tcBackColor, 3, 2) = vbYellow
.TableCell(tcAlign, 3, 2) = taCenterMiddle
.TableCell(tcFontBold, 3, 2) = True
' set row height for row 3

.TableCell(tcRowHeight, 3) = "0.2in"
' set row borders all around

.TableBorder = tbAll
' finish table definition

.EndTable
.EndDoc
End With
The above code creates this output:
Data-based Tables
This example shows how you can create tables that show data from a database. The user can pick from several recordsets
and the VSPrinter control is used to create a simple report that shows the data.
To create the DataTable example, start by adding the following controls to a new VB form:
 VSPrinter control (name it vp)
 ComboBox control (name it cmbSrc)
 Data control (name it Data1)
51
Add the following code to initialize the form and controls:
' initialize Data1 control

' (change the path so it points to the NWind.mdb file)
Data1.DatabaseName = "D:\VB98\Nwind.mdb"
' initialize recordset list

cmbSrc.AddItem "Employees: SELECT FirstName As First, " & _
"LastName As Last, Title FROM Employees"
cmbSrc.AddItem "Customers: SELECT Country,City,CompanyName AS Company," & _
"ContactName As Contact, Phone FROM Customers " & _
"ORDER BY Country, City"
cmbSrc.AddItem "Customers: SELECT CompanyName AS Company, " & _
"ContactName As Contact, Phone FROM Customers " & _
"ORDER BY CompanyName
cmbSrc.AddItem "Inventory: SELECT ProductName AS Product,UnitPrice AS Unit," & _
"UnitsInStock AS Stock,UnitPrice*UnitsInStock AS Inventory " & _
"FROM Products ORDER BY (UnitPrice * UnitsInStock) DESC"
cmbSrc.AddItem "Invoices: SELECT OrderID, ShipName AS Customer, " & _
"ShipCity AS City, " & _
"OrderDate AS Ordered, ExtendedPrice AS Total FROM Invoices " & _
"ORDER BY ExtendedPrice DESC"
' start with the first item

cmbSrc.ListIndex = 0
End Sub
Now that the controls are initialized, add the following code to generate a document whenever the user selects a new
record source:
Private Sub cmbSrc_Click()
' get record source string (trim comments up to ":")

Dim s$, i%
s = cmbSrc
i = InStr(s, ":")
If i > 0 Then s = Trim(Mid(s, i + 1))
' get recordset

Data1.RecordSource = s
Data1.Refresh
Dim rs As Recordset
Set rs = Data1.Recordset
' create document

With vp
' set up
.Header = "||Page %d"
.FontName = "Arial"
.FontSize = 10
.StartDoc
' show title

.Paragraph = "NorthWind Recordset. Query is:"
.FontBold = True
.Paragraph = s
.FontBold = False
.Paragraph = ""
' render recordset (main routine)

RenderRecordset vp, rs, 0
' done
.EndDoc
End With
End Sub
52
Now we are almost done. The only thing missing is the main routine, the one that renders the recordset. The following
RenderRecordset routine is simple and generic. It takes as parameters a VSPrinter control, a Recordset object (DAO
or ADO), and a maximum height for the table rows. The routine reads the recordset into an array using the GetRows
method, creates a table using the AddTableArray method, and sets column widths and alignment using the TableCell
property:
Sub RenderRecordset(vp As VSPrinter, rs As Recordset, maxh As Single)
Dim arr, i%, j%, wid!, fmt$, hdr$
' read recordset into an array

rs.MoveLast
rs.MoveFirst
i = rs.RecordCount
If i = 0 Then Exit Sub
arr = rs.GetRows(i)
' create table header and dummy format

For i = 0 To rs.Fields.Count - 1
If i > 0 Then hdr = hdr & "|": fmt = fmt & "|"
hdr = hdr & rs.Fields(i).Name
fmt = fmt & "500"
Next
' create table

vp.StartTable
vp.AddTableArray fmt, hdr, arr
' format table

For i = 0 To rs.Fields.Count - 1
' right-align numbers and dates

Select Case rs.Fields(i).Type
Case dbBigInt, dbByte, dbChar, dbCurrency, dbDecimal, dbDouble, _
dbFloat, dbInteger, dbLong, dbNumeric, dbSingle, dbDate
vp.TableCell(tcColAlign, , i + 1) = taRightTop
End Select
' set column width

If rs.Fields(i).Type = dbMemo Then
vp.TableCell(tcColWidth, , i + 1) = "2.5in"
Else
' select longest string from 1st 100 records

fmt = ""
For j = 0 To UBound(arr, 2)
If j > 100 Then Exit For
If Len(fmt) < Len(arr(i, j)) Then fmt = arr(i, j)
Next
If Len(rs.Fields(i).Name) > Len(fmt) Then fmt = rs.Fields(i).Name
' set column width so the longest string fits

vp.TableCell(tcColWidth, , i + 1) = vp.TextWidth(fmt) * 1.4
Next
' format header row (0)

vp.TableCell(tcBackColor, 0) = vbYellow
vp.TableCell(tcRowHeight, 0) = vp.TextHeight("Test") * 1.1
vp.TableCell(tcAlign, 0) = taLeftMiddle
' make sure it all fits, squeeze columns if necessary

For i = 1 To vp.TableCell(tcCols)
wid = wid + vp.TableCell(tcColWidth, , i)
Next
vp.GetMargins
If wid > vp.X2 - vp.X1 Then
wid = (vp.X2 - vp.X1) / wid * 0.95
For i = 1 To vp.TableCell(tcCols)
vp.TableCell(tcColWidth, , i) = wid * _
vp.TableCell(tcColWidth, , i)
53
Next
End If
' honor maximum row height

' (in case there are long memo entries)
If maxh > 0 Then
For i = 1 To vp.TableCell(tcRows)
If vp.TableCell(tcRowHeight, i) > maxh Then
vp.TableCell(tcRowHeight, i) = maxh
End If
Next
End If
' done with table

vp.EndTable
End Sub
That's it. Run the sample and you should something that looks like the following image:
Note: If the table is too wide to fit the page, the RenderRecordset routine squeezes all columns proportionally until the
table fits. This is a very simple approach, but it is not very good. It would be better to try squeezing only text and memo
fields, since text can be wrapped and numbers cannot. This is left as an exercise.
Custom NavBar Button

This example shows how you can add your own custom buttons the VSPrinter's built-in navigation bar. The custom
buttons are created using standard VB controls and "blend in" with the built-in buttons.
To create the custom buttons, start by adding the following controls to a new VB form:
 Two Image controls (name them img(0) and img(1))
 Two PictureBox controls (name them picBtn(0) and picBtn(1))
54
Set the Picture property on the Image controls to icons of your choice. The buttons will look best for icons about 10
pixels tall by 14 pixels wide, but any image will work.
Then add the following code to the form:
' align VSPrinter control to the top of the form

vp.Align = vbAlignTop
' constants for custom buttons

Const pixLeft = 180, pixTop = 2
Const pixWid = 20, pixHei = 14, pixSpace = 4
' get conversion constants

Dim tppX!, tppY!
tppX = Screen.TwipsPerPixelX
tppY = Screen.TwipsPerPixelY
' configure button controls

Dim i%, x!
For i = 0 To 1
With picBtn(i)
' initialize button appearance

.AutoRedraw = True
.BorderStyle = 0
.Picture = img(i).Picture
' move button into place

x = (pixLeft + (pixWid + pixSpace) * i) * tppX
.Move vp.Left + x, vp.Top + pixTop * tppY, pixWid * tppX, pixHei * tppY
.ZOrder
' frame button

FrameBtn picBtn(i), False
End With
Next
End Sub

vp.Height = ScaleHeight
End Sub
This code initializes the appearance of each button, moves it into place, then draws a frame around the button. (The code
assumes that the navigation bar is drawn on the top of the control). The following FrameBtn routine can draw two types
of frame: pushed and released.
Private Sub FrameBtn(pic As PictureBox, bPushed%)
' get conversion constants

Dim tppX!, tppY!
tppX = Screen.TwipsPerPixelX
tppY = Screen.TwipsPerPixelY
' draw button frame

With pic
If bPushed Then .ForeColor = &H80000010 Else .ForeColor = &H80000014
pic.Line (0, 0)-(pic.Width, pic.Height), , B
If bPushed Then .ForeColor = &H80000014 Else .ForeColor = &H80000010
pic.Line (-100, -100)-(pic.Width - tppX, pic.Height - tppY), , B
End With
End Sub
At this point, you can run the project and see that the custom buttons are visible and look like the standard built-in
buttons.
To make the buttons work, we need some mouse-handling code. We'll start by making the buttons respond to double-
clicks. The first button will zoom in and the second will zoom out:
55
Private Sub picBtn_DblClick(Index As Integer)
Select Case Index
Case 0 ' zoom in
vp.Zoom = vp.Zoom + vp.ZoomStep
Case 1 ' zoom out
vp.Zoom = vp.Zoom - vp.ZoomStep
End Select
End Sub
Finally, add the following code to make the buttons respond to the MouseDown, MouseMove, and MouseUp
events:
Private Sub picBtn_MouseDown(Index As Integer, Button As Integer, _
Shift As Integer, X As Single, Y As Single)
If Button <> 1 Then Exit Sub
picBtn(Index).Tag = "*" ' ** PUSHED
FrameBtn picBtn(Index), True
End Sub
Private Sub picBtn_MouseMove(Index As Integer, Button As Integer, _
If (Button And 1) = 0 Then Exit Sub
With picBtn(Index)
If X < 0 Or Y < 0 Or X > .Left Or Y > .Height Then
picBtn(Index).Tag = "" ' ** RELEASED
FrameBtn picBtn(Index), False
Else
picBtn(Index).Tag = "*" ' ** PUSHED
FrameBtn picBtn(Index), True
End If
End With
End Sub
Private Sub picBtn_MouseUp(Index As Integer, Button As Integer, _
If picBtn(Index).Tag = "*" Then
picBtn_DblClick Index ' ** HANDLE CLICK
End If
picBtn(Index).Tag = ""
FrameBtn picBtn(Index), False
End Sub
The MouseDown routine makes sure the left button was pushed, sets the picBtn(Index).Tag property to a flag that
indicates the button is pushed, and draws the pushed frame around the button. The MouseMove routine pushes or
releases the button depending on whether the cursor is over the button. The MouseUp routine checks whether the button
in the pushed state when the mouse was released. If so, it calls the picBtn_DblClick routine to handle the click (as a
double-click would).
If you run the project again, you will see that the custom buttons behave just like the built-in ones.
Find Text
This example shows how you can find text in a VSPrinter document using the FindText property.
To create the Find example, start by adding the following controls to a new VB form:
 TextBox control (name it txtText)
 Two CommandButton controls (name them btnFind(0) and btnFind(1)).
Set the Caption property of the command buttons to Find and Find Next.
Next, you will need an RTF file that will be loaded into the VSPrinter control. Copy any RTF file to the sample's
directory and name it "TEXT.RTF".
Then add the following code to load the RTF file into the control and manage the state of the Find and Find Next
buttons:
56
vp.Footer = "TEXT.RTF||Page %d"
vp.PrintFile App.Path & "\TEXT.RTF"
vp.PenWidth = 50
vp.PenColor = 200
vp.PenStyle = psSolid
vp.BrushStyle = bsTransparent
End Sub
Private Sub txtFind_Change()
btnFind(0).Enabled = (Len(txtFind) > 0)
btnFind(1).Enabled = (Len(txtFind) > 0)
End Sub
Finally, here is the main part of the code. It handles the Find and Find Next button clicks:
Private Sub btnFind_Click(Index As Integer)
Static iStartPage%
Static fStartY!
' reset to find first

If Index = 0 Then
iStartPage = 0
fStartY = 0
End If
' look for text

iStartPage = vp.FindText(txtFind, , iStartPage, , fStartY)
' not found? reset and bail

If iStartPage <= 0 Then
MsgBox "Cannot find the string '" & txtFind & "' in the document.", _
vbInformation, "Not Found"
fStartY = 0
Exit Sub
End If
' save top Y for next match

fStartY = vp.Y2
' show what we found

vp.StartOverlay iStartPage
vp.DrawRectangle vp.X1, vp.Y1, vp.X2, vp.Y2
vp.EndOverlay
vp.PreviewPage = iStartPage
vp.ScrollIntoView vp.X1, vp.Y1, vp.X2, vp.Y2
End Sub
The code uses static variables (iStartPage and fStartY) to keep the page number and vertical position for the last match.
These variables are reset when the user clicks the Find First button.
To find the text, the routine calls the FindText property using the iStartPage and fStartY variables. If the text is not
found, the routine shows a dialog box and returns. If the text is found, the fStartY variable is updated, a red frame is
drawn around the text on a page overlay, and the text is scrolled into view.
Note: The text returned by the FindText property includes the entire string that was added to the document when it was
created, not just the argument passed to FindText.
Build an Index
This example shows how you can build an index for a VSPrinter document based on a list of words loaded from a text
file. The example is based on the FindText property.
To create the Index example, start by adding the following controls to a new VB form:
 CommandButton control (name it btnDoIt).
Next, you will need two external files:
57
 An RTF file that will be loaded into the VSPrinter control and indexed. Copy this file to the sample's directory and
name it text.rtf.
 A plain text file containing a list of words to be indexed. The file should have one word (or expression) per line.
Copy this file to the sample's directory and name it words.txt.
Add the following code to the btnDoIt_Click event handler:
Private Sub btnDoIt_Click()
' user interface

btnDoIt.Enabled = False
vp.NavBarText = "Loading..."
' set up to create document

vp.Footer = "TEXT.RTF||Page %d"
vp.PageBorder = pbColBottom
vp.Styles.Add "Scratch", vpsAll
' load RTF file into document

vp.StartDoc
vp.PrintFile App.Path & "\text.rtf"
' start building index

vp.NewPage ' start index on a new page
vp.FontBold = True ' print title
vp.FontSize = 18
vp = "Index"
vp.Columns = 2 ' index body on two columns
vp.FontName = "Times New Roman"
vp.FontBold = False ' index body font
vp.FontSize = 9
vp.MarginTop = vp.CurrentY
vp.IndentLeft = "1in" ' hanging indent
vp.IndentFirst = -vp.IndentLeft
vp.IndentTab = 200
' build index

vp.Tag = vp.PageCount
Open App.Path & "\words.txt" For Input As #1
Dim sWord$
While Not EOF(1)
Line Input #1, sWord
AddToIndex vp, sWord
Wend
Close #1
' done
vp.EndDoc
vp.NavBarText = ""
btnDoIt.Enabled = True
vp.Styles.Apply "Scratch"
' show index page

vp.PreviewPage = vp.Tag
End Sub
This routine loads the RTF file into the VSPrinter control, then opens the file containing the words to be indexed and
calls the AddToIndex routine for each word. The AddToIndex routine is the one that does the interesting part of the
work, and here it is:
Sub AddToIndex(vp As VSPrinter, sWord$)
' user feedback

vp.NavBarText = "Indexing " & sWord
DoEvents
' look for word in document, build list of pages where it was found
Dim pg%, sPages$
Do
58
pg = vp.FindText(sWord, , pg + 1)
If pg <= 0 Then Exit Do
If Len(sPages) > 0 Then sPages = sPages & ", "
sPages = sPages & pg
Loop
' if not found, no entry

If Len(sPages) = 0 Then Exit Sub
' compress page list ranges

sPages = CompressPageRange(sPages)
' add word and page list to index

vp.FontItalic = True
vp.Text = sWord & vbTab
vp.FontItalic = False
vp.Paragraph = sPages
End Sub
The AddToIndex routine uses the FindText property to build a list of pages where the word (or expression) was found
in the document, compresses the page list to make it easier to read, then writes the index entry into the main document.
The CompressPageRange routine is optional. It changes lists such as "1, 2, 3, 4, 5, 10, 11, 12, 13" into "1-5, 10-13",
which is easier to read and makes the index look less cluttered. Here is the code:
Function CompressPageRange(s$) As String
Dim v, i%, iLast%, iRun%, sRet$
' split page list into vector and initialize list

v = Split(s, ", ")
iLast = v(0)
sRet = iLast
' process vector

' (iRun keeps a count of consecutive pages)
For i = 1 To UBound(v)
If Val(v(i)) = iLast + 1 Then
iRun = iRun + 1
Else
If iRun = 1 Then sRet = sRet & ", " & iLast
If iRun > 1 Then sRet = sRet & "-" & iLast
sRet = sRet & ", " & v(i)
iRun = 0
End If
iLast = v(i)
Next
' don't forget the end of the last run

If iRun = 1 Then sRet = sRet & ", " & iLast
If iRun > 1 Then sRet = sRet & "-" & iLast
' done
CompressPageRange = sRet
End Function
That's it. The following image shows what a typical index looks like:
59
Build a Table of Contents
This example shows how you can build a Table of Contents for a VSPrinter document. The example is based on the use
of document tags. The sample also takes advantage of the tags to implement hyperlinks, so if you right-click on an entry
in the Table of Contents, the VSPrinter control will jump to the topic in the main document.
To create the TOC example, start by adding the following controls to a new VB form:
 CommandButton control (name it btnDoIt).
Add the following code to the btnDoIt_Click event handler:
Private Sub btnDoIt_Click()
With vp
' set up document

.Orientation = orPortrait
.PageBorder = pbBottom
.Footer = "VSPrint8|TOC Sample|%d"
' define styles

.SpaceAfter = "8pt"
.IndentLeft = "0.75in"
.Styles.Add "Normal", vpsAll
.SpaceBefore = "20pt"
.IndentLeft = 0
.FontBold = True
.FontSize = 2 * .FontSize
.Styles.Add "Heading", vpsAll
.Styles.Apply "Normal"
.SpaceAfter = 0
.IndentLeft = 0
.FontBold = True
.TextColor = RGB(0, 0, 150)
.TableBorder = tbNone
.Styles.Add "TOC", vpsAll
' create document with 50 headers
.StartDoc
Dim i%, pg%, pgTOC%, s$
For i = 1 To 50
60
' create ith header with header tag
s = GetRandomTitle()
.Styles.Apply "Heading"
.StartTag "H1|" & i & "|" & s
.Paragraph = i & " " & s
.EndTag
' create some text

s = GetRandomText()
.Paragraph = s
Next
' create TOC
.NewPage
pgTOC = .PageCount
.Styles.Apply "Heading"
.Paragraph = "Random Document" & vbCrLf & "Table of Contents"
.IndentLeft = 0
.Paragraph = "This is a live table of contents. " & _
"Right-click on any item to jump to it."
.Footer = ""
' look for tags, add an entry for each one

vp.Styles.Apply "TOC"
For i = 1 To 20000
' look for ith tag, quit if not found

pg = vp.FindTag("H1|" & i & "|")
If pg <= 0 Then Exit For
' retrieve full tag text and add TOC entry

s = vp.RetrieveTag(vp.X1, vp.Y1, vp.X2, vp.Y2, pg)
AddToTOC vp, s, pg
Next
vp.Styles.Apply "Normal"
' done
.EndDoc
' move TOC to front

.MovePages pgTOC, .PageCount, True
End With
End Sub
This routine starts by creating a long document consisting of 50 random headings with bodies of random text. Each
heading has a "heading tag" associates with it. The tags are created with the StartTag and EndTag methods, and have
the format "H1|n|s", where H1 indicates this is a level 1 heading, n is the heading's sequential number, and s is the
heading text.
When the document is done, the routine starts a new page with the Table of Contents. Then it builds the table of contents
by searching the document for the heading tags ("H1|1", "H1|2", and so on) using the FindTag property. For each tag
found, the code uses the RetrieveTag property to retrieve the full tag text, and then calls the AddToTOC routine to
write out the TOC entry.
Finally, the MovePages method is used to move the TOC to the beginning of the document.
The AddToTOC routine follows:
Sub AddToTOC(vp As VSPrinter, s As String, pg As Integer)
Dim sDots$, v
' create a line of dots to include in the entry

sDots = " . . . . . . . . ."
sDots = sDots & sDots & sDots & sDots
' create TOC tag

vp.StartTag "TOC|" & pg & "|" & vp.Y1 & "|" & vp.Y2
61
' create TOC entry ("~" prevents col 2 from wrapping dots)
v = Split(s, "|")
vp.AddTable ">800|~6000|>500", "", _
v(1) & ":|" & v(2) & sDots & "|" & pg
' finish TOC tag and be done

vp.EndTag
End Sub
The AddToTOC routine builds a TOC tag formatted as "TOC|pg|y1|y2", where pg is the page where the entry can be
found in the document body, and y1 and Y2 are the vertical coordinates of the entry. This information will be used to
provide hyperlinks into the document body. Then is uses the AddTable method to write out the actual TOC entry.
To take advantage of the TOC tags and make the hyperlinks work, add the following vp_MouseDown event handler:
Private Sub vp_MouseDown(Button As Integer, Shift As Integer, _
X As Single, Y As Single)
Dim s$, v
' make sure we're using the right button

' get TOC tag

s = vp.RetrieveTag(X, Y, , , , True)
If Left(s, 4) <> "TOC|" Then Exit Sub
' jump to saved position

v = Split(s, "|")
vp.PreviewPage = v(1) + vp.FindTag("H1|1") - 1
vp.ScrollIntoView 0, v(2), 300, v(3)
End Sub
The routine starts by checking which mouse button was pressed. Then it tries to retrieve a TOC tag from the current
mouse position (using the RetrieveTag property).
If a TOC tag is found, the code calculates the page number by extracting the original page number from the tag (v(1))
and applying an offset to account for the fact that the page number changed when we moved the tag to the front of the
document using the MovePages method.
Finally, the jump is executed using the PreviewPage property and ScrollIntoView method. This makes the selected
heading visible to the user.
The only thing missing is the code that generates random text. Here it is:
Function GetRandomTitle() As String
Dim s$, v
v = Split("Learning|Explaining|Examining|Applying|Using|Destroying", "|")
s = s & v(Rnd() * UBound(v)) & " "
v = Split("Modern Art|Fast Food|Gardening|Investments", "|")
s = s & v(Rnd() * UBound(v)) & " "
v = Split("Quickly|Painlessly|Slowly|Painfully|With Panache", "|")
s = s & v(Rnd() * UBound(v))
GetRandomTitle = s
End Function
Function GetRandomText() As String
Dim s$, i%
For i = 0 To 10 + Rnd * 50
s = s & GetRandomSentence()
If Rnd < 0.3 Then s = s & vbCrLf
Next
GetRandomText = s
End Function
Function GetRandomSentence() As String
Dim s$, v
v = Split("Artists|Modern thinkers|Gardeners|Experts|Some people", "|")
s = s & v(Rnd() * UBound(v)) & " "
v = Split("know|seem to ponder|would care about|often discuss|dream about", "|")
s = s & v(Rnd() * UBound(v)) & " "
v = Split("the movies|chicken soup|tea|many things|sushi|my car", "|")
62
s = s & v(Rnd() * UBound(v)) & " "
v = Split("incessantly|too much|easily|without reason|rapidly|sadly", "|")
s = s & v(Rnd() * UBound(v))
GetRandomSentence = s & ". "
End Function
That's it. If you run the program now, you will get output that looks like the following image. Try tracing through the
code to see exactly how the tags work.
Control Reference
VSPrinter Control
The VSPrinter control allows you to quickly and easily create documents for printing and previewing. It supports
multiple columns, text wrapping, headers and footers, tables, and graphics. You can implement multiple page print
previews with zooming, panning, and paging by setting a single property. The new VSPrinter control has a thumbnail
preview mode that lets you see many pages at once.
The VSPrinter control is capable of exporting HTML and RTF documents that can be viewed and edited with your
favorite word processor, or posted on the Web. It also features an optional built-in document navigation bar that allows
users to zoom and page through preview documents.
The VSPrinter control allows you to save the documents you create to disk, and uses an efficient compression engine so
the documents consume little disk space. The compression and archiving routines are exposed through the Archive
method and ArchiveInfo property, which allow you to use compression for other purposes besides saving and loading
63
VSPrinter documents. VSPrinter archives are not PKZIP-compatible, but they are compatible with archive files created
with ComponentOne's VSFlexGrid Pro control.
Use the VSPrinter control to create sophisticated reports, either based on database tables or from arbitrary sources. You
may also use it to produce form-type documents, newsletters, format and print data files, or to let your application create
any type of custom output it needs.
Note: Before you can use a VSPrinter control in your application, you must add the VSPrint8.ocx file to your project.
Please refer to the VB documentation for details on adding controls to your projects.
To distribute applications you create with the VSPrinter control, you must install and register it on the user's computer.
The Setup Wizard provided with Visual Basic provides tools to help you do that. Please refer to the Visual Basic manual
for details.
The VSPrinter control provides the following properties, events and methods:
All of the properties, events and methods for the VSPrinter control are listed in the following tables. Properties, events,
and methods that apply only to this control, or that require special consideration when used with it, are marked with an
asterisk (*). These are documented in later sections. For documentation on the remaining properties, see the Visual Basic
documentation.
VSPrinter Properties
*AbortCaption Returns or sets the caption for the default Abort dialog.
*AbortTextButton Returns or sets the caption for the button in the default Abort
dialog.
*AbortTextDevice Returns or sets the caption for the Device string in the default
Abort dialog.
*AbortTextPage Returns or sets the caption for the Page string in the default
Abort dialog.
*AbortWindow Returns or sets whether an Abort dialog will appear while the
control is printing.
*AbortWindowPos Returns or sets the placement for the default Abort dialog.
*AccessibleDescription Gets or sets the description of the control used by accessibility
client applications.
*AccessibleName Gets or sets the name of the control used by accessibility client
applications.
*AccessibleRole Gets or sets the role of the control used by accessibility client
applications.
*AccessibleValue Gets or sets the value of the control used by accessibility client
applications.
*Action Executes an action such as 'StartDoc' or 'EndDoc'.
Appearance See the Visual Basic documentation.
*ArchiveInfo Gets information from a ComponentOne archive file.
*AutoLinkNavigate Gets or sets whether the control should automatically detect
hyperlinks embedded in the preview document, fire the Value
event, and change the cursor or perform the navigation
automatically.
*AutoRTF Returns or sets whether RTF text should be automatically
64
detected.
BackColor See the Visual Basic documentation.
BorderStyle See the Visual Basic documentation.
*BrushColor Returns or sets the color of the brush used to fill graphical
objects.
*BrushStyle Returns or sets the style of the brush used to fill graphical
objects.
*CalcParagraph Calculates the size of a paragraph, in twips, and returns results
in TextWid, TextHei, X1, Y1, X2, and Y1.
*CalcPicture Calculates the size of a picture, in twips, and returns results in
X1, Y1, X2, and Y1.
*CalcTable Calculates the size of a table, in twips, and returns results in
TextWid, TextHei, X1, Y1, X2, and Y1.
*CalcText Calculates the size of a string, in twips, and returns results in
TextWid, TextHei, X1, Y1, X2, and Y1.
*CalcTextRTF Calculates the size of an RTF string, in twips, and returns
results in TextWid, TextHei, X1, Y1, X2, and Y1.
*Collate Returns or sets whether multiple copies will be collated.
*ColorMode Returns or sets the color mode on color printers.
*Columns Returns or sets the number of columns on a page.
*ColumnSpacing Returns or sets the spacing between columns, in twips.
*Copies Returns or sets the number of copies to print.
*CurrentColumn Returns the number of the column being printed.
*CurrentLine Returns the number of the line being printed.
*CurrentPage Returns the number of the page being printed.
*CurrentX Returns or sets the horizontal position of the cursor, in twips
from the left of the page.
*CurrentY Returns or sets the vertical position of the cursor, in twips from
the top of the page.
*DefaultDevice Returns or sets whether device changes affect the Windows
default settings.
*Device Returns or sets the name of the current printer.
*Devices Returns the names of the printing devices available (zero-based
vector).
*DocName Returns or sets the name of the current document (alias for
FileName).
*DPI Returns the resolution of the printing device, in dots per inch.
*Draw Draws an object within the rectangle defined by the X1, Y1,
X2, and Y2 properties.
*Driver Returns the name of the current printer driver.
*Duplex Returns or sets duplex or double-sided printing.
65
*EmptyColor Returns or sets the color of the area around the preview page.
Enabled Returns/sets a value that determines whether an object can
respond to user-generated events.
*Error Returns a code that describes an error condition.
*ErrorDescription Returns a message that describes an error condition (see also
the Error property).
*ExportFile Returns or sets the name of an export file of type defined by the
VSPrinter property.
*ExportFormat Returns or sets the format of the output file (HTML or RTF).
*ExportNavBar Returns or sets the HTML template to be used for the
navigation bar in paged HTML export files.
*ExportRaw Injects raw text into the output file specified by the VSPrinter
property.
*FileName Returns or sets the name of the current document.
*FindTag Finds a tag in the current document, returns the page and
bounding rectangle (in X1,Y1,X2,Y2) for the match.
*FindText Finds text in the current document, returns the page and
bounding rectangle (in Y1,X2,Y2,VSPrinter) for the match.
Font Returns a Font object.
*Footer Returns or sets the footer text.
*hDC Returns the control's current hDC.
*HdrColor Returns or sets the color used to print headers and footers.
*HdrFont Returns or sets the font used to draw headers and footers.
*Header Returns or sets the header text.
hWnd Returns a handle (from Microsoft Windows) to an object's
window.
*IndentFirst Returns or sets an additional left indent for the first line of each
paragraphs, in twips.
*IndentLeft Returns or sets an additional left indent for the first line of each
paragraphs, in twips.
*IndentRight Returns or sets the right indent for paragraphs, in twips.
*IndentTab Returns or sets the left indent for the first line of a paragraph, in
twips.
*LargeChangeHorz Returns or sets the amount of change to the VSPrinter property
when the user clicks the scroll bar area.
*LargeChangeVert Returns or sets the amount of change to the VSPrinter property
when the user clicks the scroll bar area.
*LineSpacing Returns or sets the line spacing, as a percentage (for example,
100 is single spacing, 200 is double spacing).
*LoadPicture Returns a picture loaded from a file or URL.
*MarginBottom Returns or sets the bottom margin, in twips.
66
*MarginFooter Returns or sets the footer margin, in twips.
*MarginHeader Returns or sets the header margin, in twips.
*MarginLeft Returns or sets the left margin, in twips.
*MarginRight Returns or sets the right margin, in twips.
*MarginTop Returns or sets the top margin, in twips.
*Measure Returns width and height of a string, in twips, in TextHei and
VSPrinter properties/
*Measuring Returns True if the control is measuring text, False if it is
rendering
MouseIcon Sets a custom mouse icon.
MousePointer Returns/sets the type of mouse pointer displayed when over
part of an object.
*NavBar Returns True if the control is measuring text, False if it is
rendering
*NavBarColor Returns or sets the color of the document navigation bar.
*NavBarMenuText Returns or sets the text that appears on the NavBar Zoom menu
*NavBarText Returns or sets the text displayed on the document navigation
bar.
*Navigation Returns or sets the type of document navigation interface
provided (mouse, mouse wheel, or keyboard).
*NDevices Returns the number of printing devices available.
*NPorts Returns the number of ports to which the current printer is
connected.
*Orientation Returns or sets the paper orientation.
*OutputFileName Returns or sets the name of a printer output file (if empty,
output is sent to the printer).
*PageBorder Returns or sets the type of border to draw around each page.
*PageCount Returns the number of pages in the current document.
*PageHeight Returns the page height, in twips.
*PageWidth Returns the page width, in twips.
*PalettePicture Returns or sets a picture with a palette that is used to render the
document.
*PaperBin Returns or sets the paper bin to use.
*PaperBins Returns whether a given paper bin is available on the current
printer.
*PaperHeight Returns or sets the height of a custom paper size, in twips.
*PaperSize Returns or sets a standard paper size.
*PaperSizes Returns whether a given page size is available on the current
printer.
*PaperWidth Returns or sets the width of a custom paper size, in twips.
67
*Paragraph Renders a paragraph on the page at the current cursor position.
*PenColor Returns or sets the color of the pen used to outline graphical
objects.
*PenStyle Returns or sets the style of the pen used to outline graphical
objects
*PenWidth Returns or sets the width of the pen used to outline graphical
objects.
*PhysicalPage Returns or sets whether to use the physical size of the page or
on its printable area.
Picture Returns a picture of the current preview page or sets a picture
to be displayed on the page.
*Polygon Draws a polygon defined by a string of X,Y coordinates.
*Polyline Draws a line defined by a string of X,Y coordinates.
*Port Returns or sets the name of the current port.
*Ports Returns the names of the ports to which the current printer is
connected.
*Preview Returns or sets whether output saved for previewing or sent
directly to the printer.
*PreviewPage Returns or sets the current preview page (first page is 1).
*PreviewPages Returns the number of pages displayed in the preview area.
*PrintQuality Returns or sets the print quality.
*ProportionalBars Returns or sets whether the scrollbar thumbs (VSPrinter
Control) should be proportional to the size of the visible area.
*ReadyState Returns the current state of the control.
*RenderControl Renders an OPP-enabled control (such as the VSFlexGrid) on
the page.
*RetrieveTag Returns a string containing the first tag found on a region of the
current document.
*RetrieveText Returns a string containing the text on a region of the current
document.
*ScaleOutput Returns or sets the percentage by which the printed output is to
be scaled.
*ScrollLeft Returns or sets the left coordinate of the visible area, in twips.
*ScrollTop Returns or sets the top coordinate of the visible area, in twips.
*ShowGuides Returns or sets whether margin guides are displayed on the
page.
*SmallChangeHorz Returns or sets the amount of change to the VSPrinter property
when the user clicks the scroll arrow.
*SmallChangeVert Returns or sets the amount of change to the VSPrinter property
when the user clicks the scroll arrow.
*SpaceAfter Returns or sets the vertical distance after each paragraph, in
twips.
68
*SpaceBefore Returns or sets the vertical distance before each paragraph, in
twips.
*Styles Returns a collection of styles that can be applied to the
document.
*Table Renders a table on the page.
*TableBorder Returns or sets the type of border for tables.
*TableCell Returns or sets properties of a table cell or range.
*TablePen Returns or sets the width of the borders between table cells.
*TablePenLR Returns or sets the width of the left and right table borders.
*TablePenTB Returns or sets the width of the top and bottom table borders.
*TableSep Returns or sets the characters used by tables as row and column
separators.
*Text Renders a string on the page at the current cursor position.
*TextAlign Returns or sets the alignment of printed paragraphs, textboxes,
and tables.
*TextAngle Returns or sets the text angle, in tenths of degree.
*TextColor Returns or sets the color used to print text.
*TextHei Returns the height of a string measured with the Measure
property, in twips.
*TextHeight Returns the height of a string, in twips.
*TextRTF Renders RTF text on the page at the current cursor position.
*TextWid Returns the width of a string measured with the VSPrinter
property, in twips.
*TextWidth Returns the width of a string, in twips.
*Track Returns or sets whether scrolling occurs as the user drags the
scroll thumb.
*TrueType Returns or sets how TrueType fonts should be printed.
*TwipsPerPixelX Returns the number of twips per printer pixel in the horizontal
direction.
*TwipsPerPixelY Returns the number of twips per printer pixel in the vertical
direction.
*URL Returns or sets the name of a URL (Universal Resource
Locator) to load into the control.
*Version Returns the version of the control currently loaded.
*X1 Returns or sets the left coordinate of the rectangle used with the
VSPrinter property.
*X2 Returns or sets the right coordinate of the rectangle used with
the VSPrinter property.
*Y1 Returns or sets the top coordinate of the rectangle used with the
VSPrinter property.
*Y2 Returns or sets the bottom coordinate of the rectangle used with
69
the VSPrinter property.
*Zoom Returns or sets the preview scale: set to a percentage, or zero to
fill the control.
*ZoomMax Returns or sets the maximum valid zoom factor.
*ZoomMin Returns or sets the minimum valid zoom factor.
*ZoomMode Sets or returns the zoom mode (explicit percentage or one of
the automatic settings).
*ZoomStep Returns or sets the step for zooming with the mouse.
VSPrinter Methods
*AddLink Adds a hyperlink to the document.

*AddLinkTarget Adds a Target tag (%PDFName|<name>) to the document at
the cursor position.
*AddTable Renders a table with row headers and special formatting.
*AddTableArray Renders a variant array as a table with row headers and special
formatting.
*Archive Adds, extracts, or deletes files from a ComponentOne archive
file.
*Clear Clears the control, destroying any currently loaded document.
*ClientToPage Converts mouse coordinates to page coordinates.
*DrawCircle Draws a circle, circular wedge, or circular arc.
*DrawEllipse Draws an ellipse, wedge, or arc.
*DrawLine Draws a line segment.
*DrawPicture Draws a picture.
*DrawRectangle Draws a rectangle.
*EndDoc Fired after a document is successfully printed.
*EndOverlay Closes a page that was opened with the StartOverlay method.
*EndTable Renders table defined since call to StartTable.
*EndTag Ends the definition of a document tag started with StartTag.
*GetMargins Returns the printable area, excluding margins, in the X1, Y1,
*KillDoc Cancels and deletes the current document.
*LoadDoc Loads a document from disk.
*MovePages Moves a group of pages to the start or to the end of the
document
*NewColumn Skips to the next column.
*NewPage Skips to the next page.
*PageToClient Converts page coordinates to mouse coordinates
70
*PrintDialog Displays a printer selection or page setup dialog.
*PrintDoc Prints the current document (being previewed) on the printer.
*PrintFile Prints the current document (being previewed) on the printer.
*Refresh See the Visual Basic documentation.
*SaveDoc Saves the current document to disk.
*ScrollIntoView Scrolls the control so the specified rectangle or point is visible.
*StartDoc Starts a new document.
*StartOverlay Reopens an existing preview page for additional output.
*StartTable Defers table rendering until call to EndTable.
*StartTag Starts the definition of a document tag (for later use with the
FindTag and RetrieveTag methods).
*TextBox Draws text within a rectangle.
VSPrinter Events
*AfterFooter Fired after printing the footer for each page to allow font
changes.
*AfterHeader Fired after printing the header for each page to allow font
changes.
*AfterTableCell Fired after a table cell is rendered, to allow custom painting.
*AfterUserPage Fired after switching preview pages in response to a user
request.
*AfterUserScroll Fired after scrolling in response to a user request.
*AfterUserZoom Fired after Zooming in or out in response to a user request.
*BeforeFooter Fired before printing the footer for each page to allow font
changes.
*BeforeHeader Fired before printing the header for each page to allow font
changes.
*BeforeTableCell Fired before a table cell is rendered, to allow custom
formatting.
*BeforeUserPage Fired before switching preview pages in response to a user
request.
*BeforeUserScroll Fired before scrolling in response to a user request.
*BeforeUserZoom Fired before Zooming in or out in response to a user request.
Click See the Visual Basic documentation.
DblClick See the Visual Basic documentation.
*EndDoc Fired after a document is successfully printed.
*EndPage Fired after each page is complete.
*Error Fired when an error is detected (a code is returned in the Error
71
property).
KeyDown See the Visual Basic documentation.
KeyPress See the Visual Basic documentation.
KeyUp See the Visual Basic documentation.
*LayoutThumbnails Fired when the thumbnail preview is about to change to allow
customization of the preview layout.
*LoadingDoc Fired while loading documents from disk, once after each page
is loaded.
MouseDown See the Visual Basic documentation.
*MouseLink Fired when the user clicks or moves the mouse over a
hyperlink (see AutoLinkNavigate property).
MouseMove See the Visual Basic documentation.
MouseUp See the Visual Basic documentation.
*NewColumn Fired after each column and page break.
*NewLine Fired after each line break.
*NewPage Fired after each page is created.
*ReadyStateChange Fired after the state of the control changes.
*ResetDC Fired after a page is ejected and before the next page is started.
*SavingDoc Fired while saving documents to disk, once after each page is
saved.
*StartDoc Fired after a new document is created.
VSPrinter Properties
AbortCaption Property
Returns or sets the caption for the default Abort dialog.
Syntax
[form!]VSPrinter.AbortCaption[ = value As String ]
Remarks
This property allows you to customize the appearance of the default Abort dialog. This is especially useful for
developers working with languages other than English.
For details on the default Abort dialog and a diagram displaying all localizable strings, see the AbortWindow property.
Note: Setting this property to an empty string restores it default value.
Data Type
String
Default Value
"Printing..."
See Also
72
VSPrinter Control (page 63)
AbortTextButton Property
Returns or sets the caption for the button in the default Abort dialog.
Syntax
[form!]VSPrinter.AbortTextButton[ = value As String ]
Remarks
Data Type
String
Default Value
"Cancel"
See Also
AbortTextDevice Property
Returns or sets the caption for the Device string in the default Abort dialog.
Syntax
[form!]VSPrinter.AbortTextDevice[ = value As String ]
Remarks
This string may use two placeholders specified as "%s". The first placeholder gets replaced with the device name, and
the second with the port. For example, the default value for this property is "on the %s on %s". The text displayed after
replacing the placeholders would be something like "on the HP LaserJet 4L on LPT1:".
Data Type
String
Default Value
"on the %s on %s"
See Also
AbortTextPage Property
Returns or sets the caption for the Page string in the default Abort dialog.
Syntax
73
[form!]VSPrinter.AbortTextPage[ = value As String ]
Remarks
This string may use a placeholder specified as "%d", which gets replaced with the number of the page being printed. For
example, the default value for this property is "Now printing Page %d of". The text displayed after replacing the
placeholders would be something like "Now printing Page 5 of".
Data Type
String
Default Value
"Now printing Page %d of"
See Also
AbortWindow Property
Returns or sets whether an Abort dialog will appear while the control is printing.
Syntax
[form!]VSPrinter.AbortWindow[ = {True | False} ]
Remarks
The automatic Abort dialog appears while output is being sent to the printer, and allows the user to abort the print job.
The dialog shows the name of the document being printed (from the DocName property), the output device (from the
Device property), port (from the Port property), and the current page. If the user presses the Cancel button, printing
stops and an Error event is fired.
You may modify the text in the automatic Abort dialog by setting the contents of the AbortCaption, DocName,
AbortTextPage, AbortTextDevice, and AbortTextButton properties. These properties are especially useful if you are
writing applications in a language other than English.
Set this property to False if you do not want the automatic Abort dialog to be displayed. This may be desirable for server
applications, for printing small jobs, or if you want to display a custom Abort dialog.
The following image shows the layout of the automatic Abort dialog and the default captions for each element on it.
Data Type
Boolean
See Also
74
AbortWindowPos Property
Returns or sets the placement for the default Abort dialog.
Syntax
[form!]VSPrinter.AbortWindowPos[ = AbortWindowPosSettings ]
Remarks
The settings for the AbortWindowPos property are described below:
Constant Value Description

awAppWindow 0 Causes the automatic Abort dialog to appear centered
over the VSPrinter control.
awScreenCenter 1 Causes the automatic Abort dialog to appear centered on
the screen.
For details on the automatic Abort dialog, see the AbortWindow property.
Data Type
AbortWindowPosSettings (Enumeration)
Default Value
awAppWindow (0)
See Also
AccessibleDescription Property (VSPrinter)

Gets or sets the description of the control used by accessibility client applications.
Syntax
[form!]VSPrinter.AccessibleDescription [ = value As String ]
Data Type
String
See Also
AccessibleName Property (VSPrinter)

Gets or sets the name of the control used by accessibility client applications.
Syntax
[form!]VSPrinter.AccessibleName [ = value As String ]
Data Type
String
See Also
75
AccessibleRole Property (VSPrinter)
Gets or sets the role of the control used by accessibility client applications.
Syntax
[form!]VSPrinter.AccessibleRole [ = value As Variant ]
Data Type
Variant
See Also
AccessibleValue Property (VSPrinter)

Gets or sets the value of the control used by accessibility client applications.
Syntax
[form!]VSPrinter.AccessibleValue [ = value As String ]
Data Type
String
See Also
Action Property (VSPrinter)

Executes an action such as 'StartDoc' or 'EndDoc'.
Syntax
[form!]VSPrinter.Action[ = ActionSettings ]
Remarks
This property was initially implemented in the VBX version of the VSPrinter control, which did not support custom
methods. It is still supported for compatibility with older projects, but there are equivalent methods for most of its
settings. When possible, the methods should be used instead of the Action property, because they provide more options
and result in clearer code.
The settings for the Action property are described below:

paNone 0 No effect.
paPrintFile 1 Prints the file specified by the FileName property.
paChoosePrintFile 2 Shows a printer setup dialog, then prints the file specified
by the FileName property.
paStartDoc 3 Equivalent to the StartDoc method.
paNewPage 4 Equivalent to the NewPage method.
paNewCol 5 Equivalent to the NewColumn method.
paEndDoc 6 Equivalent to the EndDoc method.
paAbortDoc 7 Equivalent to the KillDoc method.
76
paPrintPage 8 Prints the current preview page (set by the PreviewPage
property).
paChoosePrintPage 9 Shows a printer setup dialog, then prints the current
preview page.
paCopyPage 10 Copies the current preview page to the clipboard.
paPrintAll 11 Equivalent to the PrintDoc method.
paChoosePrintAll 12 Shows a printer setup dialog, then prints the document
being previewed.
paChoosePrinter 13 Equivalent to the PrintDialog method.
paPageSetup 14 Equivalent to the PrintDialog method.
Data Type
ActionSettings (Enumeration)
See Also
ArchiveInfo Property
Gets information from a ComponentOne archive file.
Syntax
[form!]VSPrinter.ArchiveInfo(arcFileName As String, InfoType As ArchiveInfoSettings, [ Index As Variant ])[ =
value As Variant ]
Remarks
This property allows you to get information from an archive file created with the Archive method.
The parameters for the ArchiveInfo property are described below:
Parameter Description
ArcFile$ Name of the archive file, including its path.
Info% Type of information that is to be retrieved from the archive. Valid settings are
listed in the following table.
Index% Optional zero-based index that specifies which file in the archive should be
processed.
Valid settings for the Info parameter are:

arcFileCount 0 Number of files in the archive.
arcFileName 1 Name of the file specified by the Index parameter.
arcFileSize 2 Original size of the file specified by the Index parameter.
arcFileCompSize 3 Compressed size of the file specified by the Index parameter.
arcFileDate 4 Date and time when the file specified by the Index parameter
was last modified.
77
For example, the following code lists the contents of an archive file.
Private Sub ArcList(fn$)
Dim i%, cnt%
With vp
cnt = .ArchiveInfo(f, arcFileCount)
Debug.Print "Archive "; fn; " ("; cnt; ") files"
Debug.Print "Name", "Size", "Compressed"
For i = 0 To cnt - 1
Debug.Print .ArchiveInfo(f, arcFileName, i),
Debug.Print .ArchiveInfo(f, arcFileSize, i),
Debug.Print .ArchiveInfo(f, arcFileCompressedSize, i)
Next
If Err > 0 Then MsgBox "An error occurred while processing " & fn
End With
End Sub
Note: For safety reasons, this property is disabled when the control is hosted on a Web page.
Data Type
Variant
See Also
AutoLinkNavigate Property
Gets or sets whether the control should automatically detect hyperlinks embedded in the preview document, fire the
MouseLink event, and change the cursor or perform the navigation automatically.
Syntax
Property AutoLinkNavigate As Boolean
Data Type
Boolean
Default Value
False
See Also
AutoRTF Property
Returns or sets whether RTF text should be automatically detected.
Syntax
[form!]VSPrinter.AutoRTF[ = {True | False} ]
Remarks
If the AutoRTF property is set to True (default), the VSPrinter control interprets any text enclosed in curly brackets as
RTF text and renders it accordingly.
AutoRTF is useful for creating tables that use multiple fonts within a single cell, or documents with complex headers
and footers.
You should be aware of the fact that rendering RTF text is an order of magnitude slower than rendering regular text, so
use this capability only when there is no simple alternative.
For details on rendering RTF text, see the TextRTF property.
78
Data Type
Boolean
See Also
BrushColor Property (VSPrinter)

Returns or sets the color of the brush used to fill graphical objects.
Syntax
[form!]VSPrinter.BrushColor[ = colorref& ]
Remarks
The BrushColor and BrushStyle properties define the brush used to fill all graphical objects drawn on the control.
Graphical objects are created using the Draw and Polygon properties as well as the DrawRectangle, DrawCircle, and
DrawEllipse methods. The brush is also used to shade text boxes drawn using the TextBox method when the Shade
parameter is set to True.
Data Type
Color
Default Value
vbBlack (0)
See Also
BrushStyle Property (VSPrinter)

Returns or sets the style of the brush used to fill graphical objects.
Syntax
[form!]VSPrinter.BrushStyle[ = BrushStyleSettings ]
Remarks
DrawEllipse methods. The brush is also used to shade text boxes drawn using the TextBox method when the Shade
The settings for the BrushStyle property are described below:

bsSolid 0 Solid brush.
bsTransparent 1 Transparent (invisible) brush. Use this setting to draw empty
objects.
bsHorzLine 2 Horizontal lines.
bsVertLine 3 Vertical lines.
bsDiagonalUp 4 Diagonal lines pointing up.
bsDiagonalDown 5 Diagonal lines pointing down.
79
bsCross 6 Crossed vertical and horizontal lines.
bsDiagonalCross 7 Crossed diagonal lines.
Data Type
BrushStyleSettings (Enumeration)
Default Value
bsSolid (0)
See Also
CalcParagraph Property
Calculates the size of a paragraph, in twips, and returns results in TextWid, TextHei, X1, Y1, X2, and Y1.
Syntax
[form!]VSPrinter.CalcParagraph = value As String
Remarks
You can use this property to determine whether a paragraph will fit on the current page or to position graphical elements
with respect to the paragraph.
To draw shaded paragraphs, see also the TextBox method.
For example, the following code renders several paragraphs of text and makes sure no paragraph is broken across page
breaks:
Private Sub Command1_Click()
Dim i%, s$
s = "This is a long paragraph. A very long one, really. "
s = s & s & s & s & s & s & s & s
With VSPrinter1
.StartDoc
.SpaceAfter = "0.5in"
For i = 0 To 100
.CalcParagraph = s
If .CurrentY + .TextHei > .PageHeight - .MarginBottom Then
.NewPage
End If
.Paragraph = s
Next
.EndDoc
End With
End Sub
Data Type
String
See Also
CalcPicture Property
Calculates the size of a picture, in twips, and returns results in X1, Y1, X2, and Y1.
Syntax
[form!]VSPrinter.CalcPicture = Picture
Remarks
80
You can use this property to determine whether a picture will fit on the current page, or to position graphical elements
with respect to the picture.
To render the picture, use the DrawPicture method or the Picture property.
Note: Picture objects have Width and Height properties that return their dimensions in HIMETRIC units (0.01mm).
You may prefer to use these properties instead of the CalcPicture property. If you do, remember that to convert from
HIMETRIC to twips, you need to multiply by (1440 / 2540).
Data Type
Picture
See Also
CalcTable Property
Calculates the size of a table, in twips, and returns results in TextWid, TextHei, X1, Y1, X2, and Y1.
Syntax
[form!]VSPrinter.CalcTable = value As String
Remarks
You can use this property to keep tables together on a page or to draw custom borders around tables.
The value string describes the table to be measured. It has the same format as the string assigned to the Table property.
Data Type
String
See Also
CalcText Property
Calculates the size of a string, in twips, and returns results in TextWid, TextHei, X1, Y1, X2, and Y1.
Syntax
[form!]VSPrinter.CalcText = value As String
Remarks
You can use this property to determine whether some text will fit on the current page. The text is measured from the
current cursor position (CurrentX, CurrentY) and the measurement takes into account wrapping, indenting, and line
spacing.
If you only need the width and height of the text, and not the rectangle on the page, you may use the TextWidth and
TextHeight properties instead.
To draw shaded paragraphs, see also the TextBox method.
Data Type
String
See Also
CalcTextRTF Property
Calculates the size of an RTF string, in twips, and returns results in TextWid, TextHei, X1, Y1, X2, and Y1.
81
Syntax
[form!]VSPrinter.CalcTextRTF = value As String
Remarks
This property is similar to CalcParagraph, except the text is formatted as RTF.
Data Type
String
See Also
Collate Property
Returns or sets whether multiple copies will be collated.
Syntax
[form!]VSPrinter.Collate[ = CollateSettings ]
Remarks
The settings for the Collate property are described below:

colFalse 0 Do not collate when printing multiple copies.
colTrue 1 Collate when printing multiple copies.
Using colTrue provides faster, more efficient output for collation, since the data is sent to the device driver just once, no
matter how many copies are required. The printer is told to simply print the page again.
The default value for this property depends on the printer driver and the current printer settings.
This property relies on the printer driver, and may or may not be available on a particular printer. After setting this
property, read it back to make sure the driver made the change, or check the Error property. If it is set to
vperDeviceIncapable (7), then the printer does not support the selected setting and you should take appropriate action.
Data Type
CollateSettings (Enumeration)
See Also
ColorMode Property
Returns or sets the color mode on color printers.
Syntax
[form!]VSPrinter.ColorMode[ = ColorModeSettings ]
Remarks
Valid settings for the ColorMode property are described below:

cmMonochrome 1 Print in black and white.
82
cmColor 2 Print in color.
Data Type
ColorModeSettings (Enumeration)
See Also
Columns Property
Returns or sets the number of columns on a page.
Syntax
[form!]VSPrinter.Columns[ = value As Integer ]
Remarks
The setting of the Columns property affects the flow of text as you send it to the printer. The VSPrinter control takes
care of word wrapping, column, and page feeds automatically for you.
You may adjust the spacing between columns using the ColumnSpacing property.
Data Type
Integer
Default Value
1
See Also
ColumnSpacing Property
Returns or sets the spacing between columns, in twips.
Syntax
[form!]VSPrinter.ColumnSpacing[ = value As Variant ]
Remarks
This property determines the spacing between columns when the Columns property is set to a value greater than one.
You may specify units with this value (inches, points, twips, cm, mm, or pixels). The default unit is twips. For details on
using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
Data Type
Variant
Default Value
180
See Also
83
Copies Property
Returns or sets the number of copies to print.
Syntax
[form!]VSPrinter.Copies[ = value As Integer ]
Remarks
Multiple copies of a document may or may not be collated, depending on the printer driver and on the setting of the
Collate property.
Multiple copies of the entire document or multiple copies of each page may be printed. For printers that don't support
collating, set Copies = 1, and then use a loop in code to print multiple copies of the entire document.
Data Type
Integer
Default Value
1
See Also
CurrentColumn Property
Returns the number of the column being printed.
Syntax
[form!]VSPrinter.CurrentColumn[ = value As Integer ]
Remarks
The column number ranges from one to Columns.
You may set the value of the CurrentColumn property, which will reset the cursor position to the top of the column
selected.
Data Type
Integer
See Also
CurrentLine Property
Returns the number of the line being printed.
Syntax
[form!]VSPrinter.CurrentLine[ = value As Integer ]
Data Type
Integer
See Also
84
CurrentPage Property
Returns the number of the page being printed.
Syntax
val% = [form!]VSPrinter.CurrentPage
Remarks
While the preview document is being created, this property holds the number of the page being created. Once the
document is ready, it holds the total page count.
To find out or set which page is being previewed, use the PreviewPage property instead.
Data Type
Integer
See Also
CurrentX Property
Returns or sets the horizontal position of the cursor, in twips from the left of the page.
Syntax
[form!]VSPrinter.CurrentX[ = value As Variant ]
Remarks
As text is printed, the CurrentX and CurrentY properties change to reflect the new cursor position. You may modify
these properties directly if you want to set the cursor at a specific position on the page.
These properties are similar to the standard CurrentX and CurrentY properties available in VB's PictureBox control
and Printer object.
Data Type
Variant
See Also
CurrentY Property
Returns or sets the vertical position of the cursor, in twips from the top of the page.
Syntax
[form!]VSPrinter.CurrentY[ = value As Variant ]
Remarks
As text is printed, the CurrentX and CurrentY properties change to reflect the new cursor position. You may modify
these properties directly if you want to set the cursor at a specific position on the page.
These properties are similar to the standard CurrentX and CurrentY properties available in VB's PictureBox control
and Printer object.
85
Data Type
Variant
See Also
DefaultDevice Property
Returns or sets whether device changes affect the Windows default settings.
Syntax
[form!]VSPrinter.DefaultDevice[ = {True | False} ]
Remarks
This property determines whether modifications to the Device property should affect only the current application
(DefaultDevice = False) or all Windows applications (DefaultDevice = True).
By default, this property is False, which means changes made to the device are local to your application.
Data Type
Boolean
Default Value
False
See Also
Device Property
Returns or sets the name of the current printer.
Syntax
[form!]VSPrinter.Device[ = value As String ]
Remarks
You can use this property to provide user feedback -- so users know which printer is currently selected -- or to select the
printer you want to use.
You cannot change this property while creating a document. If you want to select a device, do so before calling the
StartDoc method. You can only set this property to a valid device name. To obtain a list of valid device names, read the
Devices() property.
If the DefaultDevice property is set to True, the device selected will become the default device for all Windows
applications.
If you want to select the default Windows device, assign an empty string to the Device property, as shown below:
' select default Windows device
vsPrinter.Device = ""
Note: In addition to all the printers attached to the computer, you can also set the Device property to "Display". This
causes the control to create a printer-independent document. In this case, instead of relying on the printer driver to
obtain information such as resolution, orientation, and paper size, the control uses the screen resolution as a reference
and allows you to set the PaperWidth and PaperHeight properties to any values you want. For example:
vsPrinter.Device = "Display"
In this mode, you can still create, preview, export, and save documents. However, you cannot print them with the
PrintDoc method.
86
Data Type
String
See Also
Devices Property
Returns the names of the printing devices available (zero-based vector).
Syntax
val$ = [form!]VSPrinter.Devices(i As Integer)
Remarks
This property returns the names of all printing devices installed on the computer. The index for this property ranges from
zero to NDevices - 1.
To select a specific device, assign its name to the Device property.
For example, the following code lists all devices available and selects the first one:
' list available devices
Dim i%
For i = 0 To vp.NDevices - 1
Debug.Print vp.Devices(i)
Next
' select first device from the list

vp.Device = vp.Devices(0)
Data Type
String
See Also
DocName Property
Returns or sets the name of the current document (alias for FileName).
Syntax
[form!]VSPrinter.DocName[ = value As String ]
Remarks
The DocName property defines the string that appears in the default Abort dialog and on the Windows Print Manager
list.
The DocName property is an alias for the FileName property. If you change one of them, the other changes as well.
Data Type
String
See Also
DPI Property
Returns the resolution of the printing device, in dots per inch.
Syntax
87
val% = [form!]VSPrinter.DPI
Data Type
Integer
See Also
Draw Property (VSPrinter)

Draws an object within the rectangle defined by the X1, Y1, X2, and Y2 properties.
Syntax
[form!]VSPrinter.Draw = DrawSettings
Remarks
methods. It is still supported for compatibility with older projects, but there are equivalent methods for all of its settings.
When possible, the methods should be used instead of the Draw property, because they provide more options and result
in clearer code.
The settings for the Draw property are described below:

doNothing 0 No effect.
doLine 1 Draw a line between points (X1, Y1) and (X2, Y2), see also the
DrawLine method.
doRectangle 2 Draw a rectangle between points (X1, Y1) and (X2, Y2), see also
the DrawRectangle method.
doEllipse 3 Draw an ellipse enclosed in the rectangle defined by points (X1,
Y1) and (X2, Y2), see also the DrawCircle and DrawEllipse
methods.
All graphical objects are drawn with the current pen and filled with the current brush. Pen and brush attributes are
defined with the PenColor, PenStyle, PenWidth, BrushColor, and BrushStyle properties.
Data Type
DrawSettings (Enumeration)
See Also
Driver Property
Returns the name of the current printer driver.
Syntax
val$ = [form!]VSPrinter.Driver
Data Type
String
See Also
88
Duplex Property
Returns or sets duplex or double-sided printing.
Syntax
[form!]VSPrinter.Duplex[ = DuplexSettings ]
Remarks
This property determines whether pages should be printed on a single side or on both sides. Note that many printers do
not support this feature.
The settings for the Duplex property are described below:

dupSimplex 1 Single-sided printing.
dupVertical 2 Double-sided printing using a horizontal page turn.
dupHorizontal 3 Double-sided printing using a vertical page turn.
With horizontal duplex printing, the top of both sides of the page are at the same end of the sheet. With vertical duplex
printing, the bottom of one page is at the same end of the sheet as the top of the next page.
Data Type
DuplexSettings (Enumeration)
See Also
EmptyColor Property (VSPrinter)

Returns or sets the color of the area around the preview page.
Syntax
[form!]VSPrinter.EmptyColor[ = colorref& ]
Data Type
Color
Default Value
vbApplicationWorkspace
See Also
Error Property
Returns a code that describes an error condition.
Syntax
[form!]VSPrinter.Error[ = PrinterErrorSettings ]
89
Remarks
Valid settings are:
Constant Value
vperCantAccessPrinter 3
vperCantStartJob 4
vperUserAborted 5
vperAlreadyPrinting 6
vperDeviceIncapable 7
vperControlIncapable 8
vperCantInBrowser 9
For details and an example, see the Error event.

Data Type
PrinterErrorSettings (Enumeration)
See Also
ErrorDescription Property
Returns a message that describes an error condition (see also the Error property).
Syntax
[form!]VSPrinter.ErrorDescription[ = value As String ]
Remarks
For details and an example, see the Error event.
Data Type
String
See Also
ExportFile Property
Returns or sets the name of an export file of type defined by the ExportFormat property.
Syntax
[form!]VSPrinter.ExportFile[ = value As String ]
Remarks
The ExportFile property works in conjunction with the ExportFormat property to generate HTML or RTF output from
VSPrinter documents.
If the ExportFile property is set to a valid file name when a document is started with the StartDoc method, the
VSPrinter control will generate an export file by that name. The export file will contain HTML or RTF code, depending
on the setting of the ExportFormat property. The export file is closed when the EndDoc method is invoked.
90
The following code shows how you can use the same code to generate regular output, HTML, or RTF files:
Private Sub CreateDocument(sFile As String)
With vp
' set up to export RTF, HTML, or nothing

.ExportFile = ""
If Instr(sFile, ".rtf") Then
.ExportFile = sFile
.ExportFormat = vpxRTF
ElseIf Instr(sFile, ".htm") Then
.ExportFile = sFile
.ExportFormat = vpxDHTML
End If
' create document

.StartDoc
CreateDocumentBody
.EndDoc
' clear ExportFile to avoid overwriting it

.ExportFile = ""
End Sub
For a complete example, see the VSPrinter Tutorial - Calendar (page 35) topic.
Notes:
 Not all elements placed in a document can be translated into HTML or RTF. Graphical objects, text boxes, headers,
footers will not translate, nor will RTF text translate into HTML. Most other elements will, including regular text,
paragraphs, tables, and all character formatting.
 You cannot export a document after it has been created. The output must be generated while the document is being
created.
 Remember to reset the ExportFile property when you are done creating each document, to avoid accidentally
overwriting the file.
 For safety reasons, this property is disabled when the control is hosted on a Web page.
Data Type
String
See Also
ExportFormat Property
Returns or sets the format of the output file (HTML or RTF).
Syntax
[form!]VSPrinter.ExportFormat[ = ExportFormatSettings ]
Remarks
The settings for the ExportFormat property are described below:

vpxPlainHTML 0 Causes the control to generate only plain HTML. This option
results in compact HTML files, but some paragraph formatting
options are lost.
vpxDHTML 1 Causes the control to generate HTML with style tags. This
91
option results in larger HTML files, but all paragraph
formatting is included in the document.
vpxDHTMLExtended 2 Similar to vpxDHTML, but with support for absolutely-
positioned text as created by the TextBox method.
vpxPagedHTML 3 Similar to vpxPlainHTML, but creates several hyperlinked
HTML files.
vpxPagedDHTML 4 Similar to vpxDHTML, but creates several hyperlinked
DHTML files.
vpxRTF 5 Causes the control to generate RTF output.
vpxRTFExtended 6 Similar to vpxRTF, but with support for absolutely-positioned
text as created by the TextBox method.
The vpxPagedHTML and vpxPagedDHTML settings create several numbered files, one per page. The file names are
created by appending a number to the string in the ExportFile property. Each file contains links that allow the user to
navigate to the first, previous, next, or last page in the sequence. The links are created using an HTML template which
can be customized through the ExportNavBar property. Note that only hard page breaks (created with the NewPage
method) affect paged files.
For more details and an example, see the ExportFile property.
Data Type
ExportFormatSettings (Enumeration)
See Also
ExportNavBar Property
Returns or sets the HTML template to be used for the navigation bar in paged HTML export files.
Syntax
[form!]VSPrinter.ExportNavBar(Position As Integer)[ = value As String ]
Remarks
This property is used in conjunction with the ExportFile and ExportFormat properties.
When exporting paged HTML files (by setting the ExportFormat to vpxPagedHTML or vpxPagedDHTML), the control
creates several HTML files with links that allow the user to navigate to the first, previous, next, or last page in the
sequence. The ExportNavBar property allows you to modify the template used to create these links.
The ExportNavBar property is indexed. Element zero defines the template used to generate the navigation bar at the
top of each HTML page. Element one defines the template used to generate the navigation bar at the bottom of each
HTML page.
By default, the ExportNavBar property has the following values:
' no navigation bar on the top of each page
ExportNavBar(0) = ""
' simple navigation bar on the bottom of each page

ExportNavBar(1) = "" & _
"<p><font face=Arial size=2><b>" & _
"<a%s>[<<]</a> <a%s>[<]</a>" & _
"   Page %d of %d   " & _
"<a%s>[>]</a> <a%s>[>>]</a>" & _
"</b></font></p>" & _
""
92
Notice that the template consists mostly of plain HTML, but is contains six special elements which serve as placeholders
(they are shown above in bold). The first two elements "%s" are replaced with links to the first and last pages in the
sequence. The middle two "%d" are replaced with the current and last page numbers. The last two "%s" are replaced
with links to the next and last pages.
When creating your own templates, make sure you include all six placeholders and that they are in the proper order, or
the navigation bar may not be created properly.
The following code shows some HTML navigation bar templates:
Select Case iNavStyle
Case 1 ' Plain
.ExportNavBar(0) = _
"<hr><p><font face=Courier size=2><a%s>[first]</a> <a%s>[prev]</a>" & _
"   This is the top of page %d of %d   " & _
"<a%s>[next]</a> <a%s>[last]</a></font></p>"
.ExportNavBar(1) = .ExportNavBar(0)
Case 2: ' White on black
.ExportNavBar(0) = "<p style=""background-color:black"";>" & _
"<font face=Wingdings size=2 color=white><b> " & _
"<a%s style=""color:white"">çç</a> " & _
"<a%s style=""color:white"">ç</a> </b></font>" & _
"<font face=Tahoma size=2 color=white>|<b>   " & _
"Page %d of %d    </b>|</font>" & _
"<font face=Wingdings size=2 color=white><b> " & _
"<a%s style=""color:white"">è</a> " & _
"<a%s style=""color:white"">èè</a> </b></font>" & _
"</p>"
.ExportNavBar(1) = .ExportNavBar(0)
End Select
Data Type
String
See Also
ExportRaw Property
Injects raw text into the output file specified by the ExportFile property.
Syntax
[form!]VSPrinter.ExportRaw[ = value As String ]
Remarks
This property works in conjunction with the ExportFile and ExportFormat properties. It allows you to insert raw
output directly into the export file stream.
When generating HTML or RTF output, VSPrinter automatically handles text and tables, but pictures and textboxes are
not included in the output. The ExportRaw property allows you to insert these elements through code. In addition, you
may use the ExportRaw property to include elements that are not part of the original document into the output stream.
For example, you may want to include comments or scripting code.
For example, the following code creates a document with some text and a picture. The text is included in the HTML
output file automatically, but the picture is not.
The following code uses the ExportRaw property to insert an IMG tag into the HTML output stream:
With vp
' create HTML document

.ExportFile = "c:\MyDocs\Export.htm"
.ExportFormat = vpxPlainHTML
.StartDoc
93
' create some text (gets exported to HTML automatically)
.Paragraph = "This image appears also in the HTML file:"
' insert a picture (*not* exported to HTML automatically)

Set p = LoadPicture(App.Path & "\wall.gif")
.DrawPicture p, .MarginLeft, .CurrentY
' create HTML image tag manually

' the picture will get placed in the HTML file
.ExportRaw = "<IMG SRC=""wall.gif"">" ' close document
.EndDoc
.ExportFile = ""
End With
Data Type
String
See Also
FileName Property
Returns or sets the name of the current document.
Syntax
[form!]VSPrinter.FileName[ = value As String ]
Remarks
The FileName property defines the string that appears in the default Abort dialog and on the Windows Print Manager
list.
The DocName property is an alias for the FileName property. If you change either one, the other changes as well.
Data Type
String
See Also
FindTag Property
Finds a tag in the current document, returns the page and bounding rectangle (in X1,Y1,X2,Y2) for the match.
Syntax
iPage = [form!]VSPrinter.FindTag(Text As String, [ CaseSensitive As Variant ], [ StartPage As Variant ], [ EndPage
As Variant ], [ StartY As Variant ])
Remarks
Tags are pieces of hidden text in a document. They are created with the StartTag and EndTag methods, and may be
used for a number of things, including document annotation, pop-up notes, hyperlinks, and more. The FindTag property
allows you to search for tags based on their contents. To search for tags based on their position in the document, use the
RetrieveTag property instead. For details and examples about creating and using tags, see the Build a Table of Contents
(page 60) sample.
The parameters for the FindTag property are described below:
Text As String
Contains the text of the tag to be found. The control performs partial matches, so setting Text to "FIELD:" will retrieve
tags with text "FIELD:first" and "FIELD:last".
94
CaseSensitive As Variant (optional)
Specifies whether the control should perform a case-sensitive comparison when looking for matches. The default value
for this parameter is False.
StartPage As Variant (optional)
Specifies the page when the control should start looking for the tag. The default value for this parameter is 1 (the first
page).
EndPage As Variant (optional)
Specifies the page when the control should stop looking for the tag. The default value for this parameter is the value of
the PageCount property (the last page).
StartY As Variant (optional)
Specifies the position on the first page where the search should start. The default value for this parameter is 0 (the top of
the page).
You may enumerate tags with identical contents by setting the StartPage and StartY parameters. See the FindText
property for an example.
The property returns the number of the page where the tag was found, or -1 if it was not found. The rectangle enclosing
the tag is returned in the X1, Y1, X2, and Y2 properties.
Data Type
Long
See Also
FindText Property
Finds text in the current document, returns the page and bounding rectangle (in X1,Y1,X2,Y2) for the match.
Syntax
iPage = [form!]VSPrinter.FindText(Text As String, [ CaseSensitive As Variant ], [ StartPage As Variant ], [ EndPage
As Variant ], [ StartY As Variant ])
Remarks
The FindText property allows you to look for text within the current document. To retrieve text based on its position in
the document, use the RetrieveText property instead.
The parameters for the FindText property are described below:
Text As String
Contains the text to be found.
CaseSensitive As Variant (optional)
Specifies whether the control should perform a case-sensitive comparison when looking for matches. The default value
for this parameter is False.
StartPage As Variant (optional)
Specifies the page when the control should start looking for the text. The default value for this parameter is 1 (the first
page).
EndPage As Variant (optional)
Specifies the page when the control should stop looking for the text. The default value for this parameter is the value of
the PageCount property (the last page).
95
StartY As Variant (optional)
Specifies the position on the first page where the search should start. The default value for this parameter is 0 (the top of
the page).
The property returns the number of the page where the text was found, or -1 if it was not found. The rectangle enclosing
the text is returned in the X1, Y1, X2, and Y2 properties.
You may enumerate different occurrences of the same text within a document by setting the StartPage and StartY
parameters. For example, the following code lists all occurrences of the string "RTF" within a document:
Dim pg& ' starting page for the search
Dim sy! ' starting top for the search
pg = 1
Do
' search for text

pg = vp.FindText("RTF", False, pg, vp.PageCount, sy)
' if not found, bail out

If pg <= 0 Then Exit Do
' found one

Debug.Print "found '"; Text1.Text; "' on page "; pg; " at "; vp.X1; vp.Y1
' increment searching point to find next

sy = vp.Y2
Loop
Note: The FindText property searches the document line by line. If a line contains the text being searched for, the
rectangle returned in the X1, Y1, X2, and Y2 properties will enclose the whole line. If the text being searched for spans
multiple lines, the control will not find it.
Data Type
Long
See Also
Footer Property
Returns or sets the footer text.
Syntax
[form!]VSPrinter.Footer[ = value As String ]
Remarks
The Footer is composed of three sections, separated by pipe characters ("|"). The first section is left-justified, the second
is centered, and the third is right-justified.
You may include a page number field by embedding a "%d" code in the string. If you want to show a percent sign in the
footer, double it in the Footer property (for example, "50%% Progress Report, Page %d").
For example, the following footer would print the file name and page number on the left and right corners of every page:
vp.Footer = vp.DocName & "||Page %d"
You may create multi-line footers by embedding line-feed characters within the Footer string. For example:
vp.Footer = "Document:" & vbLf & vp.DocName & "||Page" & vbLf & "%d"
The color and font used to print the footer are defined by the HdrFont and HdrColor properties. The position of the
footer is defined by the MarginFooter property.
If you want to use different fonts or colors for headers and footers, trap the BeforeFooter and AfterFooter events to
make that changes you want.
96
Data Type
String
See Also
hDC Property
Returns the control's current hDC.
Syntax
val& = [form!]VSPrinter.hDC
Remarks
This property is useful if you wish to call Windows API functions to draw directly into the VSPrinter's device context.
The value of the hDC property corresponds to a printer or enhanced metafile device context, depending on whether the
control is drawing to the printer or to the screen (in print preview mode).
If there's no open document, the hDC property returns zero.
Note: You should only use this property if you are familiar with the Windows GDI calls. In particular, you should
restore the hDC to its original state when you are done using it. If you run into problems using this property, our
technical support staff probably won't be able to help you.
Data Type
Long
See Also
HdrColor Property
Returns or sets the color used to print headers and footers.
Syntax
[form!]VSPrinter.HdrColor[ = colorref& ]
Remarks
By default, the same color is used for headers and footers.
If you want to use distinct colors for the headers and footers of a document, you should trap the BeforeHeader,
BeforeFooter, AfterHeader, and AfterFooter events to set and restore the HdrColor property accordingly.
The font used to draw the headers and footers is set with the HdrColor property.
To set the color used to draw regular text, use the TextColor property.
Data Type
Color
See Also
HdrFont Property
Returns or sets the font used to draw headers and footers.
Syntax
97
[form!]VSPrinter.HdrFont[ = Font ]
Remarks
By default, the same font is used for headers and footers.
If you want to use distinct fonts for the headers and footers of a document, you should trap the BeforeHeader,
BeforeFooter, AfterHeader, and AfterFooter events to set and restore the HdrFont property accordingly.
The color of the headers and footers is set with the HdrColor property.
Data Type
Font
See Also
Header Property
Returns or sets the header text.
Syntax
[form!]VSPrinter.Header[ = value As String ]
Remarks
The Header is composed of three sections, separated by pipe characters ("|"). The first section is left-justified, the
second is centered, and the third is right-justified.
You may include a page number field by embedding a "%d" code in the string. If you want to show a percent sign in the
footer, double it in the Footer property (for example, "50%% Progress Report, Page %d").
For example, the following header would print the file name and page number on the left and right corners of every page:
vp.Header = vp.DocName & "||Page %d"
You may create multi-line footers by embedding line-feed characters within the header string. For example:
vp.Header = "Document:" & vbLf & vp.DocName & "||Page" & vbLf & "%d"
The color and font used to print the header are defined by the HdrFont and HdrColor properties. The position of the
footer is defined by the MarginHeader property.
If you want to use different fonts or colors for headers and footers, trap the BeforeHeader and AfterHeader events to
make that changes you want.
Data Type
String
See Also
IndentFirst Property
Returns or sets an additional left indent for the first line of each paragraphs, in twips.
Syntax
[form!]VSPrinter.IndentFirst[ = value As Variant ]
Remarks
This property is mainly useful for creating hanging indents for bullet or numbered lists. To create hanging indents, set
IndentFirst to a negative value (-x) and IndentTab to the same value, but positive (x). For example:
' set 1/4 inch hanging indent
98
.IndentLeft = "0.25in"
.IndentTab = .IndentLeft
.IndentFirst = -.IndentLeft
' create a list with 10 items

For i = 1 To 10
.Paragraph = i & "." & vbTab & "This is item " & i & ". " & s
Next
For a diagram showing the effect of the Indent properties, see the IndentLeft property.
Data Type
Variant
See Also
IndentLeft Property
Returns or sets the left indent for paragraphs, in twips.
Syntax
[form!]VSPrinter.IndentLeft[ = value As Variant ]
Remarks
This property sets the distance between the text and the left margin of the page (MarginLeft).
The following diagram shows the effect of the IndentLeft, IndentFirst, and IndentRight properties:
When creating different paragraph styles, use the IndentLeft and IndentRight properties rather than the MarginLeft
and MarginRight properties. The former affect only the paragraph text, while the latter also affect the positioning of
headers, footers, and page borders.
Data Type
Variant
See Also
99
IndentRight Property
Returns or sets the right indent for paragraphs, in twips.
Syntax
[form!]VSPrinter.IndentRight[ = value As Variant ]
Remarks
This property sets the distance between the text and the right margin of the page (MarginRight).
For a diagram showing the effect of the Indent* properties, see the description of the IndentLeft property.
When creating different paragraph styles, use the IndentLeft and IndentRight properties rather than the MarginLeft
and MarginRight properties. The former affect only the paragraph text, while the latter also affect the positioning of
headers, footers, and page borders.
Data Type
Variant
See Also
IndentTab Property
Returns or sets the left indent for the first line of a paragraph, in twips.
Syntax
[form!]VSPrinter.IndentTab[ = value As Variant ]
Remarks
When VSPrinter encounters a tab character in the input text, it moves the cursor to the next multiple of the IndentTab
value. If the next position is beyond the end of the current line, then the output advances to the next line.
This property is mainly useful for creating hanging indents in bullet or numbered lists. For detail and an example, see the
IndentFirst property.
The IndentTab property only affects left-aligned and justified text. It is ignored while printing centered and right-
aligned text. To create tables with varying column widths and alignments, see the AddTable method.
Data Type
Variant
See Also
LargeChangeHorz Property (VSPrinter)

Returns or sets the amount of change to the ScrollLeft property when the user clicks the scroll bar area.
Syntax
[form!]VSPrinter.LargeChangeHorz[ = value As Double ]
Data Type
100
Double
Default Value
300
See Also
LargeChangeVert Property (VSPrinter)

Returns or sets the amount of change to the ScrollTop property when the user clicks the scroll bar area.
Syntax
[form!]VSPrinter.LargeChangeVert[ = value As Double ]
Data Type
Double
Default Value
300
See Also
LineSpacing Property (VSPrinter)

Returns or sets the line spacing, as a percentage (for example, 100 is single spacing, 200 is double spacing).
Syntax
[form!]VSPrinter.LineSpacing[ = value As Variant ]
Remarks
If no units are supplied, this value is interpreted as a percentage of the single line spacing for the current font (font height
plus external leading.) In this case, the spacing changes automatically when you change the font size.
The following table shows some common settings for the LineSpacing property:
Setting Effect
100 Single-line spacing (default value).
150 1.5 line spacing.
200 Double line spacing.
50 Half line spacing
You may also specify the line spacing as an absolute value (for example, "12pt"). In this case, the line spacing becomes
independent of the font size.
For details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
Data Type
Variant
Default Value
100
See Also
101
LoadPicture Property
Returns a picture loaded from a file or URL.
Syntax
Picture = [form!]VSPrinter.LoadPicture(FileName As String)
Remarks
This property is read-only.
See Also
MarginBottom Property
Returns or sets the bottom margin, in twips.
Syntax
[form!]VSPrinter.MarginBottom[ = value As Variant ]
Remarks
The MarginBottom property measures the space between the text and the bottom of the page. If the MarginFooter
property is set to zero, MarginBottom also determines the position of the page footers.
When text wraps past the bottom margin, or when table rows exceed it, the VSPrinter control automatically causes a
column or page break. To disable page breaks -- to write on the margins, for example -- set MarginBottom to a
negative value (remember to restore it later).
For a diagram showing the effect of the Margin properties, see the MarginLeft property.
Data Type
Variant
Default Value
1440
See Also
MarginFooter Property
Returns or sets the footer margin, in twips.
Syntax
[form!]VSPrinter.MarginFooter[ = value As Variant ]
Remarks
The MarginFooter property measures the space between the top of the footer text and the bottom of the page. If the
MarginFooter property is set to zero, the top of the footer is placed 200 twips below the bottom margin.
102
Data Type
Variant
Default Value
0
See Also
MarginHeader Property
Returns or sets the header margin, in twips.
Syntax
[form!]VSPrinter.MarginHeader[ = value As Variant ]
Remarks
The MarginHeader property measures the space between the top of the page and the top of the header text. If the
MarginHeader property is set to zero, the header is bottom-aligned within a rectangle with its bottom located 200 twips
above the top margin.
Data Type
Variant
Default Value
0
See Also
MarginLeft Property
Returns or sets the left margin, in twips.
Syntax
[form!]VSPrinter.MarginLeft[ = value As Variant ]
Remarks
The MarginLeft property measures the space between the text and the left edge of the page. This measurement is also
affected by the setting of the IndentLeft property.
The following diagram shows the effect of the Margin properties:
103
Data Type
Variant
Default Value
1440
See Also
MarginRight Property
Returns or sets the right margin, in twips.
Syntax
[form!]VSPrinter.MarginRight[ = value As Variant ]
Remarks
The MarginRight property measures the space between the text and the right edge of the page. This measurement is
also affected by the setting of the IndentRight property.
Data Type
Variant
Default Value
1440
See Also
104
MarginTop Property
Returns or sets the top margin, in twips.
Syntax
[form!]VSPrinter.MarginTop[ = value As Variant ]
Remarks
The MarginTop property measures the space between the text and the top of the page.
Data Type
Variant
Default Value
1440
See Also
Measure Property
Returns width and height of a string, in twips, in TextWid and TextHei properties.
Syntax
[form!]VSPrinter.Measure = value As String
Remarks
This property is obsolete and is provided for compatibility with old applications. New applications should use the
TextWidth and TextHeight properties.
To measure text using the Measure property, assign it the text you want to measure, then read the text width and height,
in twips, from the TextWid and TextHei properties.
Data Type
String
See Also
Measuring Property
Returns True if the control is measuring text, False if it is rendering.
Syntax
val% = [form!]VSPrinter.Measuring
Remarks
Some of the VSPrinter events are fired while rendering and while measuring text to make sure it will fit on the page.
For example, the BeforeTableCell event is fired when rendering tables and when calculating row heights.
This property allows you to determine whether VSPrinter is measuring or rendering the text when these events are fired.
105
Data Type
Boolean
See Also
NavBar Property
Returns or sets whether to display the document navigation bar.
Syntax
[form!]VSPrinter.NavBar[ = NavBarSettings ]
Remarks
The NavBar property controls the position and configuration of the optional built-in preview navigation bar. Valid
settings are:

vpnbNone 0 Do not display the navigation bar.
vpnbTop 1 Display a simple navigation bar at the top of the control.
vpnbBottom 2 Display a simple navigation bar at the bottom of the control.
vpnbTopPrint 3 Display a complete navigation bar at the top of the control
(including a Print button). This is the default setting.
vpnbBottomPrint 4 Display a complete navigation bar at the bottom of the control
(including a Print button).
The following diagram shows the elements that make up a typical navigation bar:
The buttons on the left of the navigation bar are used to switch pages. Keeping them pressed for about a second causes
the pages to start switching continuously, so it is easy to move from page 1 to page 20, for example. The digits between
the buttons show the current page and the total page count.
The drop-down list on the right of the navigation bar is used for zooming. Clicking the buttons toggles the zoom factor
between 100% and full-page preview. To select other zoom factors, the user may click on the drop-down button and
select the zoom factor from the menu.
106
Although the picture does not show it, the navigation bar may include a Print button. Clicking the Print button shows a
print dialog and allows the user to print the document.
The navigation bar may also include a custom caption specified by the NavBarText property. The color of the bar can
be changed using the NavBarColor property.
The navigation bar is very useful because it allows users to instantly see where they are in a document, to go to a specific
page, or to set the zoom factor they prefer. Although these tasks can also be accomplished using the mouse or the
keyboard, the navigation bar is visual and thus easier to use. If you choose to implement your own user interface for
preview navigation, simply set the NavBar property to vpnbNone.
Data Type
NavBarSettings (Enumeration)
Default Value
3 (vpnbTopPrint)
See Also
NavBarColor Property
Returns or sets the color of the document navigation bar.
Syntax
[form!]VSPrinter.NavBarColor[ = colorref& ]
Data Type
Color
Default Value
&H8000000F& (Button Face)
See Also
NavBarMenuText Property
Returns or sets the text that appears on the NavBar Zoom menu.
Syntax
[form!]VSPrinter.NavBarMenuText[ = value As String ]
Remarks
This property allows you to customize the text that appears on the navigation bar's zoom menu. This is especially useful
for developers working with languages other than English.
The navigation bar's zoom menu has ten items, including a separator. The four items before the separator are used to
select the zoom mode (whole page, page width, two pages, or thumbnails). The five items after the separator are used to
select predefined zoom levels.
The NavBarMenuText property contains the text for the first four items, separated by pipe characters ("|"). The
remaining items cannot be customized.
For example, an application designed to run in Portuguese might customize the menu text using this code:
vp.NavBarMenuText = "&Página Inteira|&Largura de Página|" & _
"&Duas Páginas|&Multi-Página"
107
To fully localize the VSPrinter control, you should also set the following properties: AbortCaption, AbortTextButton,
AbortTextDevice, and AbortTextPage.
Data Type
String
Default Value
"Whole &Page|Page &Width|&Two Pages|Thumb&nail"
See Also
NavBarText Property
Returns or sets the text displayed on the document navigation bar.
Syntax
[form!]VSPrinter.NavBarText[ = value As String ]
Remarks
You can use the space on the right of the navigation bar buttons to display short messages to the user. A typical use for
these messages would be to display messages related to the state of the control.
For example, the following code uses the NavBarText property to display its progress while generating a document:
Private Sub CreateDoc()
vp.NavBarText = "Creating document"
vp.StartDoc
CreateDocBody
vp.EndDoc
vp.NavBarText = ""
End Sub
Private Sub vp_NewPage()
vp.NavBarText = "Creating page " & vp.PageCount & "..."
End Sub
Note: The message is displayed using the same font used to display the current page and page count on the navigation
bar. This font is fixed and cannot be changed.
Data Type
String
See Also
Navigation Property
Returns or sets the type of document navigation interface provided (mouse, mouse wheel, or keyboard).
Syntax
[form!]VSPrinter.Navigation[ = NavigationSettings ]
Remarks
The settings for the Navigation property are described below:

vpnvNone 0 No built-in navigation.
108
vpnvMouse 1 The control will respond to the following mouse
commands: (1) click-drag to scroll the document, (2)
shift-click with the left and right buttons to switch
pages, and (3) control-click with the left and right
buttons to zoom in and out.
vpnvWheel 2 The control will respond to the following mouse wheel
commands: (1) roll to scroll the document, (2) shift-roll
to switch pages, and (3) control-roll to zoom in and
out.
vpnvMouseWheel 3 Combination of vpnvMouse and vpnvWheel. The
control will respond to mouse and wheel commands.
vpnvKeyboard 4 The control will respond to the following keyboard
commands: (1) arrow keys scroll the document, (2)
page up/page down to switch pages, and (3) control-
arrow keys to zoom in and out.
vpnvMouseKeyboard 5 Combination of vpnvMouse and vpnvKeyboard.
vpnvWheelKeyboard 6 Combination of vpnvWheel and vpnvKeyboard.
vpnvAll 7 Combination of vpnvMouse, vpnvWheel, and
vpnvKeyboard.
Data Type
NavigationSettings (Enumeration)
See Also
NDevices Property
Returns the number of printing devices available.
Syntax
val% = [form!]VSPrinter.NDevices
Remarks
Use the Devices property to retrieve the name of a specific device.
Data Type
Integer
See Also
NPorts Property
Returns the number of ports to which the current printer is connected.
Syntax
val% = [form!]VSPrinter.NPorts
Remarks
This property will return one unless you have devices with the same name connected to different ports.
109
For example, if the current Device is an "HP LaserJet 4L" connected to "LPT1:" and there's another "HP LaserJet 4L"
connected to "LPT2:", then NPorts will return 2, Ports(0) will return "LPT1:", and Ports(1) will return "LPT2:".
Data Type
Integer
See Also
Orientation Property
Returns or sets the paper orientation.
Syntax
[form!]VSPrinter.Orientation[ = OrientationSettings ]
Remarks
The settings for the Orientation property are described below:

orPortrait 0 The page is rendered in Portrait mode (tall).
orLandscape 1 The page is rendered in Landscape mode (wide).
You can change the Orientation property while creating a document, so that some pages are rendered in landscape
mode and others in portrait. To do this, you must switch the orientation before the page starts. For example, the
following code creates a document with some text in portrait mode, then a chart in landscape mode, followed by more
text in portrait mode:
Dim i%
With vp
' start in portrait mode

.StartDoc
' print some text in portrait mode

For i = 1 To 10
.Paragraph = i & ": This is portrait mode."
Next
' print graphics in landscape mode

.Orientation = orLandscape
.NewPage
.Paragraph = "This is landscape mode."
.BrushStyle = bsTransparent
.DrawCircle .PageWidth / 2, .PageHeight / 2, .PageHeight / 4
' print more text in portrait mode

.NewPage
For i = 1 To 10
.Paragraph = i & ": This is portrait mode."
110
Next
.EndDoc
End With
End Sub
The code above produces the following result:
Data Type
OrientationSettings (Enumeration)
See Also
OutputFileName Property
Returns or sets the name of a printer output file (if empty, output is sent to the printer).
Syntax
[form!]VSPrinter.OutputFileName[ = value As String ]
Remarks
This property gives you the option to direct the output of the VSPrinter control to a printer file. This may be useful to
some specialized applications that create faxes, mailing lists, and the like.
Set the OutputFileName property to an empty string ("") to send the output to the printer.
Notes: If the Preview property is set to True, the document is created in preview mode and this property has no effect.
For safety reasons, this property is disabled when the control is hosted on a Web page.
Data Type
String
See Also
111
PageBorder Property
Returns or sets the type of border to draw around each page.
Syntax
[form!]VSPrinter.PageBorder[ = PageBorderSettings ]
Remarks
The border is drawn using the current pen. Its color, style, and thickness are determined by the PenColor, PenStyle, and
PenWidth properties. The distance between the border and the edges of the page is determined by the MarginLeft,
MarginTop, MarginRight, and MarginBottom properties.
The following image shows valid settings for the PageBorder property and their effect:
Note: For single-column documents, settings pbColumns, pbColTopBottom, pbAll, pbColTop, and pbColBottom have the
same effect as pbNone, pbBottom, pbTop, pbTopBottom, and pbBox.
Data Type
PageBorderSettings (Enumeration)
Default Value
pbNone (0)
See Also
112
PageCount Property
Returns the number of pages in the current document.
Syntax
val% = [form!]VSPrinter.PageCount
Remarks
While the preview document is being created, this property holds the number of the page being created. Once the
document is ready, it holds the total page count.
This property is an alias for the CurrentPage property.
Data Type
Integer
See Also
PageHeight Property (VSPrinter)

Returns the page height, in twips.
Syntax
val# = [form!]VSPrinter.PageHeight
Remarks
The PageHeight and PageWidth properties are useful to position elements on a page. They reflect the current device,
paper, and orientation selections, and do not subtract the document margins.
The values returned by the PageHeight and PageWidth properties depend on the setting of the PhysicalPage property.
These properties are read-only. To use custom paper sizes, set the PaperSize property to pprUser (256) and use the
PaperHeight and PaperWidth properties to define the paper size.
Data Type
Double
See Also
PageWidth Property (VSPrinter)

Returns the page width, in twips.
Syntax
val# = [form!]VSPrinter.PageWidth
Remarks
The PageHeight and PageWidth properties are useful to position elements on a page. They reflect the current device,
paper, and orientation selections, and do not subtract the document margins.
The values returned by the PageHeight and PageWidth properties depend on the setting of the PhysicalPage property.
These properties are read-only. To use custom paper sizes, set the PaperSize property to pprUser (256) and use the
PaperHeight and PaperWidth properties to define the paper size.
113
Data Type
Double
See Also
PalettePicture Property
Returns or sets a picture with a palette that is used to render the document.
Syntax
[form!]VSPrinter.PalettePicture[ = Picture ]
Remarks
If you want to select a palette for the VSPrinter control, assign the picture that contains it to this property.
Palletized devices can only show 256 colors at a time. If you have many pictures in a document, setting this property
forces all pictures in the document to share the same (specified) palette, mapping colors as needed. This property is only
relevant when the display is in 256 color mode.
If you don't set this property and render multiple pictures with different palettes to the same page, the quality of the
images on a 256 color screen will probably be poor.
Data Type
Picture
See Also
PaperBin Property
Returns or sets the paper bin to use.
Syntax
[form!]VSPrinter.PaperBin[ = PaperBinSettings ]
Remarks
The settings for the PaperBin property are described below:

binUpper 1 Use paper from the upper bin.
binLower 2 Use paper from the lower bin.
binMiddle 3 Use paper from the middle bin.
binManual 4 Wait for manual insertion of each sheet of paper.
binEnvelope 5 Use envelopes from the envelope feeder.
binEnvManual 6 Use envelopes from feeder, but wait for manual insertion.
binAuto 7 Use paper from the current default bin.
binTractor 8 Use paper fed from the tractor feeder.
binSmallFmt 9 Use paper from the small paper bin.
binLargeFmt 10 Use paper from the large paper bin.
114
binLargeCapacity 11 Use paper from the large capacity feeder.
binCassette 14 Use paper from the attached cassette cartridge.
binFormSource 15 Use paper from form source.
binUser 256 Custom bin.
You can determine which bins are available on the current device by reading the PaperBins property. For example, the
following code shows which bins are available on the current device:
Debug.Print "Bins available on the "; vp.Device; ":"
For i = 1 To 15
If vp.PaperBins(i) Then Debug.Print " bin "; i; " available"
Next
Data Type
PaperBinSettings (Enumeration)
See Also
PaperBins Property
Returns whether a given paper bin is available on the current printer.
Syntax
val% = [form!]VSPrinter.PaperBins(PaperBin As PaperBinSettings)
Remarks
Use this property to make sure a specific paper bin is available before selecting it with the PaperBin property, or to build
a list of available bins for selection by the user.
Data Type
Boolean
See Also
PaperHeight Property
Returns or sets the height of a custom paper size, in twips.
Syntax
[form!]VSPrinter.PaperHeight[ = value As Single ]
Remarks
Sets or returns the physical size of the paper set up for the printing device; not available at design time.
The PaperHeight and PaperWidth properties can only be set on printers that allow custom paper sizes. Most printers
no not, and you have to select the paper size using the PaperSize property from a list of available standard sizes. If you
set these properties and the printer driver doesn't allow custom paper sizes, no error occurs and the size of the paper
remains as it was.
115
If you set PaperHeight and PaperWidth properties for a printer driver that allows only certain values to be specified,
no error occurs and the property is set to whatever the driver allows. For example, you could set PaperHeight to 150
and the driver would set it to 144.
Setting the PaperHeight or PaperWidth properties automatically sets the PaperSize property to pprUser (256).
Data Type
Single
See Also
PaperSize Property
Returns or sets a standard paper size.
Syntax
[form!]VSPrinter.PaperSize[ = PaperSizeSettings ]
Remarks
The settings for the PaperSize property are described below:

pprLetter 1 Letter, 8½ x 11 in.
pprLetterSmall 2 Letter Small, 8½ x 11 in.
pprTabloid 3 Tabloid, 11 x 17 in.
pprLedger 4 Ledger, 17 x 11 in.
pprLegal 5 Legal, 8 ½ x 14 in.
pprStatement 6 Statement, 5 1/2 x 8 1/2 in.
pprExecutive 7 Executive, 7 1/2 x 10 1/2 in.
pprA3 8 A3, 297 x 420 mm
pprA4 9 A4, 210 x 297 mm
pprA4Small 10 A4 Small, 210 x 297 mm
pprA5 11 A5, 148 x 210 mm
pprB4 12 B4, 250 x 354 mm
pprB5 13 B5, 182 x 257 mm
pprFolio 14 Folio, 8 ½ x 13 in.
pprQuarto 15 Quarto, 215 x 275 mm
ppr10x14 16 10 x 14 in.
ppr11x17 17 11 x 17 in.
pprNote 18 Note, 8 ½ x 11 in.
pprEnv9 19 Envelope #9, 3 7/8 x 8 7/8 in.
pprEnv10 20 Envelope #10, 4 1/8 x 9 ½ in.
pprEnv11 21 Envelope #11, 4 ½ x 10 3/8 in.
116
pprEnv12 22 Envelope #12, 4 ½ x 11 in.
pprEnv14 23 Envelope #14, 5 x 11 ½ in.
pprCSheet 24 C size sheet
pprDSheet 25 D size sheet
pprESheet 26 E size sheet
pprEnvDL 27 Envelope DL, 110 x 220 mm
pprEnvC5 28 Envelope C5, 162 x 229 mm
pprEnvB4 33 Envelope B4, 250 x 353 mm
pprEnvItaly 36 Envelope, 110 x 230 mm
pprEnvMonarch 37 Envelope Monarch, 3 7/8 x 7 ½ in.
pprEnvPersonal 38 Envelope, 3 5/8 x 6 ½ in.
pprFanfoldUS 39 U.S. Standard Fanfold, 14 7/8 x 11 in.
pprFanfoldStdGerman 40 German Standard Fanfold, 8 ½ x 12 in.
pprFanfoldLglGerman 41 German Legal Fanfold, 8 1/2 x 13 in.
ppr* 42 - 68 Less-common international sizes.
pprUser 256 Custom-size. Set dimensions with the
PaperWidth and PaperHeight properties.
Setting the PaperWidth or PaperHeight properties automatically sets PaperSize to pprUser (256).
Not all of the paper size options are available on every printer. Before selecting a paper size, you should check whether it
is available. You can do this by reading the PaperSizes array property. For example, the following code shows which
paper sizes are available on the current device:
Debug.Print "Paper sizes available on the "; vp.Device; ":"
For i = 1 To 256
If vp.PaperSizes(i) Then Debug.Print " paper size "; i; " is available"
Next
Data Type
PaperSizeSettings (Enumeration)
See Also
PaperSizes Property
Returns whether a given page size is available on the current printer.
Syntax
117
val% = [form!]VSPrinter.PaperSizes(PaperSize As PaperSizeSettings)
Remarks
Use this property to make sure a specific paper bin is available before selecting it with the PaperSize property, or to
build a list of available paper sizes for selection by the user.
Data Type
Boolean
See Also
PaperWidth Property
Returns or sets the width of a custom paper size, in twips.
Syntax
[form!]VSPrinter.PaperWidth[ = value As Single ]
Remarks
Sets or returns the physical size of the paper set up for the printing device; not available at design time.
The PaperHeight and PaperWidth properties can only be set on printers that allow custom paper sizes. Most printers
no not, and you have to select the paper size using the PaperSize property from a list of available standard sizes. If you
set these properties and the printer driver doesn't allow custom paper sizes, no error occurs and the size of the paper
remains as it was.
If you set PaperHeight and PaperWidth properties for a printer driver that allows only certain values to be specified,
no error occurs and the property is set to whatever the driver allows. For example, you could set PaperHeight to 150 and
the driver would set it to 144.
Setting the PaperHeight or PaperWidth properties automatically sets the PaperSize property to pprUser (256).
Data Type
Single
See Also
Paragraph Property
Renders a paragraph on the page at the current cursor position.
Syntax
[form!]VSPrinter.Paragraph = value As String
Remarks
This is the main property for placing text on a page. The VSPrinter control takes care of justification, word wrapping,
and page breaks.
Before rendering the text, the Paragraph property checks the current cursor position. If the cursor is free (that is, was
not set by the user or as a result of rendering text with the Text property), then its horizontal position is reset to the left
margin and its vertical position is incremented by the amount specified with the SpaceBefore property.
After rendering the text, the Paragraph property resets the horizontal cursor position to the left margin and increments
the vertical cursor position by the amount specified with the SpaceAfter property.
If the AutoRTF property is set to True and the text starts with a curly bracket ("{"), the text is rendered as RTF.
118
If you want to render text with mixed fonts and colors, use the Text property. If you want to render text within a
rectangle on the page, use the TextBox method.
Data Type
String
See Also
PenColor Property (VSPrinter)

Returns or sets the color of the pen used to outline graphical objects.
Syntax
[form!]VSPrinter.PenColor[ = colorref& ]
Remarks
The PenColor, PenStyle, and PenWidth properties define the pen used to outline all graphical objects drawn on the
control. The pen object is also used to borders around pages and tables depending on the settings of the PageBorder,
TableBorder properties.
DrawEllipse methods. The pen is also used to outline text boxes drawn using the TextBox method when the Shade
Data Type
Color
Default Value
vbBlack (0)
See Also
PenStyle Property (VSPrinter)

Returns or sets the style of the pen used to outline graphical objects.
Syntax
[form!]VSPrinter.PenStyle[ = PenStyleSettings ]
Remarks
control.
DrawEllipse methods.
The settings for the PenStyle property are described below:

psSolid 0 Solid pen (default value).
psDash 1 Dashed pen.
psDot 2 Dotted pen.
119
psDashDot 3 Dash-dot pen.
psDashDotDot 4 Dash-dot-dot pen.
psTransparent 5 Transparent pen (no lines).
psInsideSolid 6 Solid pen drawn inside shapes.
Note: Non-solid settings are only valid when the PenWidth property is set to zero (which translates into a pen one-pixel
wide). This is a Windows GDI limitation, not imposed by the VSPrinter control.
Data Type
PenStyleSettings (Enumeration)
Default Value
psSolid (0)
See Also
PenWidth Property (VSPrinter)

Returns or sets the width of the pen used to outline graphical objects.
Syntax
[form!]VSPrinter.PenWidth[ = value As Variant ]
Remarks
control. The pen object is also used to borders around pages and tables depending on the settings of the PageBorder,
TableBorder properties.
DrawEllipse methods. The pen is also used to outline text boxes drawn using the TextBox method when the Shade
If you set this property to zero, the resulting pen is one pixel wide. This is the only settings that allows the creation of
non-solid pens (also see PenStyle).
Data Type
Variant
Default Value
0
See Also
PhysicalPage Property
Returns or sets whether to use the physical size of the page or on its printable area.
Syntax
[form!]VSPrinter.PhysicalPage[ = {True | False} ]
120
Remarks
Most printers have a "logical" paper size that corresponds to the printer's printable area and a "physical" paper size that
corresponds to the actual page size. The physical paper size is always a little larger than the logical paper size.
If the PhysicalPage property is set to True, the control draws and prints to the physical page. This means any content
that is drawn too close to the edges of the page may not be printed. This setting should be used when accurate
positioning of elements with respect to the edges of the paper is desired. This is the case when printing checks, letterhead
paper, and other pre-printed forms.
If the PhysicalPage property is set to False, the control draws and prints to the logical page. This means the page
appears smaller than it actually is, and prevents output from being placed outside the printable area of the control.
The setting of this property is reflected in the values returned by the PageWidth and PageHeight properties. It can also
be seen on the preview page if the ShowGuides property is set to a non-zero value.
Note: The default value for this property is True, which gives more consistent output across different printers.
The following code shows the difference between the two settings:
With vp
.PaperSize = pprLetter
.FontSize = 44
.TextAlign = taCenterMiddle
.BrushStyle = bsTransparent
Dim s$
s = "PhysicalPage is " & .PhysicalPage & "."
s = s & vbLf & "PaperSize is pprLetter."
s = s & vbLf & "PageWidth is " & (.PageWidth / 1440) & " inches."
s = s & vbLf & "PageHeight is " & (.PageHeight / 1440) & " inches."
.StartDoc
.TextBox s, 0, 0, .PageWidth, .PageHeight
.DrawEllipse 0, 0, .PageWidth, .PageHeight
.EndDoc
End With
End Sub
The following image illustrates the output generated by the code when PhysicalPage is set to True and to False:
Data Type
121
Boolean
Default Value
True
See Also
Picture Property (VSPrinter)

Returns a picture of the current preview page or sets a picture to be displayed on the page.
Syntax
[form!]VSPrinter.Picture[ = Picture ]
Remarks
Getting the Picture property returns a picture of the current preview page. The picture returned is an enhanced metafile
that can be assigned to another control, saved with the VB SavePicture method, or copied to the clipboard to be pasted
into another application.
For example:
Clipboard.Clear
Clipboard.SetData vp.Picture
Setting the Picture property renders the picture on the current page. The position and size of the picture on the page are
determined by the X1, Y1, X2, and Y2 properties. If the rectangle defined by these properties is invalid (X2 <= X1 or Y2
<= Y1), the picture is not rendered. It is measured instead, and the X2 and Y2 properties are adjusted to reflect the
picture's natural size.
However, the DrawPicture method provides a better way to render pictures than using the Picture property.
DrawPicture has flexible parameters that allow you to scale, align, and clip pictures.
Note that the picture returned by the Picture property is an enhanced metafile. If you want to get a regular metafile
instead, use the following method:
' 1) copy the current page to the clipboard
vp.Action = paCopyPage
' 2) retrieve a regular metafile from the clipboard

metaPict.Picture = Clipboard.GetData(vbCFMetafile)
This method works because the paCopyPage action copies the current picture to the clipboard both as an enhanced and
regular metafiles.
Data Type
Picture
See Also
Polygon Property (VSPrinter)

Draws a polygon defined by a string of X,Y coordinates.
Syntax
[form!]VSPrinter.Polygon = value As String
Remarks
The string assigned to the Polygon property contains a sequence of coordinates, in twips, separated by spaces or
commas.
122
This is a convenient way to draw complex closed shapes using a single drawing command. For example, the following
code draws a rectangle extending from point (1000,1000) to point (2000,2000).
vp.StartDoc
vp.Polygon = "1000 1000, 2000 1000, 2000 2000, 1000 2000"
vp.EndDoc
The Polygon property draws closed shapes. To draw open shapes, use the Polyline property instead.
Data Type
String
See Also
Polyline Property (VSPrinter)

Draws a line defined by a string of X,Y coordinates.
Syntax
[form!]VSPrinter.Polyline = value As String
Remarks
The string assigned to the Polyline property contains a sequence of coordinates, in twips, separated by spaces or
commas.
This is a convenient way to draw complex open shapes using a single drawing command. For example, the following
code draws a sine curve.
Const pi = 3.1416
Dim a#, s$
vp.StartDoc
For a = 0 To 6 * pi Step 0.2
s = s & (1000 + 100 * a) & " " & (2000 + Sin(a) * 500) & " "
Next
vp.Polyline = s
vp.EndDoc
The Polyline property draws an open shape using the current pen. To draw closed shapes, use the Polygon property
instead.
Data Type
String
See Also
Port Property
Returns or sets the name of the current port.
Syntax
[form!]VSPrinter.Port[ = value As String ]
Remarks
You can use this property to provide user feedback -- so users know which printer port is currently selected -- or to select
the printer port you want to use.
123
You cannot change this property while creating a document. If you want to select a port, do so before calling the
StartDoc method. You can only set this property to a valid port name. To obtain a list of valid port names, read the
Ports() property.
If the DefaultDevice property is set to True, the port selected will become the default port for all Windows applications.
Data Type
String
See Also
Ports Property
Returns the names of the ports to which the current printer is connected.
Syntax
val$ = [form!]VSPrinter.Ports(i As Integer)
Remarks
This property returns the names of all ports that have devices with the same name as the current device. The valid range
is from zero to NPorts - 1.
For example, if the current Device is an "HP LaserJet 4L" connected to "LPT1:" and there's another "HP LaserJet 4L"
connected to "LPT2:", then NPorts will return 2, Ports(0) will return "LPT1:", and Ports(1) will return "LPT2:".
Data Type
String
See Also
Preview Property
Returns or sets whether output saved for previewing or sent directly to the printer.
Syntax
[form!]VSPrinter.Preview [ = {True | False} ]
Remarks
If the Preview property is set to False, the VSPrinter control sends its output directly to the printer. The control will not
display the document at all. If the AbortWindow property is set to True, an Abort dialog is created and shown while the
document prints, so the user can abort the print job.
If the Preview property is set to True, the VSPrinter control saves all output in memory. When the document is ready,
you can preview it, save it to disk, create overlays, or send it to the printer.
For example, the following code creates the same document twice: the first time it is printed directly to the printer. The
second time, it remains available for previewing and later printing.
' This routine sends the document directly to the printer
' (there is no preview)
Sub PrintButton_Click ()
vsPrinter.Preview = False
DoPrinting
End Sub
' This routines creates the document in memory

' (you can preview, save, or print it later)
Sub Preview_Click ()
vsPrinter.Preview = True
124
DoPrinting
End Sub
Data Type
Boolean
Default Value
True
See Also
PreviewPage Property
Returns or sets the current preview page (first page is 1).
Syntax
[form!]VSPrinter.PreviewPage[ = value As Integer ]
Remarks
Use this property in preview mode to determine which preview page is currently visible, or to select a page for
previewing.
Valid pages range from one to PageCount. If you set the Preview property to a value less than one, it is set to one. If
you set the Preview property to a value larger than PageCount, it is set to PageCount. Either way, no error is fired.
If the ZoomMode property is set to a value that causes more than one page to be displayed at once (zmTwoPages or
zmThumbnail), then PreviewPage returns the number of the first page being displayed. The total number of pages
displayed can be determined by reading the PreviewPages property.
Data Type
Integer
See Also
PreviewPages Property
Returns the number of pages displayed in the preview area.
Syntax
val% = [form!]VSPrinter.PreviewPages
Remarks
The number of pages previewed at a time depends on the setting of the ZoomMode property.
Most ZoomMode settings cause one page to be displayed at a time. The exceptions are settings zmTwoPages, which
displays two pages side by side, and zmThumbnail, which displays as many one-inch wide pages as will fit on the
control.
This property is mostly used to provide user feedback, displaying information such as "Now showing pages 1 to 7 of 23".
Data Type
Integer
See Also
125
PrintQuality Property
Returns or sets the print quality.
Syntax
[form!]VSPrinter.PrintQuality[ = PrintQualitySettings ]
Remarks
Valid settings for the PrintQuality property are described below:

pqDraft -1 Lowest possible resolution.
pqLow -2 Low resolution.
pqMedium -3 Medium resolution.
pqHigh -4 Highest possible resolution.
Other >0 Specifies the desired resolution, in dots per inch.
Data Type
PrintQualitySettings (Enumeration)
See Also
ProportionalBars Property (VSPrinter)

Returns or sets whether the scrollbar thumbs (VSPrinter Control) should be proportional to the size of the visible area.
Syntax
[form!]VSPrinter.ProportionalBars[ = {True | False} ]
Data Type
Boolean
Default Value
True
See Also
ReadyState Property
Returns the current state of the control.
Syntax
val% = [form!]VSPrinter.ReadyState
Remarks
126
The values returned by the ReadyState property are described below:

vpstEmpty 0 The control is empty (there is no preview document).
vpstLoading 1 The control is loading a document from a disk file or URL.
vpstReady 2 The control has a preview document that can be saved or
printed.
vpstOpen 3 The control is generating a document (StartDoc has been called,
EndDoc has not).
vpstSaving 4 The control is saving a document to a disk file.
vpstPrinting 5 The control is printing a document.
When control state changes, the control sets the ReadyState property and fires the ReadyStateChange event.
There are many instances where an application may need to know the state of the control. For example, a Print button
should be enabled only when the control has a document available for printing (vpstReady), and an Abort button should
be enabled only while the control is generating a document (vpstOpen).
This property is especially useful for applications that create or load documents asynchronously. For example:
1. When generating long documents, you may want to add DoEvents statements to your document generation
function to keep the application responsive while the document is generated. In this case, you should make
sure the document generation function is not called recursively. The following code illustrates this
technique:
Private Function GenerateDocument() As Boolean
' ** avoid recursive calls

If vp.ReadyState <> vpstReady Then Exit Function
' ** control is ready, so create document

vp.StartDoc
Dim i%
For i = 0 To 1000
GeneratePage i
DoEvents ' ** keep application responsive
If vp.Error <> 0 Then Exit For ' ** bail on errors
Next
vp.EndDoc
' ** done
GenerateDocument = True
Exit Function
2. When the control is used on a Web page and a document is loaded using the URL property, the
ReadyState property will be set to vpstLoading while the document is downloaded from the server and
loaded into the control, and it will be set to vpstReady when the document is ready to be displayed. You can
trap the ReadyStateChange event and enable some page elements (such as a Print button) when the
document is ready. The following code illustrates this technique:
<html>
<head>
<title>VSPrinter8 ReadyState</title>
</head>
<script language="vbscript">
Sub vp_ReadyStateChange(ReadyState)
sStates = Split("Empty Loading Ready Open Saving Printing", " ")
document.all.ReadyDiv.innerText = "The VSPrinter is " & sStates(ReadyState)
End Sub
127
</script>
<body>
<p><div id=ReadyDiv>The VSPrinter control is Empty</div><p>
<object classid="clsid:A8561647-E93C-11D3-AC3B-CE6078F7B616" id=vp width=497 height=609>
<param name=PageBorder value=7><param name=NavBar value=3>
<param name=URL value="http://localhost/default.html">
</object>
</p>
</body>
</html>
Data Type
ReadyStateSettings (Enumeration)
See Also
RenderControl Property
Renders an OPP-enabled control (such as the VSFlexGrid) on the page.
Syntax
[form!]VSPrinter.RenderControl = value As Long
Remarks
To render an OPP (Open Printing Protocol) enabled control on a page, assign its window handle (hWnd property) to the
RenderControl property.
The ComponentOne VSFlexGrid control supports OPP and can be rendered using the RenderControl property. For
example, the following code renders three grids onto a report, with titles above each one:
With vp
.StartDoc
.Paragraph = "Here is the list of customers:"

.RenderControl = VSFlexGridCustomers.hWnd
.Paragraph = "Here is the list of suppliers:"

.RenderControl = VSFlexGridSuppliers.hWnd
.Paragraph = "Here is the list of products:"

.RenderControl = VSFlexGridProducts.hWnd
.EndDoc
End With
Using the RenderControl property to print a control has the following advantages over other approaches (such as
PrintForm):
1. RenderControl leverages all VSPrinter's capabilities, including previewing, the ability to add custom
headers and footers, margin control, and so on.
2. The control is incorporated into a document. This means you can render multiple controls into a document,
add annotations, pictures, charts and so on.
3. RenderControl supports spanning pages both vertically and horizontally. (Grid controls often spill
sideways as well as down.)
4. The VSPrinter only provides the drawing context, but the control is responsible for rendering itself. Thus,
the final image is completely accurate.
5. Rendering a control on a page takes only one line of code.
Data Type
128
Long
See Also
RetrieveTag Property
Returns a string containing the first tag found on a region of the current document.
Syntax
val$ = [form!]VSPrinter.RetrieveTag(Left As Variant, Top As Variant, [ Right As Variant ], [ Bottom As Variant ], [
Page As Variant ], [ ClientCoords As Variant ])
Remarks
used for a number of things, including document annotation, pop-up notes, hyperlinks, and more. The RetrieveTag
property allows you to retrieve tags based on their position in the document. To search for tags based on their content,
use the FindTag property instead. For details and examples about creating and using tags, see the Build a Table of
Contents (page 60) sample.
The parameters for the RetrieveTag property are described below:
Left, Top As Variant
These parameters define the left and top coordinates of the region to be searched for a tag. You may specify units with
these parameters (inches, points, twips, cm, mm, or pixels). The default unit is twips. For details on using unit-aware
measurements, see the Using Unit-Aware Properties (page 16) topic.
Right, Bottom As Variant (optional)
These parameters define the right and bottom coordinates of the region to be searched for a tag. They are optional, and
default to the values of the Left and Top parameters (in which case the control looks for a tag that contains the given
point).
Page As Variant (optional)
This parameter defines the page to be searched for a tag. It is optional, and defaults to the current preview page
(PreviewPage property).
ClientCoords As Variant (optional)
This parameter determines whether the Left, Top, Right, and Bottom parameters express coordinates in client coordinates
(as opposed to page coordinates). This parameter is optional and defaults to False (page coordinates). Note that you may
convert coordinates using the ClientToPage and PageToClient methods.
The property returns the text of the tag, if it was found, or an empty string otherwise.
For example, the following code handles the MouseMove event to look for tags as displays them as tooltips if they are
found:
Private Sub vp_MouseMove(Button As Integer, _
Shift As Integer, x As Single, y As Single)
' ** show tooltips if no button is being pressed

If Button = 0 Then
' ** retrieve tag using mouse (client) coordinates

vp.ToolTipText = vp.RetrieveTag(x, y, , , , True)
End If
End Sub
Data Type
129
String
See Also
RetrieveText Property
Returns a string containing the text on a region of the current document.
Syntax
val$ = [form!]VSPrinter.RetrieveText(Left As Variant, Top As Variant, [ Right As Variant ], [ Bottom As Variant ], [
Page As Variant ], [ ClientCoords As Variant ])
Remarks
The RetrieveText property allows you to retrieve text based on its position in the document. To search for text within a
document, use the FindText property instead.
The parameters for the RetrieveText property are described below:
Left, Top As Variant
These parameters define the left and top coordinates of the region to be searched for a tag. You may specify units with
these parameters (inches, points, twips, cm, mm, or pixels). The default unit is twips. For details on using unit-aware
measurements, see the Using Unit-Aware Properties (page 16) topic.
Right, Bottom As Variant (optional)
These parameters define the right and bottom coordinates of the region to be searched for a tag. They are optional, and
default to the values of the Left and Top parameters (in which case the control looks for a tag that contains the given
point).
Page As Variant (optional)
This parameter defines the page to be searched for a tag. It is optional, and defaults to the current preview page
(PreviewPage property).
ClientCoords As Variant (optional)
This parameter determines whether the Left, Top, Right, and Bottom parameters express coordinates in client coordinates
(as opposed to page coordinates). This parameter is optional and defaults to False (page coordinates). Note that you may
convert coordinates using the ClientToPage and PageToClient methods.
The property returns the text contained in the specified region.
Data Type
String
See Also
ScaleOutput Property
Returns or sets the percentage by which the printed output is to be scaled.
Syntax
[form!]VSPrinter.ScaleOutput[ = value As Integer ]
Remarks
The apparent page size is scaled from the physical page size by a factor of ScaleOutput/100. For example, a letter-sized
page with a ScaleOutput value of 50 would contain as much data as a page of 17- by 22-inches because the output text
and graphics would be half their original height and width.
130
Note: This property does not affect the measurements or coordinate system used to produce images on a page, nor does
it affect the appearance of the preview image either. It only works at the printer driver level.
Data Type
Integer
See Also
ScrollLeft Property (VSPrinter)

Returns or sets the left coordinate of the visible area, in twips.
Syntax
[form!]VSPrinter.ScrollLeft[ = value As Double ]
Remarks
The ScrollLeft and ScrollTop properties allow you to control the VSPrinter's scroll bars. You can read these values to
determine what part of the preview page the user is looking at, or set them to make a part of the page visible.
When these properties are set, the control validates the ranges automatically and clips the values if necessary. If you
assign negative values, the properties are set to zero. If you assign very large values, the properties are set to the
maximum value in the scrollbar range.
For example, the following code shows how you can display the top-left or bottom-right corners of a page.
Private Sub cmdTopLeft()
vp.ScrollLeft = 0
vp.ScrollTop = 0
End Sub
Private Sub cmdBottomRight()

vp.ScrollLeft = 32000 ' large value causes maximum to be used
vp.ScrollTop = 32000
End Sub
The following code centers the page on the preview window:

Private Sub cmdCenter()
Dim x, y
x = vp.PageWidth / 2 * (vp.Zoom / 100)
y = vp.PageHeight / 2 * (vp.Zoom / 100)
vp.ScrollLeft = x - (vp.Width - 300) / 2
vp.ScrollTop = y - (vp.Height - 300) / 2
End Sub
The code starts by calculating the position of the page center, then scales it by the current zoom factor. Finally, the code
subtracts half the control width, in twips (the 300 factor is the size of the scroll bar, which has to be discounted).
Data Type
Double
See Also
ScrollTop Property (VSPrinter)

Returns or sets the top coordinate of the visible area, in twips.
131
Syntax
[form!]VSPrinter.ScrollTop[ = value As Double ]
Remarks
The ScrollLeft and ScrollTop properties allow you to control the VSPrinter's scroll bars. You can read these values to
determine what part of the preview page the user is looking at, or set them to make a part of the page visible.
When these properties are set, the control validates the ranges automatically and clips the values if necessary. If you
assign negative values, the properties are set to zero. If you assign very large values, the properties are set to the
maximum value in the scrollbar range.
For an example, see the ScrollLeft property.
Data Type
Double
See Also
ShowGuides Property
Returns or sets whether margin guides are displayed on the page.
Syntax
[form!]VSPrinter.ShowGuides[ = ShowGuideSettings ]
Remarks
The settings for the ShowGuides property are described below:

gdHide 0 Never show guides.
gdShow 1 Always show guides.
gdDesignTime 2 Show guides at design time (default setting).
Guides are thin dotted lines that show the position of the margins, headers, and footers. They also show the printable area
of the page if PhysicalPage is set to False.
The guides are especially useful at design time, when they provide feedback showing where the margins, headers, and
footers will be located on the page. If our applications allow users to modify the page layout, you may want to set the
ShowGuides property to True to provide the users with the same feedback.
The following image shows what the preview page looks like with and without the guides:
132
Data Type
ShowGuideSettings (Enumeration)
Default Value
gdDesignTime (2)
See Also
SmallChangeHorz Property (VSPrinter)

Returns or sets the amount of change to the ScrollLeft property when the user clicks the scroll arrow.
Syntax
[form!]VSPrinter.SmallChangeHorz[ = value As Double ]
Data Type
Double
Default Value
30
See Also
SmallChangeVert Property (VSPrinter)

Returns or sets the amount of change to the ScrollTop property when the user clicks the scroll arrow.
Syntax
[form!]VSPrinter.SmallChangeVert[ = value As Double ]
Data Type
133
Double
See Also
SpaceAfter Property
Returns or sets the vertical distance after each paragraph, in twips.
Syntax
[form!]VSPrinter.SpaceAfter[ = value As Variant ]
Remarks
The SpaceBefore and SpaceAfter properties set the amount of vertical spacing to add before and after each paragraph.
The spacing specified applies to regular paragraphs, table cells, and textboxes (drawn using the TextBox method).
To specify the horizontal spacing to the left and right of each paragraph, use the IndentLeft, IndentRight, and
IndentFirst properties.
Data Type
Variant
See Also
SpaceBefore Property
Returns or sets the vertical distance before each paragraph, in twips.
Syntax
[form!]VSPrinter.SpaceBefore[ = value As Variant ]
Remarks
The SpaceBefore and SpaceAfter properties set the amount of vertical spacing to add before and after each paragraph.
The spacing specified applies to regular paragraphs, table cells, and textboxes (drawn using the TextBox method).
To specify the horizontal spacing to the left and right of each paragraph, use the IndentLeft, IndentRight, and
IndentFirst properties.
Data Type
Variant
See Also
Styles Property
Returns a collection of styles that can be applied to the document.
Syntax
val% = [form!]VSPrinter.Styles
Remarks
134
A VSPrinter "Style" is a group of properties that affect the appearance of text and graphical elements that are rendered
on the page.
The Styles collection is an object that exposes methods that allow you to create, apply, and manage styles. The methods
and properties exposed by the Styles object are described below:
vp.Styles.SetPageExtent
Method that removes all styles from the collection.

val% = vp.Styles.Count
Property that returns the number of styles in the Styles collection.

vp.Styles.Add(Key As String, Flags As StyleFlagsSettings)
Method that defines a new style based on the VSPrinter control's current settings. The new style is saved into the
collection under the name Key (if a style by that name is already defined, it is overwritten).
The Flags parameter specifies which style elements should be saved. Valid settings for the Flags parameter are:
Symbol Value Saves/Restores

vpsCharacter 1 Font, TextColor, and TextAngle properties.
vpsParagraph 2 SpaceBefore, SpaceAfter, LineSpacing, Indent*, and
TextAlign properties.
vpsGraphics 4 Brush*, Pen*, TablePen*, and TableBorder properties.
vpsContent 7 All of the above (vpsCharacter + vpsParagraph +
vpsGraphics).
vpsPage 8 Margin*, Columns, ColumnSpacing, and PageBorder
properties.
vpsAll 65535 All of the above.
vp.Styles.Remove(Index As Variant)
Deletes the given style, removing it from the collection. The Index parameter should correspond to the name of an
existing style, or it should be an index ranging from zero to vp.Styles.Count - 1.
vp.Styles.Apply(Index As Variant)
Applies the given style to the VSPrinter control, modifying the set of properties defined when the style was created.
vp.Styles.Key(Index As Variant) [ = NewKey As String]
Returns or sets the name (key) for a given style. If NewKey has already been assigned to another style, an Invalid Index
error will occur.
val% = vp.Styles.Flags(Index As Variant)
Returns the flags associated with a given style when the style was defined.
vp.Styles.Save(FileName As String)
Saves the current Styles collection to a disk file.

vp.Styles.Load(FileName As String)
Loads a set of styles from a disk file into the Styles collection. Existing styles are preserved, unless a style being loaded
has the same name as an existing style, in which case the existing style is overwritten with the one being loaded form
disk.
Styles are useful for two main purposes:
135
1. To define a consistent look for your documents. You can set up a routine that defines a basic set of styles
and is completely separate from the routine that generates the document using the predefined styles. If you
decide to change the styles, or to implement different "templates" for your documents, change only the
routine that defines the styles, and not the one that generates the documents. You can even save the styles
to disk and share the styles among several applications. For example:
Sub DefineStyles()
vp.FontName = "Tahoma"
vp.FontSize = 10
vp.SpaceAfter = "8pt"
vp.Styles.Add "Normal", vpsAll
vp.FontSize = "14"
vp.SpaceBefore = "1in"
vp.Styles.Add "Title", vpsAll
End Sub
Sub CreateDocument()
vp.Startdoc
vp.Styles.Apply "Title"
vp.Paragraph = "Welcome to VSPrinter Styles"
vp.Styles.Apply "Normal"
vp.Paragraph = "This is the normal style."
vp.EndDoc
End Sub
2. Styles allow you to save and restore the control state easily and efficiently. Instead of saving a large
number of properties, creating the output you want, and then restoring the saved properties, you can simply
define a "Scratch" style, make all the changes you want, then restore the "Scratch" style. For example:
vp.Styles.Add "Scratch", vpsAll
vp.FontName = "Symbol"
vp.IndentLeft = "2in"
vp.Paragraph = "Bet you can't read this!"
vp.Styles.Apply "Scratch"
Data Type
IVSPrinterStyle
See Also
Table Property
Renders a table on the page.
Syntax
[form!]VSPrinter.Table = value As String
Remarks
The string assigned to the Table property is divided into rows and columns by special characters defined through the
TableSep property. By default, rows are separated by semi-colons (";") and columns by column pipes ("|").
The first row contains formatting information only and is not printed. The formatting information consists of sequences
of formatting characters (one sequence for each column) followed by a column width. For a description of the format
string, see the AddTable method.
For example, the following code prints a table with five rows and four columns:
sFmt$ = "+^1440|+^1050|+^2000|+=4000;"
sBody$ = "Last|First|Instrument|Favorite;" & _
"Page|James Patrick|Guitar|Stairway to Heaven;" & _
"Plant|Robert|Vocals|Going to California;" & _
"Jones|John Paul|Bass, Keyboards|The Lemon Song;" & _
"Bonham|John Bonzo|Drums|Rock & Roll, The Rover;"
vp.Table = sFmt & sBody
136
Note: This property is provided for compatibility with old projects. New projects should use the AddTable method
instead. AddTable provides a clearer syntax and more powerful formatting options. For even more formatting options,
see also the StartTable and EndTable methods and the TableCell property.
Data Type
String
See Also
TableBorder Property
Returns or sets the type of border for tables.
Syntax
[form!]VSPrinter.TableBorder[ = TableBorderSettings ]
Remarks
The border is drawn using the current pen. Its color, style, and thickness are determined by the PenColor, PenStyle, and
PenWidth properties. You may override the pen width using the TablePen, TablePenLR, and TablePenTB properties.
The following image shows valid settings for the TableBorder property and their effect:
Notice how the header and body are treated as different tables. For example, for the setting tbBottom, you get a border
below the header row and another below the last row.
Note: You may also create additional vertical borders at specific positions by embedding formatting characters in the
table format string (see AddTable). You may create additional vertical and horizontal borders at specific positions using
the TableCell property.
Data Type
TableBorderSettings (Enumeration)
137
See Also
TableCell Property
Returns or sets properties of a table cell or range.
Syntax
[form!]VSPrinter.TableCell(Setting As TableCellSettings, [ Row1 As Variant ], [ Col1 As Variant ], [ Row2 As Variant
], [ Col2 As Variant ]) [ = value As Variant ]
Remarks
The TableCell property is used to build and format tables. Using TableCell requires four steps:
1. Start a table definition with the StartTable method.
2. Create the table using the AddTable or AddTableArray methods, or using the TableCell property by
itself.
3. Format the table using the TableCell property.
4. Close the table definition with the EndTable method. This will render the table.
The parameters for the TableCell property are described below:
Setting Determines which property of the table, row, column, or cell you want to set or
retrieve. The list of valid settings is given below.
Row1 First row in the range. The header row has index zero. Body rows are one-based.
Col1 First column in the range. The first column has index one.
Row2 Last row in the range. Optional, defaults to Row1.
Col2 Last column in the range. Optional, defaults to Col1.
Setting the TableCell property affects the range of cells specified by the Row1, Col1, Row2, and Col2 parameters.
Getting the TableCell property retrieves properties from the cell specified by the Row1 and Col1 parameters. Some
parameters apply to the whole table, others to entire rows or columns. In these cases, one or more of the range
parameters are ignored.
The TableCell property is very powerful because the Setting parameter lets you access and modify virtually any aspect
of a table. The TableCellSettings enumeration has over 40 values you can use. They are listed below, according to the
type of formatting they provide.
Table Properties: These settings affect the entire table.

tcIndent 0 Returns or sets the indent for the table. You may specify units
with this value (the default unit is twips).
tcRows 1 Returns or sets the number of rows on the table. The header row is
not included in this count. If you change the number of rows, rows
are added or deleted from the bottom of the table.
138
tcCols 2 Returns or sets the number of columns on the table. If you change
the number of columns, columns are added or deleted from the
right of the table.
tcInsertRow 3 Inserts a row at the specified position (Row1).
tcInsertCol 4 Inserts a column at the specified position (Col1).
tcDeleteRow 5 Deletes the row at the specified position (Row1).
tcDeleteCol 6 Deletes the column at the specified position (Col1).
Row Properties: These settings affect entire rows or row ranges. The Col1 and Col2 parameters are ignored:

tcRowHeight 7 Returns or sets the height of the rows. The header row has
index zero. You may specify units with this value (the
default unit is twips).
tcRowBorder 8 Returns or sets whether the rows will have a border drawn
above them. Possible values are: 0 (no border), 1 (force
border), and 2 (honor TableBorder setting).
tcRowData 9 Returns or sets a Variant associated with the row. This
value is for your own use, and is not used by the control.
tcRowSource 10 Returns or sets the array row used as a data source for the
table row. This setting only applies if the table was bound
to an array (with the AddTableArray method). Note that
array indices are zero-based, and table indices are one-
based.
tcRowKeepWithNext 11 Returns or sets whether the control should prevent page
breaks after the rows.
tcRowIsSubHeader 12 Returns or sets whether the row should become the table
header after it is rendered (useful for subtitles).
tcRowSpaceBefore 34 Returns or sets the amount of vertical space to insert
before each cell on the row.
tcRowSpaceAfter 35 Returns or sets the amount of vertical space to insert after
each cell on the row.
tcRowBorderAbove 36 Returns or sets the thickness of a custom border to be
drawn above the row.
tcRowBorderBelow 37 Returns or sets the thickness of a custom border to be
drawn below the row.
tcRowBorderColor 38 Returns or sets the color of the custom borders drawn
above and below the row.
tcRowNewPage 39 Returns or sets whether the row should be the first on a
page (forcing a page break if necessary).
tcRowKeepTogether 40 Returns or sets whether the row should be kept together on
a page or whether it can be broken and rendered on two
pages.
139
Column Properties: These settings affect entire columns or column ranges. The Row1 and Row2 parameters are
ignored:

tcColWidth 13 Returns or sets the width of the columns. You may specify
units with this value (the default unit is twips).
tcColBorder 14 Returns or sets whether the columns will have a border
drawn on their right-hand side. Possible values are: 0 (no
border), 1 (force border), and 2 (honor TableBorder
setting).
tcColData 15 Returns or sets a Variant associated with the column. This
value is for your own use, and is not used by the control.
tcColSource 16 Returns or sets the array column used as a data source for
the table column. This setting only applies if the table was
bound to an array (with the AddTableArray method). Note
that array indices are zero-based, and table indices are one-
based.
tcColAlign 31 Returns or sets the alignment for the column. Valid settings
are the same used with the TextAlign property.
tcColNoWrap 32 Returns or sets whether long text entries should be allowed
to wrap within cells on this column.
tcColSkipRepeats 33 Returns or sets whether repeated text entries (with the same
text as the cell above) should be skipped on this column.
tcColBorderLeft 43 Returns or sets the thickness of a custom border to be
drawn to the left of this column.
tcColBorderRight 44 Returns or sets the thickness of a custom border to be
drawn to the right of this column.
tcColBorderColor 45 Returns or sets the color of the custom borders drawn to the
left and right of this column.
Cell Properties: These settings affect individual cells or cell ranges:

tcColSpan 17 Returns or sets the number of columns that the cell should span
(column merging).
tcText 18 Returns or sets the cell text. If the table is bound to an array,
setting the property will change the table, but not the source
array.
tcAlign 19 Returns or sets the alignment of text in the cells. Valid settings
are the same used with the TextAlign property.
tcBackColor 20 Returns or sets the background color for the cell.
tcForeColor 21 Returns or sets the foreground (text) color for the cell.
tcFont 22 Returns or sets the cell font.
tcFontName 23 Returns or sets the name of the cell font.
140
tcFontSize 24 Returns or sets the size of the cell font.
tcFontBold 25 Returns or sets the bold attribute of the cell font.
tcFontItalic 26 Returns or sets the italic attribute of the cell font.
tcFontUnderline 27 Returns or sets the underline of the cell font.
tcFontStrikethru 28 Returns or sets the strikethrough attribute of the cell font.
tcPicture 29 Returns or sets the cell picture.
tcPictureAlign 30 Returns or sets the alignment of pictures in the cells. Valid
settings are the same used with the TextAlign property.
tcRowSpan 41 Returns or sets the number of rows that the cell should span
(row merging).
tcVertical 42 Returns or sets whether the cell text should be rendered in the
vertical direction.
tcAlignCurrency 46 Aligns to the right and accounts for parenthesis.
Negative currency values are often shown enclosed in
parenthesis.
The Table Formatting (page 50) example shows how you can use the TableCell property to create and format a table.
Data Type
Variant
See Also
TablePen Property
Returns or sets the width of the borders between table cells.
Syntax
[form!]VSPrinter.TablePen[ = value As Variant ]
Remarks
Normally, table borders are drawn using the current pen, whose width is determined by the PenWidth property. The
TablePen, TablePenLR, and TablePenTB properties allow you to specify different pen widths to be used when
drawing table borders. If any of these properties is set to zero, the default pen width is used instead.
TablePen determines the thickness of the lines drawn inside the table. TablePenLR determines the thickness of the
lines drawn to the left and to the right of the table. TablePenTB determines the thickness of the lines drawn on the top
and on the bottom of the table. The position of the borders is specified with the TableBorder property.
You may specify units with these values (inches, points, twips, cm, mm, or pixels). The default unit is twips. For details
on using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
The following example shows how these properties are used:
Dim s$
With vp
.TableBorder = tbAll
.TablePen = 1 ' thin lines inside the table
.TablePenTB = 80 ' thick line above and below the table
.TablePenLR = 30 ' medium lines on the left and right of the table
.StartDoc
s = "This is a table|This is a table|This is a table;"
.Table = "1440|1440|1440;" & s & s & s
.EndDoc
141
End With
Here is the table created by the above code:
Note: You can create borders with custom thickness and colors around specific rows and columns using the TableCell
property (see the tcRowBorder* and tcColBorder* settings).
Data Type
Variant
Default Value
0
See Also
TablePenLR Property
Returns or sets the width of the left and right table borders.
Syntax
[form!]VSPrinter.TablePenLR[ = value As Variant ]
Remarks
See the TablePen property for more details and an example.
142
Data Type
Variant
Default Value
0
See Also
TablePenTB Property
Returns or sets the width of the top and bottom table borders.
Syntax
[form!]VSPrinter.TablePenTB[ = value As Variant ]
Remarks
See the TablePen property for more details and an example.
Data Type
Variant
Default Value
0
See Also
TableSep Property
Returns or sets the characters used by tables as row and column separators.
Syntax
[form!]VSPrinter.TableSep[ = value As String ]
Remarks
The TableSep property is used in conjunction with AddTable and AddTableArray methods to determine which
characters should be interpreted as column and row separators for the table format and body strings. The TableSep
property contains a string with two characters: the first is used as a column separator, and the second as a row separator.
The default value for this property is the string "|;", which means pipe characters are used to separate columns and
semicolons are used to separate rows.
To use tabs to separate columns and line breaks to separate rows, for example, you would write:
vp.TableSep = vbTab & vbLf
The value assigned to this property must be a two-character string, and the characters must be different. If the string is
invalid, the default separators are used (pipe and semi-colon).
Data Type
String
143
Default Value
"|;"
See Also
Text Property (VSPrinter)

Renders a string on the page at the current cursor position.
Syntax
[form!]VSPrinter.Text = value As String
Remarks
This property renders text on the page, at the current cursor position (determined by the CurrentX and CurrentY
properties).
It is similar to the Paragraph property, except it does not terminate the string with a new line. Instead, it leaves the
cursor at the point where the text stopped, allowing you to print a paragraph in pieces. This is the most efficient way to
generate paragraphs with mixed fonts and colors.
For example, the following code prints VB source files. The code prints function names in bold red letters, and the
remaining text in regular black characters:
Sub PrintVBFile(FileName as String)
Dim ln$, subname$, subargs$
Open FileName For Input As #1
With vp
.StartDoc
While Not EOF (1)
Line Input #1, ln
If Left(ln, 3) = "Sub" Then ' print function header
ln = Mid(ln, 4)
subname = Left(ln, Instr (ln, " "))
subargs = Mid(ln, Instr (ln, " "))
.Text = "Sub "
.FontBold = True: .TextColor = vbRed
.Text = subname
.FontBold = False: .TextColor = vbBlack
.Text = subargs
Else ' print regular paragraph
.Paragraph = ln
End If
Wend
.EndDoc
End With
End Sub
The VPRenderHTML function in the VPUtil.BAS file uses the Text property extensively to render HTML text. If you
include the VPUtil.BAS file in your projects, you can use the VPRenderHTML function to render text with embedded
formatting. For example:
VPRenderHTML vp, "Hello, this is <B>BOLD</B> and this is <I>ITALICS</I>."
Note: You can also print paragraphs with mixed fonts using the TextRTF property. Using RTF provides a little more
flexibility than using the Text property, but rendering RTF takes a lot longer.
Data Type
String
See Also
144
TextAlign Property (VSPrinter)
Returns or sets the alignment of printed paragraphs, textboxes, and tables.
Syntax
[form!]VSPrinter.TextAlign[ = TextAlignSettings ]
Remarks
The settings for the TextAlign property are described below:

taLeftTop 0 Align to the left and to the top.
taCenterTop 1 Align to the center and to the top.
taRightTop 2 Align to the right and to the top.
taLeftBottom 3 Align to the left and to the bottom.
taCenterBottom 4 Align to the center and to the bottom.
taRightBottom 5 Align to the right and to the bottom.
taLeftMiddle 6 Align to the left and to the middle.
taCenterMiddle 7 Align to the center and to the middle.
taRightMiddle 8 Align to the right and to the middle.
taJustTop 9 Justify and align to the top.
taJustBottom 10 Justify and align to the bottom.
taJustMiddle 11 Justify and align to the middle.
The setting specifies the horizontal and vertical alignment. The vertical alignment specification only applies for text
drawn in table cells and text boxes. For regular paragraphs and text, the top of the characters is rendered at the CurrentY
position.
Note: If you use the Text property to render a paragraph word by word, and change font sizes between words, the
control automatically adjusts the CurrentY position so that the bottom of every character lines up.
Data Type
TextAlignSettings (Enumeration)
See Also
TextAngle Property (VSPrinter)

Returns or sets the text angle, in tenths of degree.
Syntax
[form!]VSPrinter.TextAngle[ = value As Integer ]
Remarks
Setting the TextAngle property to a non-zero value disables word wrapping when rendering text and paragraphs.
145
The TextAngle property applies to text boxes (drawn with the TextBox method). The entire text box is rotated about
the top left corner by the specified angle. Text wraps normally within the text box, and the shaded rectangle and borders
are also rotated.
The rotation is applied in the counter-clockwise direction, starting from the three o'clock position, as shown in the
following graphic:
Note: To rotate table cells so they are rendered vertically, set the TableCell(tcVertical) property instead.
Data Type
Integer
See Also
TextColor Property (VSPrinter)

Returns or sets the color used to print text.
Syntax
[form!]VSPrinter.TextColor[ = colorref& ]
Remarks
This property determines the color used to render all text except the headers and footers. To set the color of the headers
and footers, use the HdrColor property instead.
Data Type
Color
See Also
TextHei Property
Returns the height of a string measured with the Measure property, in twips.
Syntax
val# = [form!]VSPrinter.TextHei
Remarks
This property returns the height, in twips, of an element measured with the Measure property or with one of the Calc*
properties. These include CalcText, CalcParagraph, CalcTable, CalcPicture, and CalcTextRTF.
Data Type
Double
See Also
146
TextHeight Property (VSPrinter)
Returns the height of a string, in twips.
Syntax
val# = [form!]VSPrinter.TextHeight(Text As String)
Remarks
This property does not take into account word wrapping or the settings of the SpaceBefore and SpaceAfter properties.
To measure formatted text, use the CalcParagraph or CalcText properties instead.
Data Type
Double
See Also
TextRTF Property
Renders RTF text on the page at the current cursor position.
Syntax
[form!]VSPrinter.TextRTF = value As String
Remarks
RTF (Rich Text Format) allows you to embed special formatting codes into the text to be printed. You may obtain RTF
text from many sources, including RTF files created by WordPad, Microsoft® Word, or from a RichEdit control.
Alternatively, you may choose to create the RTF text manually.
All RTF text starts with a header section that contains a font table and a color table (and possibly other optional
elements). If you assign an RTF string without an RTF header to the TextRTF property, VSPrinter will realize that the
header is missing and will create one on the fly. This automatically generated header contains a single font and a single
color (based on the control's Font and TextColor properties.) Because there is a single font in the automatically
generated header, you may change the font style and size, but not its name (typeface).
For example, the following code prints a string with embedded bold and italics:
vp.TextRTF = "Hello. This is {\b BOLD}, and this is {\i ITALICS}."
If you need to combine multiple typefaces into a single string, you must supply the RTF header yourself. The easiest way
to do this is to create the document in WordPad, save it as RTF, then open the file in NotePad and tweak it.
For example, the following code prints a string with different fonts:
vp.TextRTF = "{\rtf1\ansi\deff0\deftab720" & _
"{\fonttbl{\f0\fswiss Arial;}" & _
"{\f1\froman Courier New;}}" & _
"{\colortbl\red0\green0\blue0;}" & _
"\f0\fs22 Hello. This is Arial and " & _
"this is {\f1 Courier}." & _
"}"
You can also use RTF text in cell tables, headers, footers, text boxes, and regular paragraphs. To do this, set the
AutoRTF property to True and enclose the text you want to print in curly braces ("{}").
VSPrinter uses the Windows RichEdit component (RICHED20.DLL) to render RTF. RichEdit is powerful, but not as
powerful as Microsoft® Word. In particular, RichEdit does not handle RTF tables, which means you cannot copy a
table from Word and render it using the TextRTF property. VSPrinter can, however, export tables into RTF files which
can then be read into Word.
Note: RTF is an extremely powerful format, but it is also fairly time-consuming to render. Use RTF only if you have to,
because it will slow down the creation of your documents.
147
Data Type
String
See Also
TextWid Property
Returns the width of a string measured with the Measure property, in twips.
Syntax
val# = [form!]VSPrinter.TextWid
Remarks
This property returns the width, in twips, of an element measured with the Measure property or with one of the Calc*
properties. These include CalcText, CalcParagraph, CalcTable, CalcPicture, and CalcTextRTF.
Data Type
Double
See Also
TextWidth Property (VSPrinter)

Returns the width of a string, in twips.
Syntax
val# = [form!]VSPrinter.TextWidth(Text As String)
Remarks
This property does not take into account word wrapping or the settings of the SpaceBefore and SpaceAfter properties.
To measure formatted text, use the CalcParagraph or CalcText properties instead.
Data Type
Double
See Also
Track Property (VSPrinter)

Returns or sets whether scrolling occurs as the user drags the scroll thumb.
Syntax
[form!]VSPrinter.Track[ = {True | False} ]
Data Type
Boolean
Default Value
False
See Also
148
TrueType Property
Returns or sets how TrueType fonts should be printed.
Syntax
[form!]VSPrinter.TrueType[ = TrueTypeSettings ]
Remarks
Valid settings for the TrueType property are described below:

ttBitmap 1 Prints TrueType fonts as raster graphics.
ttDownload 2 Downloads TrueType fonts as soft fonts.
ttSubDevice 3 Substitute device fonts for TrueType fonts.
ttOutline 4 Prints TrueType fonts as vector graphics.
The default value for this property depends on the type of printer you have. Generally, dot-matrix printers will use the
ttBitmap setting, Hewlett-Packard printers will use the ttDownload, and PostScript printers will use the ttSubDevice
setting by default.
Data Type
TrueTypeSettings (Enumeration)
See Also
TwipsPerPixelX Property
Returns the number of twips per printer pixel in the horizontal direction.
Syntax
val# = [form!]VSPrinter.TwipsPerPixelX
Remarks
Windows API routines generally require measurements in pixels. You can use the TwipsPerPixelX and
TwipsPerPixelY properties to convert measurements from twips to pixels.
Note: The VB objects Screen and Printer also have TwipsPerPixelX and TwipsPerPixelY properties that return the
number of twips per screen and printer pixel. Generally, printer have higher resolution than screens, so the Printer
object returns smaller values than the Screen object. The VSPrinter properties return the same value as VB's Printer
object (provided the same device is selected).
Data Type
Double
See Also
149
TwipsPerPixelY Property
Returns the number of twips per printer pixel in the vertical direction.
Syntax
val# = [form!]VSPrinter.TwipsPerPixelY
Remarks
Windows API routines generally require measurements in pixels. You can use the TwipsPerPixelX and
TwipsPerPixelY properties to convert measurements from twips to pixels.
Data Type
Double
See Also
URL Property
Returns or sets the name of a URL (Universal Resource Locator) to load into the control.
Syntax
[form!]VSPrinter.URL[ = value As String ]
Remarks
This property is especially useful when the VSPrinter control is used on a Web page. Setting the URL property causes
the control to download the requested file from the server and load it into the control. The URL may refer to a file
containing plain ASCII text, RTF text, or to a VSPrinter document saved with the SaveDoc method.
If you are using the VSPrinter control in a host application that has a Web context (such as Microsoft® Internet
Explorer), you can specify an absolute path (for example, http://myserver/start.htm) or a relative path that does not
include the protocol, or domain, or path (for example, page2.htm). If you specify a relative URL, the path is relative to
the page in which the VSPrinter control appears. If you specify a URL that is not valid, the VSPrinter control will set
the Error property to "File Not Found" and will fire the Error event.
When you assign a value to the URL property, the file is loaded asynchronously, that is, your code continues to execute
while the document is being downloaded. You can monitor this process using the ReadyState property and the
ReadyStateChange event. For more details and an example, refer to the ReadyState property documentation.
There are many Web-based scenarios where the URL property is useful:
You can use a VSPrinter control on the server to generate reports and save them on the server using the SaveDoc
method. Then publish a Web page containing another VSPrinter control and use the URL property to load the reports on
the client, where they could be previewed and printed exactly the way they were created (with headers, footers, graphical
elements, page breaks, and so on). Because the SaveDoc method creates compressed files by default, the reports can be
downloaded quickly.
You can use a VSPrinter control on a Web page to distribute RTF files, eliminating the need to convert them into
HTML and taking advantage of the built-in document navigation interface provided by the NavBar property.
The following example shows how you could use the URL property to load different types of files from a Web site into a
VSPrinter control hosted on a Web page:
<html>
<head>
<title>VSPrinter8 URL</title>
</head>
<script language=vbscript>
Sub btnLoadText_OnClick()
vp.URL = "http:\\localserver\samplefiles\readme.txt"
150
End Sub
Sub btnLoadRTF_OnClick()
vp.URL = "http:\\localserver\samplefiles\readme.rtf"
End Sub
Sub btnLoadVP_OnClick()
vp.URL = "http:\\localserver\samplefiles\readme.vp"
End Sub
</script>
<body>
<p>This is a <b>VSPrinter8</b> control:</p>
<p>
<object classid="clsid:A8561647-E93C-11D3-AC3B-CE6078F7B616"
id=vp width=250 height=350>
</object>
</p>
<p>
1: <input type=button value="Load Text File" name=btnLoadText><br>
2: <input type=button value="Load RTF File" name=btnLoadRTF><br>
3: <input type=button value="Load VSPrint Document" name=btnLoadVP><br>
</p>
</body>
</html>
Data Type
String
See Also
Version Property (VSPrinter)

Returns the version of the control currently loaded.
Syntax
val% = [form!]VSPrinter.Version
Remarks
You may want to check this value at the Form_Load event, to make sure the version that is executing is at least as
current as the version used to develop your application.
The version number is a three digit integer where the first digit represents the major version number and the last two
represent the minor version number. For example, version 7.0 returns 700.
Data Type
Integer
See Also
X1 Property (VSPrinter)
Returns or sets the left coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSPrinter.X1[ = value As Variant ]
Remarks
The X1, Y1, X2, and Y2 properties are used with other properties and methods:
1. They define a rectangle used to position and size objects drawn with the Draw and Picture properties.
151
2. They return a bounding box for elements measured with the CalcParagraph, CalcPicture, CalcTable,
CalcText, and CalcTextRTF properties.
3. They return the printable area of the page (discounting margins) after a call to the GetMargins method.
4. They return the position of a tag or a string after a call to the FindTag and FindText properties.
In all cases, the coordinates used have their origin at the top left corner of the page. All values are returned in twips.
When setting them, the default unit is also twips, but you may specify different units if you want. For details, see the
Using Unit-Aware Properties (page 16) topic.
Data Type
Variant
See Also
X2 Property (VSPrinter)
Returns or sets the right coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSPrinter.X2[ = value As Variant ]
See the X1 property.
Data Type
Variant
See Also
Y1 Property (VSPrinter)
Returns or sets the top coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSPrinter.Y1[ = value As Variant ]
Data Type
Variant
See Also
Y2 Property (VSPrinter)
Returns or sets the bottom coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSPrinter.Y2[ = value As Variant ]
Data Type
Variant
See Also
152
Zoom Property (VSPrinter)

Returns or sets the preview scale: set to a percentage, or zero to fill the control.
Syntax
[form!]VSPrinter.Zoom[ = value As Double ]
Remarks
If you set the Zoom property to 100, then the preview page appears in actual size. If you set it to 50, the page appears in
half its actual size, and so on.
If the page image is larger than the control, scroll bars are automatically added. If the control is larger than the page
image, the image is centered on the control and the empty area around it is filled with the color specified by the
EmptyColor property.
You can add automatic mouse support for panning, zooming, and switching pages by setting the Navigation property.
If you set the Zoom property to zero, the page image is stretched to fill the entire control. This is not a very useful
setting, but is provided for compatibility with earlier versions of the control.
The Zoom property works in conjunction with the ZoomMode property. If ZoomMode is set to a value other than
zmPercentage, the Zoom property returns the current zoom factor, which changes automatically when the control is
resized. If you assign a value to the Zoom property, the ZoomMode property will automatically be set to zmPercentage,
and the zoom factor will remain constant when the control is resized.
Data Type
Double
See Also
ZoomMax Property
Returns or sets the maximum valid zoom factor.
Syntax
[form!]VSPrinter.ZoomMax[ = value As Integer ]
Remarks
The ZoomMin, ZoomMax, and ZoomStep properties determine the valid range and step for zooming with the mouse.
You can override these values by trapping the BeforeUserZoom event.
These limits are not enforced for values assigned directly in code to the Zoom property.
Data Type
Integer
Default Value
400
See Also
ZoomMin Property
Returns or sets the minimum valid zoom factor.
153
Syntax
[form!]VSPrinter.ZoomMin[ = value As Integer ]
Remarks
Data Type
Integer
Default Value
10
See Also
ZoomMode Property (VSPrinter)

Sets or returns the zoom mode (explicit percentage or one of the automatic settings).
Syntax
[form!]VSPrinter.ZoomMode[ = ZoomModeSettings ]
Remarks
The settings for the ZoomMode property are described below:

zmPercentage 0 Use zoom factor set by the user with Zoom property.
zmThumbnail 1 Show as many 1-inch wide preview pages as will fit on the
control.
zmTwoPages 2 Show two whole pages, side by side.
zmWholePage 3 Show a whole page.
zmPageWidth 4 Show page so that it fits horizontally within the control.
zmStretch 5 Stretch page to fill the control without preserving the aspect
ratio.
The ZoomMode property adjusts the zoom factor automatically when the control is resized, so a specified amount of
document content is visible within the control. The first setting, zmPercentage, is the only one that uses the zoom factor
set by the programmer, with the Zoom property, and does not modify it when the control is resized.
If the programmer assigns a specific zoom factor to the control, with the Zoom property, then the ZoomMode property
is automatically set to zmPercentage.
Note: In thumbnail mode (setting zmThumbnail), the control will fit as many preview pages into the control as possible.
The programmer has no control over the number of thumbnails displayed, but the value is available for reading through
the PreviewPages property.
The following images show the effect of each setting on the control's appearance:
154
155
ZoomMode = zmPageWidth
156
ZoomMode = zmStretch
Data Type
ZoomModeSettings (Enumeration)
Default Value
zmWholePage (3)
See Also
ZoomStep Property
Returns or sets the step for zooming with the mouse.
Syntax
[form!]VSPrinter.ZoomStep[ = value As Integer ]
Remarks
Data Type
Integer
Default Value
25
See Also
157
VSPrinter Methods
AddLink Method
Adds a hyperlink to the document.
Syntax
AddLink(LinkText As String, LinkTarget As String, Formatted As Boolean)
Remarks
LinkText is the text that will be displayed in the document.
LinkTarget is a URL (for example, "http://www.componentone.com") or local reference (for example, "#myTarget") that
defines the link target (destination).
Formatted defines whether the text should be automatically formatted to look like an HTML link (underlined and
rendered in blue).
If the AutoLinkNavigate property is set to true, moving the mouse over hyperlinks will change the mouse pointer into a
hand, and clicking it will either open the link target in a new window or bring the target into view.
If you add links to local references, make sure you add the link target to the document using the AddLinkTarget
method.
Hyperlinks are automatically exported to PDF and HTML.
Note: Internally, hyperlinks are represented as custom tags with the following format: "%PDFLink|<linkTarget>". If the
linkTarget starts with a pound sign "#" then the link is a local reference, otherwise it is a URL or file name. If you want,
you can create links using the StartTag and EndTag methods to add tags using the specified format.
See Also
AddLinkTarget Method
Adds a Target tag (%PDFName|<name>) to the document at the cursor position.
Syntax
AddLinkTarget(TargetText As String, TargetName As String)
Remarks
TargetText is the text that will be displayed in the document.
TargetName is the name of the target which can be reached by clicking on hyperlinks that reference it.
Hyperlinks that point to local references should precede the target name with a pound sign "#". The target name itself
should not include the pound sign. For example:
vp.AddLinkTarget "Home"
GenerateDocumentContent vp ' << your routine
vp.AddLink "Go back home", "#Home", True
Note: Internally, link targets are represented as custom tags with the following format: "%PDFName|<linkTarget>". If
you want, you can create link targets using the StartTag and EndTag methods to add tags using the specified format.
See Also
158
AddTable Method
Renders a table with row headers and special formatting.
Syntax
[form!]VSPrinter.AddTable Format As String, Header As String, Body As String, [ HeaderShade As Variant ], [
BodyShade As Variant ], [ Append As Variant ]
Remarks
The AddTable method is used to render tables. The parameters describe the table format, the contents of a header row,
and the contents of the table body. VSPrinter renders the table, automatically sizing rows and breaking pages when
necessary.
The parameters for the AddTable method are described below:
Format$
This parameter contains formatting information and is not printed. The formatting information describes each column
using a sequence of formatting characters followed by the column width. The information for each column is delimited
by the column separator character (by default a pipe ("|"), but may be modified using the TableSep property).
For example, the following string defines a table with four center-aligned, two-inch wide columns:
s$ = "^+2in|^+2in|^+2in|^+2in"
The following list shows all valid formatting characters and their effect:
Character Effect
< Align column contents to the left
^ Align column contents to the center
> Align column contents to the right
= Justify column contents
+ Align column contents vertically to the center
_ Align column contents vertically to the bottom
* Align column contents according to the TextAlign property
~ Prevent word wrapping on this column
! Draw a vertical border to the right of the column (see also the TableBorder
property)
Column widths may be specified in twips, inches, points, millimeters, centimeters, pixels, or as a percentage of the age
width. If units are not supplied, twips are used. If a width is not supplied, 0.5 inch is used as a default value. For details
Header$
This parameter contains the text to be printed on the first row of the table and after each column or page break (the
header row). The text for each cell in the header row is delimited by the column separator character (by default a pipe
("|"), but may be modified using the TableSep property).
If you are appending to an existing table and would like the header to appear at the breaks but not in the beginning of the
table, set the Append parameter to True.
Body$
This parameter contains the text for the table body. Cells are delimited by column separator characters, and rows are
delimited by row separator characters. By default, cells pare separated by pipes ("|") and rows by semi-colons (";"), but
these characters may be modified using the TableSep property.
159
Instead of supplying the table data as a string, you may create the table based on data from a Variant array. To do this,
use the AddTableArray method.
You may also choose to supply data for individual cells separately. To do this, use the TableCell property.
HeaderShade, BodyShade (optional)
These parameters specify colors to be used for shading the cells in the header and in the body of the table. If omitted or
set to zero, the cells are not shaded. If you want to use black shading, do not use zero or the vbBlack constant. Use a very
dark shade of gray instead (for example, 1 or RGB(1,1,1)).
Append (optional)
Set this parameter to True if you want the Header string to appear at the top of each page, but not in the beginning of the
table. This is useful if you are printing a table in parts, using several calls to the AddTable method, and don't want
headers to be included between table sections.
If you are building a table in deferred mode (using the StartTable and EndTable methods), then setting the Append
parameter to True adds the data to the table being build in memory. The Format and Header parameters are ignored in
this case.
Aligning and indenting tables:
Tables may be aligned to the left, center, or right of the page depending on the setting of the TextAlign property. To
indent a table by a specified amount, use the TableCell property with the tcIndent setting.
The vertical position of the table is determined by the CurrentY property.
Drawing borders around tables:
Tables may have borders drawn around them. To specify the type and appearance of the borders, use the TableBorder,
PenColor, PenWidth, PenStyle, TablePen, TablePenLR, and TablePenTB properties.
You may also draw vertical and horizontal borders next to specific rows and columns using the TableCell property with
the tcRowBorder and tcColBorder settings.
Formatting individual cells:
While measuring and rendering tables, the VSPrinter control fires the BeforeTableCell and AfterTableCell events,
which allows you to change fonts and other formatting parameters while printing the table. This is the traditional method
of applying custom formatting to cells.
A new and better alternative is to use the TableCell property to set the cell format, including font, back and foreground
colors, alignment, and so on. This technique is efficient and easy to use.
You may also use RTF text in table cells. Just set the AutoRTF property to True and enclose the cell contents in curly
brackets (for example, "{Show me \b BOLD}"), but this technique is much slower than the other alternatives.
Populating a table:
Instead of supplying the table data as a string, you may bind the table to a Variant array using the AddTableArray
method, or set the contents of individual cells using the TableCell property with the tcText setting.
See also the Shaded Table (page 50) example.
See Also
AddTableArray Method
Renders a variant array as a table with row headers and special formatting.
Syntax
[form!]VSPrinter.AddTableArray Format As String, Header As String, Body As Variant, [ HeaderShade As Variant ],
[ BodyShade As Variant ], [ Append As Variant ]
160
Remarks
The AddTableArray method is similar to the AddTable method, except the data for the table body comes from a
Variant array instead of being specified by a string.
All parameters are identical to those in the AddTable method, except for the Body parameter, which must be a two-
dimensional array of Variants. The first array dimension contains the rows, and the second dimension contains the
columns.
By default, the first table column (columns 1) is bound to the first array column (column 0) and so on. You may change
this binding using the TableCell property with the tcColSource setting.
For examples of creating tables based on Variant arrays, see the VSPrinter Tutorial - Calendar (page 35) topic and the
Data-based Tables (page 51) example.
See Also
Archive Method
Adds, extracts, or deletes files from a ComponentOne archive file.
Syntax
[form!]VSPrinter.Archive arcFileName As String, FileName As String, Action As ArchiveSettings
Remarks
The Archive method allows you to combine several files into one, optionally compressing the data.
This is especially useful for applications that save documents using the SaveDoc method. You may write custom
information about the document into a data file and add the data file to the archive file created with the SaveDoc method.
To extract information from an archive file, use the ArchiveInfo property.
The parameters for the Archive method are described below:
arcFileName$ Name of the archive file, including its path.
FileName$ Name of the file to be added, deleted, or extracted from the archive.
Action% Action to perform on the archive. Valid settings are listed in the following table.
Valid settings for the Action parameter are:

arcAdd 0 Adds the file FileName to the archive arcFileName,
compressing it. If the archive file does not exist, it is created. If
the file is already present in the archive, it is refreshed.
arcStore 1 Adds the file FileName to the archive arcFileName, without
compressing it. If the archive file does not exist, it is created. If
the file is already present in the archive, it is refreshed.
arcDelete 2 Removes the file FileName from the archive arcFileName.
arcExtract 3 Creates a copy of the file FileName on the disk. The file is
created on the directory specified in the FileName parameter,
or on the archive directory if no path is specified.
Notes:
161
VSPrint 8 archive files are compatible with archive files created by earlier versions of the control and are also
compatible with ComponentOne's VSFlexGrid archive files.
For safety reasons, this method is disabled when the control is hosted on a Web page.
See Also
Clear Method (VSPrinter)

Clears the control, destroying any currently loaded document.
Syntax
[form!]VSPrinter.Clear
Remarks
This is equivalent to using the StartDoc and KillDoc methods in sequence.
See Also
ClientToPage Method (VSPrinter)

Converts mouse coordinates to page coordinates.
Syntax
[form!]VSPrinter.ClientToPage X As Single, Y As Single, [ Page As Variant ]
Remarks
Use the ClientToPage method to convert the coordinates on the MouseDown, MouseMove, and MouseUp events into
page coordinates, in twips.
For example, if the user clicks in the middle of an 8.5x11 page in the preview window, the X and Y parameters in the
MouseDown event would depend on the zoom factor and page position within the control. After converting to page
coordinates, you would have X = 6120 (8.5/2 * 1440) and Y = 7920 (11/2 * 1440).
This may be useful if you want to determine that the user clicked the mouse on a specific page element such as a field on
a form.
The optional parameter Page returns the number of that page that was clicked. If only a single page is being displayed,
the value returned will be the value of the PreviewPage property. If multiple pages are being displayed, the value
returned will be the number of the page that was clicked. (Multiple pages are displayed when the ZoomMode property is
set to zmTwoPages or zmThumbnail).
You can perform the reverse conversion using the PageToClient method.
For example, the following code prints the page coordinates of each click:
Private Sub vp_MouseDown(Button As Integer, Shift As Integer, _
X As Single, Y As Single)
Dim page
vp.ClientToPage X, Y, page
Debug.Print "You clicked on page "; page; " at "; _

X / 1440; " inches from the top and "; _
Y / 1440; " inches from the left."
End Sub
See Also
162
DrawCircle Method (VSPrinter)
Draws a circle, circular wedge, or circular arc.
Syntax
[form!]VSPrinter.DrawCircle CenterX As Variant, CenterY As Variant, Radius As Variant, [ Start As Variant ], [ End
As Variant ]
Remarks
The parameters for the DrawCircle method are described below:
CenterX X coordinate of the center of the circle, arc, or wedge.
CenterY Y coordinate of the center of the circle, arc, or wedge.
Radius Radius of the circle, arc, or wedge.
Start Optional parameter that specifies the beginning position of an arc or wedge, in
radians. If omitted, a circle is drawn.
End Optional parameter that specifies the end position of an arc or wedge, in radians. If
omitted, a circle is drawn.
If the Start and End parameters are not specified, a circle is drawn. If they are specified, an arc or wedge are drawn
depending on the setting of the BrushStyle property. If the BrushStyle is set to bsTransparent, an arc is drawn.
Otherwise, a wedge is drawn (a wedge is just a filled arc.)
The CenterX, CenterY, and Radius parameters may be specified with units (inches, points, twips, cm, mm, or pixels).
The default unit is twips. For details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16)
topic.
The Start and End parameters are measured counter-clockwise, starting from the 3 o'clock position.
See Also
DrawEllipse Method (VSPrinter)

Draws an ellipse, wedge, or arc.
Syntax
[form!]VSPrinter.DrawEllipse X1 As Variant, Y1 As Variant, X2 As Variant, Y2 As Variant, [ Start As Variant ], [ End
As Variant ]
Remarks
The parameters for the DrawEllipse method are described below:
X1, Y1 First corner of the rectangle that encloses the ellipse.
X2, Y2 Second corner of the rectangle that encloses the ellipse.
163
radians. If omitted, an ellipse is drawn.
omitted, an ellipse is drawn.
The CenterX, CenterY, and Radius parameters may be specified with units (inches, points, twips, cm, mm, or pixels).
The default unit is twips. For details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16)
topic.
See Also
DrawLine Method (VSPrinter)

Draws a line segment.
Syntax
[form!]VSPrinter.DrawLine X1 As Variant, Y1 As Variant, [ X2 As Variant ], [ Y2 As Variant ]
Remarks
The DrawLine method draws a line between point (X1, Y1) and (X2, Y2). If (X2, Y2) are omitted, the line is drawn
from the last point used in a call to DrawLine and (X1, Y1).
Lines are drawn with the current pen, defined by the PenColor, PenStyle, and PenWidth properties.
The X1, Y1, X2, and Y2 parameters may be specified with units (inches, points, twips, cm, mm, or pixels). The default
unit is twips. For details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
To draw complex shapes, you may prefer to use the Polygon or PolyLine properties instead.
See Also
DrawPicture Method (VSPrinter)

Draws a picture.
Syntax
[form!]VSPrinter.DrawPicture Picture As Picture, Left As Variant, Top As Variant, [ Width As Variant ], [ Height As
Variant ], [ Align As Variant ], [ Shade As Variant ]
Remarks
The parameters for the DrawPicture method are described below:
Picture Picture to draw. May be a reference to a bitmap, icon, or metafile.
164
Left, Top Position of the top left corner of the picture on the page.
Width, Height Optional parameters that determine the size of the picture on the page. If omitted,
the natural size is used.
Align How to scale and align the picture within the given rectangle. If provided, must
be a value from the PictureAlignSettings enumeration. The default value is
vppaStretch, which stretches the picture to fill the rectangle. For details, see the
example below.
Shade Specifies whether the box will be outlined with the current pen and shaded with
the current brush. Optional, defaults to False.
All measurement parameters may be specified with units (inches, points, twips, cm, mm, or pixels). The default unit is
twips. For details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
The Width and Height parameters may also be specified as percentages of the picture's natural size.
For example:
' draw a picture, scale to half the natural size
vp.DrawPicture Picture1, "2in", "2in", "50%", "50%"
' draw a picture, natural size

' draw a picture, scale to twice the natural size

The Align parameter allows you to determine how the picture will be scaled and aligned within the given rectangle. Valid
settings are:

vppaLeftTop 0 Align to the left top corner of the rectangle.
vppaCenterTop 1 Align to the center and to the top of the rectangle.
vppaRightTop 2 Align the right top corner of the rectangle.
vppaLeftBottom 3 Align to the left bottom corner of the rectangle.
vppaCenterBottom 4 Align to the center and to the bottom of the rectangle.
vppaRightBottom 5 Align to the right bottom corner of the rectangle.
vppaLeftMiddle 6 Align to the left and to the middle of the rectangle.
vppaCenterMiddle 7 Align to the center and to the middle of the rectangle.
vppaRightMiddle 8 Align to the right and to the middle of the rectangle.
vppaClip 9 Align to the center and to the middle of the rectangle (same
as vppaCenterMiddle)
vppaZoom 10 Fit rectangle while preserving aspect ratio.
vppaStretch 11 Fill rectangle, stretching the picture as needed.
vppaTile 12 Fill rectangle by tiling copies of the picture (useful for
rendering backgrounds).
165
None of the settings allow the picture to overflow the rendering rectangle. The first ten settings (vppaLeftTop through
vppaClip) will clip the picture if it is too large to fit the rectangle, and will leave parts of the rectangle empty if the
picture is too small.
The vppaZoom setting will stretch (or shrink) the picture so that one of its dimensions matches the rendering rectangle,
and the other dimension will be calculated so as to preserve the picture's aspect ratio. This setting is useful when
rendering pictures that should not be distorted in a rectangle of fixed size.
The picture below shows the effect of each setting:
See Also
166
DrawRectangle Method (VSPrinter)
Draws a rectangle.
Syntax
[form!]VSPrinter.DrawRectangle X1 As Variant, Y1 As Variant, X2 As Variant, Y2 As Variant, [ Radius1 As Variant
], [ Radius2 As Variant ]
Remarks
The parameters for the DrawRectangle method are described below:
X1, Y1 First corner of the rectangle.
X2, Y2 Second corner of the rectangle.
Radius1 Optional parameter that specifies the radius of a rounded rectangle's corner, in the
horizontal direction.
Radius2 Optional parameter that specifies the radius of a rounded rectangle's corner, in the
vertical direction.
If the Radius1 and Radius2 parameters are omitted, a rectangle is drawn.
All measurements may be specified with units (inches, points, twips, cm, mm, or pixels). The default unit is twips. For
details on using unit-aware measurements, see the Using Unit-Aware Properties (page 16) topic.
See Also
EndDoc Method
Ends the current document (created with the StartDoc method).
Syntax
[form!]VSPrinter.EndDoc
Remarks
The EndDoc method finishes the current document. If the Preview property is set to True, the document remains on the
control and can be previewed, saved or printed. If Preview is set to False, the document is sent to the printer.
To cancel the current document, use the KillDoc method instead of EndDoc. KillDoc will clear the control's contents
and cancel the printing job if it has started.
See Also
EndOverlay Method
Closes a page that was opened with the StartOverlay method.
Syntax
[form!]VSPrinter.EndOverlay
167
Remarks
The StartOverlay and EndOverlay methods allow you to add elements to a document after it has been created in
preview mode.
This allows you to create templates with blank fields, save them to disk, load and fill them out later. It also allows you to
avoid lengthy two-pass operations. With the StartOverlay and EndOverlay methods, you can create the document,
save information you need (such as page numbers, counts, and subtotals), then go back and place the information in the
appropriate places.
Each page in the document may have a single overlay page. To create the overlay page, you issue the StartOverlay
method with the desired page as a parameter, then add all text and graphics elements that you want, and finalize the
overlay by calling the EndOverlay method.
When you call StartOverlay, you have the option of preserving or deleting the contents of the previous overlay for the
page.
See also the Page n of m (page 49) example.
See Also
EndTable Method
Renders table defined since call to StartTable.
Syntax
[form!]VSPrinter.EndTable
Remarks
If you create a table with the AddTable or AddTableArray methods, the table is rendered immediately. This is a good
approach for creating simple tables, but it does not allow you to perform complex formatting on the table.
On the other hand, if you enclose the calls to AddTable or AddTableArray between calls to StartTable and
EndTable, the table is not rendered until the call to EndTable is made. This allows you to perform complex formatting
on the table using the TableCell property.
Here is some pseudo-code that shows how the second approach works:
' start the table
vp.StartTable
' set basic format and some data

vp.AddTable Format, Header, Body
' make top left cell bold and red

vp.TableCell(tcFontBold, 1, 1) = True
vp.TableCell(tcBackColor, 1, 1) = vbRed

vp.EndTable
See Also
EndTag Method
Ends the definition of a document tag started with StartTag.
Syntax
[form!]VSPrinter.EndTag
168
Remarks
For details and an example, see the StartTag method.
See Also
GetMargins Method
Returns the printable area, excluding margins, in the X1, Y1, X2, and Y2 properties.
Syntax
[form!]VSPrinter.GetMargins
Remarks
This method provides a convenient way to determine the rectangle defined by the current page size, margins, and current
column.
For example, to draw a line across the page (from margin to margin), you could use code such as:
vp.X1 = vp.MarginLeft
vp.X2 = vp.PageWidth - vp.MarginRight
vp.DrawLine vp.X1, y, vp.X2, y
Or you could use the GetMargins method and write:

vp.GetMargins
vp.DrawLine vp.X1, y, vp.X2, y
The second version is more efficient and concise, and it also works when the Columns property is set to a value greater
than one.
See Also
KillDoc Method
Cancels and deletes the current document.
Syntax
[form!]VSPrinter.KillDoc
Remarks
This method cancels a document that was started with the StartDoc method and resets the control.
To delete an existing preview document and reset the control, use the SetPageExtent method.
See Also
LoadDoc Method (VSPrinter)

Loads a document from disk.
Syntax
[form!]VSPrinter.LoadDoc FileName As String, [ Append As Variant ]
Remarks
The SaveDoc and LoadDoc methods are useful for loading documents that take a long time to generate and do not
change often, or to distribute documents that you create so that others can view and print them.
169
The parameters for the LoadDoc method are described below:
FileName Name of the file to be loaded. The file must exist and must have been saved with
the SaveDoc method, or an error will occur.
Append Optional parameter that specifies whether the document being loaded should be
appended to the current document or whether it should replace the current
document. If omitted, the document being loaded replaces the existing document.
While the document is being loaded, the VSPrinter control fires the LoadingDoc event before each page is loaded. This
allows you to provide user feedback while the document is loading. You may also cancel the loading operation.
See Also
MovePages Method
Moves a group of pages to the start or to the end of the document.
Syntax
[form!]VSPrinter.MovePages First As Long, Last As Long, bToFront As Boolean
Remarks
This method is useful mainly for documents that have a table of contents or similar elements that can only be created
after the body of the document is done, but which you would like to insert at the start of the document.
For example, the code below creates a long document, followed by a table of contents. It then moves the table of
contents to the beginning of the document:
With vp
.StartDoc
' create document body

Dim i%, s$
s = "This is a very long paragraph. "
s = s & s & s & s & s & s
s = s & s & s
vp.Paragraph = "** Document Body"
For i = 1 To 200
.Paragraph = s
Next
' create table of contents

vp.NewPage
Dim fp%
fp = vp.PageCount
vp.Paragraph = "** Table Of Contents"
For i = 1 To 100
vp = "Item " & i & "...... Page n"
Next
vp.EndDoc
' move TOC to doc start

vp.MovePages fp, vp.PageCount, True
End With
See Also
170
NewColumn Method
Skips to the next column.
Syntax
[form!]VSPrinter.NewColumn
See Also
NewPage Method
Skips to the next page.
Syntax
[form!]VSPrinter.NewPage
See Also
PageToClient Method (VSPrinter)

Converts page coordinates to mouse coordinates.
Syntax
[form!]VSPrinter.PageToClient X As Single, Y As Single
Remarks
Use the PageToClient method to convert page coordinates into mouse coordinates that reflect the current zoom factor
and scroll position.
This method is symmetrical to the ClientToPage method.
See Also
PrintDialog Method
Displays a printer selection or page setup dialog.
Syntax
[form!]VSPrinter.PrintDialog(DialogType As PrintDialogSettings)
Remarks
This method displays a standard Print, Printer Setup, or Page Setup dialog, depending on the setting of the DialogType
parameter.
Valid settings for the DialogType parameter are:

pdPrinterSetup 0 Displays a Printer Setup dialog. This dialog is normally used
before the document is created, to select the target printer,
paper size, and orientation.
pdPageSetup 1 Displays a Page Setup dialog. This dialog is normally used
before the document is created, to select margins, paper size,
171
and orientation.
pdPrint 2 Displays a Print dialog. This dialog is used after the document
is ready, to select the range of pages to print and number of
copies. (If the document is empty, this parameter displays a
Printer Setup dialog instead).
pdGetFromPage 100 Retrieves the first page in the range selected by the user from
the last Print dialog (this setting does not display a dialog).
pdGetToPage 101 Retrieves the last page in the range selected by the user from
the last Print dialog (this setting does not display a dialog).
pdGetToFile 102 Retrieves a Boolean value that indicates whether the user
selected the Print To File button on the last Print dialog (this
setting does not display a dialog).
The picture below shows the Print, Printer Setup, and Page Setup dialogs. Note that these dialogs are provided by the
operating system and their appearance may vary.
When used with the settings that display dialogs, PrintDialog returns True if the user clicked OK to accept the changes
and False if the user clicked Cancel to dismiss the dialog.
Changes made by the user through the dialogs are reflected in the control (for example, device, paper size, orientation,
margins, copies, and so on). If the DefaultDevice property is set to True, the device also becomes the default for other
Windows applications. However, these changes are not automatically reflected in the current preview document. The
document retains the original formatting and you need to regenerate it to apply the changes made by the user.
If the document is long and generating it is time-consuming, you may want to cache the values of the Device, PaperSize,
Orientation, and Margin properties and regenerate the document only if one of them was changed.
The code below shows typical uses of the PrintDialog method:
172
' ** Print Dialog: select printer, pages, copies
If vp.PageCount = 0 Then
MsgBox "No document: using Printer Setup Dialog."
End If
If vp.PrintDialog(pdPrint) Then
MsgBox "You chose to print " & vp.Copies & _
" copies of pages " & vp.PrintDialog(pdGetFromPage) & _
" through " & vp.PrintDialog(pdGetToPage) & _
" (ToFile is " & vp.PrintDialog(pdGetToFile) & ")." & vbCrLf
End If
' ** Page Setup Dialog: select margins, paper size, orientation

If vp.PrintDialog(pdPageSetup) Then
MsgBox "Device is " & vp.Device & ". " & _
"Paper size is " & vp.PaperSize & ". " & _
"Orientation is " & vp.Orientation & ". " & _
"Margins are " & vp.MarginLeft & ", " & vp.MarginTop & ", " & _
vp.MarginRight & ", and " & vp.MarginBottom & "." & vbCrLf
End If
' ** Printer Setup Dialog : select printer, paper size, orientation

If vp.PrintDialog(pdPrinterSetup) Then
MsgBox "Device is " & vp.Device & ". " & _
"Paper size is " & vp.PaperSize & ". " & _
"Orientation is " & vp.Orientation & "."
End If
See Also
PrintDoc Method (VSPrinter)

Prints the current document (being previewed) on the printer.
Syntax
[form!]VSPrinter.PrintDoc [ Choose As Variant ], [ FromPage As Variant ], [ ToPage As Variant ]
Remarks
The parameters for the PrintDoc method are described below:
Choose If set to True, the control displays a Print Setup dialog before printing the
document. Optional, defaults to False.
FromPage Selects the first page to be printed. May also be set to a string containing a
complex page range (for example, "1-5, 7, 9-11"). Optional, defaults to one.
ToPage Selects the last page to be printed. Optional, defaults to PageCount.
Note: If you use the Choose parameter to display a dialog box and the user changes the paper size, the document may
look distorted when printed. The alternative is to call the PrintDialog method yourself, and regenerate the document in
response to new user settings.
See Also
PrintFile Method
Prints a file.
173
Syntax
[form!]VSPrinter.PrintFile FileName As String
Remarks
This method allows you to print a file quickly. You don't have to call the StartDoc and EndDoc methods to use
PrintFile.
If the AutoRTF property is set to True, the control will automatically detect RTF files and render them appropriately.
See Also
SaveDoc Method (VSPrinter)

Saves the current document to disk.
Syntax
[form!]VSPrinter.SaveDoc FileName As String, [ Compress As Variant ], [ FromPage As Variant ], [ ToPage As
Variant ]
Remarks
The SaveDoc and LoadDoc methods are useful for loading documents that take a long time to generate and do not
change often, or to distribute documents that you create so that others can view and print them.
The parameters for the SaveDoc method are described below:
FileName Name of the file to be saved.
Compress Specifies whether the file should be saved in compressed form. Compression
typically reduces file size to about 25% of the uncompressed size, but saving
takes about twice as long. Optional, defaults to True.
FromPage First page to save. Optional, defaults to one.
ToPage Last page to save. Optional, defaults to PageCount.
While the document is being saved, the VSPrinter control fires the SavingDoc event before each page is saved. This
allows you to provide user feedback while the document is being saved. You may also cancel the save operation.
See Also
ScrollIntoView Method
Scrolls the control so the specified rectangle or point is visible.
Syntax
[form!]VSPrinter.ScrollIntoView Left As Variant, Top As Variant, [ Right As Variant ], [ Bottom As Variant ]
Remarks
Use this method when you want to make sure a specific part of a document is visible to the user.
For example, the code below looks for a string in a document and shows it to the user:
' ** search for the text:
' returns page and sets (X1,Y1,X2,Y2) to bounding box
Dim pg&
pg = vp.FindText("Hello")
174
' ** if the text was found, show it to the user
If pg > 0 Then
vp.PreviewPage = pg
vp.ScrollIntoView vp.X1 - 200, vp.Y1 - 200, vp.X2 + 200, vp.Y2 + 200
End If
See Also
StartDoc Method
Starts a new document.
Syntax
[form!]VSPrinter.StartDoc
See Also
StartOverlay Method
Reopens an existing preview page for additional output.
Syntax
[form!]VSPrinter.StartOverlay Page As Integer, [ Preserve As Variant ]
Remarks
The StartOverlay and EndOverlay methods allow you to add elements to a document after it has been created in
preview mode.
The parameters for the StartOverlay method are described below:
Page Page in existing preview document to which you want to add text or graphical
elements.
Preserve Boolean value that specifies whether previous overlay contents should be
preserved or deleted. This parameter is optional and defaults to False, which
causes previous contents to be deleted.
The overlay mechanism allows you to create templates with blank fields, save them to disk, load and fill them out later.
It also allows you to avoid lengthy two-pass operations. With the StartOverlay and EndOverlay methods, you can
create the document, save information you need (such as page numbers, counts, and subtotals), then go back and place
the information in the appropriate places.
Each page in the document may have a single overlay page, which you may add to or replace when you call
StartOverlay. To create the overlay page, issue the StartOverlay method with the desired page as a parameter, then
add all text and graphics elements that you want, and finalize the overlay by calling the EndOverlay method.
By setting the Preserve parameter to True, you can create overlays in several passes, adding extra information on each
pass.
See also the Page n of m (page 49) example.
See Also
175
StartTable Method
Defers table rendering until call to EndTable.
Syntax
[form!]VSPrinter.StartTable
Remarks
If you create a table with the AddTable or AddTableArray methods, the table is rendered immediately. This is a good
approach for creating simple tables, but it does not allow you to perform complex formatting on the table.
On the other hand, if you enclose the calls to AddTable or AddTableArray between calls to StartTable and
EndTable, the table is not rendered until the call to EndTable is made. This allows you to perform complex formatting
on the table using the TableCell property.
Here is some pseudo-code that shows how the second approach works:
' start the table
vp.StartTable
' set basic format and some data

vp.AddTable Format, Header, Body
' make top left cell bold and red

vp.TableCell(tcFontBold, 1, 1) = True
vp.TableCell(tcBackColor, 1, 1) = vbRed

vp.EndTable
See Also
StartTag Method
Starts the definition of a document tag (for later use with the FindTag and RetrieveTag methods).
Syntax
[form!]VSPrinter.StartTag Text As String, [ Left As Variant ], [ Top As Variant ], [ Right As Variant ], [ Bottom As
Variant ]
Remarks
used for a number of things, including document annotation, pop-up notes, hyperlinks, and more. For details and
examples about creating and using tags, see the Build an Index (page 57) sample.
The parameters for the StartTag method are described below:
Text As String
This parameter contains the tag's text. You can later look for a tag based on this value using the FindTag property, or
retrieve this value based on the tag's position using the RetrieveTag property.
Left, Top, Right, Bottom As Variant (optional)
These parameters are optional. If supplied, they define a rectangle on the page that is associated with the tag. If omitted,
the tag will include all text and graphical elements up to the next call to the EndTag method.
For example, the following code creates several tags, and uses their text as a tooltip when the mouse moves over an
element on the document:
' ** create document with tags
176
Sub CreateDoc()
With vp
.StartDoc
' ** create tags based on document elements

.StartTag "This is a picture of a horse."
.DrawPicture picHorse, "2in", "3in", "2in", "2in"
.EndTag
.StartTag "These are some text and pictures."

.DrawPicture picHorse, "2in", "3in", "2in", "2in"
.Paragraph = "Horse"
.DrawPicture picDog, "4in", "3in", "2in", "2in"
.Paragraph = "Dog"
.DrawPicture picCat, "4in", "3in", "2in", "2in"
.Paragraph = "Cat"
.EndTag
' ** create a tag based on a region

.StartTag "This is the rectangle from (1in, 1in)-(5in,2in)", _
"1in", "1in", "5in", "2in"
.EndTag
.EndDoc
End With
End Sub
' ** show tags as tooltips

Private Sub vp_MouseMove(Button As Integer, Shift As Integer, _
x As Single, y As Single)
If Button = 0 Then
vp.ToolTipText = vp.RetrieveTag(x, y, , , , True)
End If
End Sub
See Also
TextBox Method
Draws text within a rectangle.
Syntax
[form!]VSPrinter.TextBox Text As String, X As Variant, Y As Variant, Width As Variant, Height As Variant, [ Wrap As
Variant ], [ Calc As Variant ], [ Shade As Variant ]
Remarks
The parameters for the TextBox method are described below:
Text Text to be drawn in the text box. It may be plain text or, if the AutoRTF
property is set to True, it may contain RTF text enclosed in curly braces
("{}").
X, Y, Coordinates of the upper left corner of the box. You may specify the units for
these parameters. The default unit is twips.
Width The width of the text box, in twips or explicit units.
Height The height of the text box, in twips or explicit units. If this parameter is set to
zero, the height is calculated automatically so the text fits within the box.
Wrap Specifies whether text should be allowed to wrap within the box. Optional,
defaults to True.
177
Calc Specifies whether the text box should only be calculated, and not rendered.
Optional, defaults to False. If you set this parameter to True, no text is drawn
and the dimensions of the text box are returned in the TextWid and TextHei
properties. This is useful if you want to determine whether a text box will fit
on the current page.
Shade Specifies whether the text box will be outlined with the current pen and
shaded with the current brush. Optional, defaults to False.
Several properties affect the way text is drawn within the text boxes. The main ones are Font, TextColor, TextAlign,
TextAngle, SpaceBefore, SpaceAfter, IndentLeft, IndentRight, and LineSpacing.
You can use the TextBox method to build sophisticated reports with total control over text positioning and page breaks,
or forms with arbitrary field positioning.
See Also
VSPrinter Events
AfterFooter Event
Fired after printing the footer for each page to allow font changes.
Syntax
Private Sub VSPrinter_AfterFooter()
Remarks
If the Footer property is set to a non-empty string, the VSPrinter control fires the BeforeFooter and the AfterFooter
events before and after printing the footer on each page.
These events allow you to customize margins, fonts, and other characteristics for the footers. Make the changes during
the BeforeFooter event and restore the control state during the AfterFooter event.
See Also
AfterHeader Event
Fired after printing the header for each page to allow font changes.
Syntax
Private Sub VSPrinter_AfterHeader()
Remarks
If the Header property is set to a non-empty string, the VSPrinter control fires the BeforeHeader and the AfterHeader
events before and after printing the header on each page.
the BeforeHeader event and restore the control state during the AfterHeader event.
See Also
178
AfterTableCell Event
Fired after a table cell is rendered, to allow custom painting.
Syntax
Private Sub VSPrinter_AfterTableCell(ByVal Row As Long, ByVal Col As Long, ByVal Left As Double, ByVal Top
As Double, ByVal Right As Double, ByVal Bottom As Double, Text As String, KeepFiring As Boolean)
Remarks
The AfterTableCell event is fired while a table is rendered. Its parameters are described below:
Row, Col As Long
These parameters identify the cell that was printed. The coordinates are 1-based, except for header rows which have
index zero. For example, cell (0,1) is the first cell on the header row. Cell(1,1) is the first cell in the table body.
Left, Top, Right, Bottom As Double
These parameters specify the cell rectangle on the page, in twips.
Text As String
This parameter contains the string that was printed on the cell.
KeepFiring As Boolean
This parameter should be set to True by the event handler. The default value, False, indicates that the event is not needed
and thus should no longer be fired. Not firing the events makes table rendering more efficient.
For example, the code below draws a cross over cells that contain strings longer than 100 characters:
Private Sub vp_AfterTableCell(ByVal row As Long, ByVal col As Long, _
ByVal Left As Double, ByVal Top As Double, _
ByVal Right As Double, ByVal Bottom As Double, _
Text As String, KeepFiring As Boolean)
' we want this event to keep firing

KeepFiring = True
' draw cross if we have to

If Len(Text) > 100 Then
vp.DrawLine Left, Top, Right, Bottom
vp.DrawLine Left, Bottom, Right, Top
End If
End Sub
See Also
AfterUserPage Event
Fired after switching preview pages in response to a user request.
Syntax
Private Sub VSPrinter_AfterUserPage()
Remarks
The page may be switched using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
of the NavBar and Navigation properties.
See Also
179
AfterUserScroll Event
Fired after scrolling in response to a user request.
Syntax
Private Sub VSPrinter_AfterUserScroll()
Remarks
The page may be scrolled using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
See Also
AfterUserZoom Event
Fired after Zooming in or out in response to a user request.
Syntax
Private Sub VSPrinter_AfterUserZoom()
Remarks
The page may be zoomed using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
See Also
BeforeFooter Event
Fired before printing the footer for each page to allow font changes.
Syntax
Private Sub VSPrinter_BeforeFooter()
Remarks
If the Footer property is set to a non-empty string, the VSPrinter control fires the BeforeFooter and the AfterFooter
events before and after printing the footer on each page.
the BeforeFooter event and restore the control state during the AfterFooter event.
See Also
BeforeHeader Event
Fired before printing the header for each page to allow font changes.
Syntax
Private Sub VSPrinter_BeforeHeader()
Remarks
If the Header property is set to a non-empty string, the VSPrinter control fires the BeforeHeader and the AfterHeader
events before and after printing the header on each page.
180
the BeforeHeader event and restore the control state during the AfterHeader event.
See Also
BeforeTableCell Event
Fired before a table cell is rendered, to allow custom formatting.
Syntax
Private Sub VSPrinter_BeforeTableCell( ByVal Row As Long, ByVal Col As Long, Text As String, KeepFiring As
Boolean)
Remarks
The BeforeTableCell event is fired while a table is rendered, either to measure or to render each cell. Its parameters are
described below:
Row, Col As Long
These parameters identify the cell that was printed. The coordinates are 1-based, except for header rows which have
index zero. For example, cell (0,1) is the first cell on the header row. Cell(1,1) is the first cell in the table body.
Text As String
This parameter contains the string that was printed on the cell.
KeepFiring As Boolean
This parameter should be set to True by the event handler. The default value, False, indicates that the event is not needed
and thus should no longer be fired. Not firing the events makes table rendering more efficient.
This event may be useful if you want to change the format of certain cells based on their contents. Note, however, that
you may accomplish the same task using the TableCell property.
Also, note that this event gets called in two situations: when measuring a cell and when rendering it. This is needed so
that changed in the cell format are taken into account while calculating the size of a cell. If you need to determine
whether the cell is about to be measured or rendered, check the value of the Measuring property.
For example, the code below makes cells with strings longer than 100 characters bold:
Private Sub vp_BeforeTableCell(ByVal row As Long, ByVal col As Long, _
Text As String, KeepFiring As Boolean)
' we want this event to keep firing
KeepFiring = True
' make long text bold

vp.FontBold = ( Len(Text) > 100)
End Sub
See Also
BeforeUserPage Event
Fired before switching preview pages in response to a user request.
Syntax
Private Sub VSPrinter_BeforeUserPage(NewPage As Integer)
Remarks
The page may be switched using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
181
You may change the value of the NewPage parameter to switch to a specific page. If you set NewPage to
PreviewPage, the switch is canceled.
See Also
BeforeUserScroll Event
Fired before scrolling in response to a user request.
Syntax
Private Sub VSPrinter_BeforeUserScroll(Cancel As Boolean)
Remarks
The page may be scrolled using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
You may set the Cancel parameter to True to prevent the user from scrolling the page.
See Also
BeforeUserZoom Event
Fired before Zooming in or out in response to a user request.
Syntax
Private Sub VSPrinter_BeforeUserZoom(NewZoom As Integer)
Remarks
The page may be zoomed using the built-in navigation bar, mouse, mouse wheel, or keyboard, depending on the setting
You may change the value of the NewZoom parameter to zoom to a specific level. If you set NewZoom to the value of the
Zoom property, the zooming is canceled.
See Also
EndDoc Event
Fired after a document is successfully printed.
Syntax
Private Sub VSPrinter_EndDoc()
See Also
EndPage Event
Fired after each page is complete.
Syntax
Private Sub VSPrinter_EndPage()
Remarks
182
You can trap this event to print custom headers and footers or to add text and graphics that will overlay the contents of
the page.
To add text and graphics that should be rendered behind the contents of the page (such as a watermark) use the NewPage
event instead.
See Also
Error Event
Fired when an error is detected (a code is returned in the Error property).
Syntax
Private Sub VSPrinter_Error()
Remarks
This event is fired when the VSPrinter control detects a non-fatal error. The error code may be retrieved by reading the
Error property. For a list of non-fatal errors, see the Error property.
This event is not fired when a fatal error occurs. To trap fatal errors, use the standard Visual Basic error handling
mechanisms (On Error, and so on). Fatal errors include assigning an invalid value to a property, using invalid indices,
running out of memory, or trying to open a file that doesn't exist.
You may use the ErrorDescription property to retrieve a description of an error based on it's code. For example:
Private Sub vp_Error()
Debug.Print vp.ErrorDescription(vp.Error)
End Sub
See Also
LayoutThumbnails Event
Fired when the thumbnail preview is about to change to allow customization of the preview layout.
Syntax
Private Sub VSPrinter_LayoutThumbnails( ByVal PagesX As Integer)
Remarks
The parameters for the LayoutThumbnails event are described below:
PagesX The number of the pages containing the thumbnails.
See Also
LoadingDoc Event
Fired while loading documents from disk, once after each page is loaded.
Syntax
Private Sub VSPrinter_LoadingDoc( ByVal Page As Integer, ByVal Of As Integer, Cancel As Boolean)
183
Remarks
The parameters for the LoadingDoc event are described below:
Page The number of the page being loaded.
Of The total number of pages to be loaded.
Cancel Set this parameter to True if you wish to cancel the loading operation.
If you want to allow the user to cancel the loading operation, you should include a call to DoEvents in this event handler.
This will allow your application to process user actions while the document is loading (such as clicking a Cancel button
or pressing the ESC key).
For example:
Private Sub vp_LoadingDoc(ByVal Page As Integer, _
ByVal Of As Integer, Cancel As Boolean)
' provide user feedback

Debug.Print "Loading Page "; Page; " of "; Of
' detect user actions

DoEvents
Cancel = bGlobalCancelFlag
End Sub
See Also
MouseLink Event
Fired when the user clicks or moves the mouse over a hyperlink (see AutoLinkNavigate property).
Syntax
Event MouseLink(Link As String, Clicked As Boolean, Cancel As Integer)
Remarks
Event parameters:
Link String containing the link target (for example, "http://componentone.com").
Clicked True if the user clicked the link, False if he just moved the mouse over it.
Cancel Set to True to prevent navigation to the link or changing the mouse cursor to
show a hand.
See Also
NewColumn Event
Fired after each column and page break.
184
Syntax
Private Sub VSPrinter_NewColumn()
See Also
NewLine Event
Fired after each line break.
Syntax
Private Sub VSPrinter_NewLine()
See Also
NewPage Event
Fired after each page is created.
Syntax
Private Sub VSPrinter_NewPage()
Remarks
You can trap this event to print custom headers and footers or to add text and graphics that will overlay the contents of
the page.
When the NewPage event is fired, the page is still blank. To add text and graphics that should be rendered on top of the
page contents, use the EndPage event instead.
See Also
ReadyStateChange Event
Fired after the state of the control changes.
Syntax
Private Sub VSPrinter_ReadyStateChange( ByVal ReadyState As Long)
Remarks
For details and an example, see the ReadyState property.
See Also
ResetDC Event
Fired after a page is ejected and before the next page is started.
Syntax
Private Sub VSPrinter_ResetDC()
Remarks
This event is supplied to enable API calls to modify the VSPrinter's hDC.
185
Note: You should only use this property if you are familiar with the Windows GDI calls. In particular, you should
restore the hDC to its original state when you are done using it. If you run into problems using this property, our
technical support staff probably won't be able to help you.
See Also
SavingDoc Event
Fired while saving documents to disk, once after each page is saved.
Syntax
Private Sub VSPrinter_SavingDoc( ByVal Page As Integer, ByVal Of As Integer, Cancel As Boolean)
Remarks
The parameters for the SavingDoc event are described below:
Page The number of the page being saved.
Of The total number of pages to be saved.
Cancel Set this parameter to True if you wish to cancel the save operation.
See Also
StartDoc Event
Fired after a new document is created.
Syntax
Private Sub VSPrinter_StartDoc()
See Also
VSDraw Control
The VSDraw control lets you create detailed, scaleable, resolution-independent drawings. The drawings can be shown
on your forms, printed, save to disk or copied to the Windows clipboard, where they become available for pasting into
other Windows applications such as Microsoft Word.
The coordinate system used to create and display the drawing is determined by the programmer using the ScaleWidth,
ScaleHeight, ScaleLeft, and ScaleTop properties (similar to the VB's PictureBox control). These properties may be
modified after the drawing has been created, and the changes will be reflected on the display.
The scaling is used for all drawing and measurements, including font height. For example, if the ScaleHeight property is
set to 1000 and the FontSize property is set to 100, then the font height corresponds to 1/10th of the control height.
After the drawing is created, you can change the drawing extents to provide distortion and zoom. Use the VSDraw
control to create custom maps, charts, diagrams or whatever graphics you need.
186
The VSDraw control is based on Windows metafile technology, which has limited support for text manipulation. This
makes it less than ideal for text-intensive applications. If you need to handle a lot of text, use the VSPrinter control
instead.
Note: Before you can use a VSDraw control in your application, you must add the VSDraw8.ocx file to your project.
Please refer to the VB documentation for details on adding controls to your projects.
To distribute applications you create with the VSDraw control, you must install and register it on the user's computer.
The Setup Wizard provided with Visual Basic provides tools to help you do that. Please refer to the Visual Basic manual
for details.
The VSDraw control provides the following properties, events and methods:
All of the properties, events and methods for the VSDraw control are listed in the following tables. Properties, events
and methods that apply only to this control, or that require special consideration when used with it, are marked with an
asterisk (*). These are documented in later sections. For documentation on the remaining properties, see the Visual Basic
documentation.
Properties
*AccessibleDescription Gets or sets the description of the control used by accessibility
*AccessibleName Gets or sets the name of the control used by accessibility
*AccessibleRole Gets or sets the role of the control used by accessibility client
applications.
*AccessibleValue Gets or sets the value of the control used by accessibility
*Action Executes actions such as clear, show, and print.
*BackStyle Returns or sets whether text is transparent or opaque.
*BrushColor Returns or sets the brush color.
*BrushStyle Returns or sets the brush style.
*Draw Draws an object within the rectangle defined by the X1, Y1,
*EmptyColor Returns or sets the color of the area around the preview page.
Enabled See the Visual Basic documentation.
Font See the Visual Basic documentation.
hWnd See the Visual Basic documentation.
*KeepTextAspect Returns or sets whether text should keep its aspect ratio when
the drawing is resized.
*LargeChangeHorz Returns or sets the amount of change to the ScrollLeft
property when the user clicks the scroll bar area.
*LargeChangeVert Returns or sets the amount of change to the ScrollTop
187
*LineSpacing Returns or sets the line spacing as a percentage (for example,
100% is single spacing, 200% is double spacing).
MouseIcon See the Visual Basic documentation.
MousePointer See the Visual Basic documentation.
*MouseScroll Returns or sets whether contents may be scrolled by dragging
the VSDraw's client area.
*PageHeight Returns or sets the physical height of the drawing, in twips.
*PageWidth Returns or sets the physical width of the drawing, in twips.
*PenColor Returns or sets the pen color.
*PenStyle Returns or sets the pen style.
*PenWidth Returns or sets the pen width, in logical units.
*Picture Returns a snapshot of the current drawing.
*Polygon Draws a polygon defined by a string of X,Y coordinates.
*Polyline Draws a line defined by a string of X,Y coordinates.
*ProportionalBars Returns or sets whether the scrollbar thumbs should be
proportional to the size of the visible area.
*ScaleHeight Returns or sets the number of logical units for the vertical
dimension of the drawing.
*ScaleLeft Returns or sets the horizontal coordinate for the left edge of
the drawing.
*ScaleTop Returns or sets the vertical coordinate for the top edge of the
drawing.
*ScaleWidth Returns or sets the number of logical units for the horizontal
dimension of the drawing.
*ScrollLeft Returns or sets the left coordinate of the visible area, in twips.
*ScrollTop Returns or sets the top coordinate of the visible area, in twips.
*SmallChangeHorz Returns or sets the amount of change to the ScrollLeft
property when the user clicks the scroll arrow.
*SmallChangeVert Returns or sets the amount of change to the ScrollTop
*Text Prints a string starting at the point defined by the X1, Y1
properties.
*TextAlign Returns or sets the text alignment.
*TextAngle Returns or sets the text angle, in tenths of degrees.
*TextColor Returns or sets the text color.
*TextHeight Returns the height of a string in scale units.
*TextWidth Returns the width of a string in scale units.
*Track Returns or sets whether scrolling occurs as the user drags the
scroll thumb.
188
*X1 Returns or sets the left coordinate of the rectangle used with
the Draw property.
*X2 Returns or sets the right coordinate of the rectangle used with
the Draw property.
*Y1 Returns or sets the top coordinate of the rectangle used with
the Draw property.
*Y2 Returns or sets the bottom coordinate of the rectangle used
with the Draw property.
*Zoom Returns or sets the preview scale: set to a percentage, or zero
to fill the control.
*ZoomMode Sets or returns the zoom mode (explicit percentage or one of
the automatic settings).
Methods
*Clear Resets the control and discards its contents.
*ClientToPage Converts mouse coordinates to page coordinates.
*Copy Updates the drawing and copies it to the clipboard.
*DrawCircle Draws a circle, circular wedge, or circular arc.
*DrawEllipse Draws an ellipse, wedge, or arc.
*DrawLine Draws a line segment.
*DrawPicture Draws a bitmap or an icon.
*DrawRectangle Draws a rectangle.
*LoadDoc Loads a VSDraw document (metafile) from disk.
*PageToClient Converts page coordinates to mouse coordinates.
*PrintDoc Updates the drawing and copies it to the printer.
*SaveDoc Saves a VSDraw document (metafile) to disk.
*SetPageExtent Sets the PageWidth and PageHeight properties.
*Show Updates the drawing and shows it on the screen.
Events
KeyDown See the Visual Basic documentation.
KeyPress See the Visual Basic documentation.
KeyUp See the Visual Basic documentation.
189
*Scroll Fired after the control scrolls its contents.
VSDraw Properties
AccessibleDescription Property (VSDraw)

Syntax
Property AccessibleDescription As String
Data Type
String
See Also
VSDraw Control (page 186)
AccessibleName Property (VSDraw)

Syntax
Property AccessibleName As String
Data Type
String
See Also
AccessibleRole Property (VSDraw)

Syntax
Property AccessibleRole As Variant
Data Type
Variant
See Also
AccessibleValue Property (VSDraw)

Syntax
Property AccessibleValue As String
Data Type
190
String
See Also
Action Property (VSDraw)

Executes actions such as clear, show, and print.
Syntax
val% = [form!]VSDraw.Action
Remarks
This property was initially implemented in the VBX version of the VSDraw control, which did not support custom
methods. It is still supported for compatibility with older projects, but there are equivalent methods for most of its
settings. When possible, the methods should be used instead of the Action property, because they provide more options
and result in clearer code.
The settings for the Action property are described below:

daNone 0 No effect.
daClear 1 Clears the control. Equivalent to the Clear method.
daDraw 2 Repaints the control. Equivalent to the Show method.
daPrint 3 Prints the contents of the control on the default printer. The
output is scaled to fit the page and preserve the aspect ratio.
Equivalent to the Print method.
daChoosePrint 4 Shows a printer setup dialog, then prints the contents of the
control on the default printer.
daCopy 5 Copies the contents of the control to the clipboard. Equivalent
to the Copy method.
Data Type
DrawActionSettings (Enumeration)
See Also
BackStyle Property
Returns or sets whether text is transparent or opaque.
Syntax
[form!]VSDraw.BackStyle[ = DrawBackStyleSettings ]
Remarks
The settings for the BackStyle property are described below:
191
bkTransparent 0 Text is transparent.
bkOpaque 1 Text is opaque.
Set BackStyle to bkTransparent when you want to place text over graphics to avoid erasing parts of the drawing. Set
BackStyle to bkOpaque when you want the text to stand out.
To draw text, use the Text property.
Data Type
DrawBackStyleSettings (Enumeration)
Default Value
bkTransparent (0)
See Also
BrushColor Property (VSDraw)

Returns or sets the brush color.
Syntax
[form!]VSDraw.BrushColor[ = colorref& ]
Remarks
Data Type
Color
See Also
BrushStyle Property (VSDraw)

Returns or sets the brush style.
Syntax
[form!]VSDraw (page 186).BrushStyle[ = BrushStyleSettings ]
Remarks
Data Type
BrushStyleSettings (Enumeration)
Default Value
bsSolid (0)
See Also
192
Draw Property (VSDraw)

Draws an object within the rectangle defined by the X1, Y1, X2, and Y2 properties.
Syntax
[form!]VSDraw.Draw = DrawSettings
Remarks
methods. It is still supported for compatibility with older projects, but there are equivalent methods for all of its settings.
When possible, the methods should be used instead of the Draw property, because they provide more options and result
in clearer code.
The settings for the Draw property are described below:

doNothing 0 No effect.
doLine 1 Draw a line between points (X1, Y1) and (X2, Y2), see also the
DrawLine method.
doRectangle 2 Draw a rectangle between points (X1, Y1) and (X2, Y2), see also
the DrawRectangle method.
doEllipse 3 Draw an ellipse enclosed in the rectangle defined by points (X1,
Y1) and (X2, Y2), see also the DrawCircle and DrawEllipse
methods.
Data Type
DrawSettings (Enumeration)
See Also
EmptyColor Property (VSDraw)

Returns or sets the color of the area around the preview page.
Syntax
[form!]VSDraw.EmptyColor[ = colorref& ]
Remarks
An empty area is visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.
Data Type
Color
See Also
193
KeepTextAspect Property
Returns or sets whether text should keep its aspect ratio when the drawing is resized.
Syntax
[form!]VSDraw.KeepTextAspect[ = {True | False} ]
Remarks
When KeepTextAspect is set to True, text drawn using the Text property will retain its aspect ratio when the control
is resized or rescaled. This is done by adjusting the font height to the new scale, and computing the width so that the text
appearance does not change.
When KeepTextAspect is set to False, text drawn using the Text property will be resized or rescaled with the control.
Both the height and the width of the font are adjusted to reflect the new scaling, so the aspect of the text may change (the
font may look "fat" or "skinny").
Note that this is not a global setting that applies to the entire drawing. It is like a font attribute, that applies individually
to each string drawn on the control.
For example, the picture below shows VSDraw control with a drawing containing two strings. One was drawn with
KeepTextAspect set to True, the other to False. The picture shows the drawing before and after the control was
resized:
Data Type
Boolean
Default Value
True
See Also
LargeChangeHorz Property (VSDraw)

Returns or sets the amount of change to the ScrollLeft property when the user clicks the scroll bar area.
Syntax
[form!]VSDraw.LargeChangeHorz[ = value As Double ]
Remarks
Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.
Data Type
Double
194
Default Value
300
See Also
LargeChangeVert Property (VSDraw)

Returns or sets the amount of change to the ScrollTop property when the user clicks the scroll bar area.
Syntax
[form!]VSDraw.LargeChangeVert[ = value As Double ]
Remarks
Data Type
Double
Default Value
300
See Also
LineSpacing Property (VSDraw)

Returns or sets the line spacing as a percentage (for example, 100% is single spacing, 200% is double spacing).
Syntax
[form!]VSDraw.LineSpacing[ = value As Single ]
Remarks
The line spacing is used when a string containing line breaks is assigned to the Text property.
For example:
vd.Text = "This text" & vbLf & "has line breaks."
Data Type
Single
Default Value
100
See Also
MouseScroll Property (VSDraw)

Returns or sets whether contents may be scrolled by dragging the VSDraw's client area.
Syntax
[form!]VSDraw.MouseScroll[ = {True | False} ]
Remarks
195
Data Type
Boolean
Default Value
True
See Also
PageHeight Property (VSDraw)

Returns or sets the physical height of the drawing, in twips.
Syntax
[form!]VSDraw.PageHeight[ = value As Double ]
Remarks
The PageHeight and PageWidth properties may be set to values, in twips, that define the physical dimensions of the
drawing (in twips).
If these properties are not specified, or are set to zero, the drawing is stretched to fill the control. If they are specified,
then the control will scale the drawing according to their values. The control will display and manage scrollbars if
necessary, so the user can view the entire drawing.
If the PageHeight and PageWidth properties are set to non-zero values, the Zoom and ZoomMode properties can also
be used to control the appearance of the control.
Data Type
Double
Default Value
0
See Also
PageWidth Property (VSDraw)

Returns or sets the physical width of the drawing, in twips.
Syntax
[form!]VSDraw.PageWidth[ = value As Double ]
Remarks
The PageHeight and PageWidth properties may be set to values, in twips, that define the physical dimensions of the
drawing (in twips).
If these properties are not specified, or are set to zero, the drawing is stretched to fill the control. If they are specified,
then the control will scale the drawing according to their values. The control will display and manage scrollbars if
necessary, so the user can view the entire drawing.
If the PageHeight and PageWidth properties are set to non-zero values, the Zoom and ZoomMode properties can also
be used to control the appearance of the control.
Data Type
Double
Default Value
196
0
See Also
PenColor Property (VSDraw)

Returns or sets the pen color.
Syntax
[form!]VSDraw.PenColor[ = colorref& ]
Remarks
control.
Data Type
Color
See Also
PenStyle Property (VSDraw)

Returns or sets the pen style.
Syntax
[form!]VSDraw.PenStyle[ = PenStyleSettings ]
Remarks
control.
The settings for the PenStyle property are described below:

psSolid 0 Solid pen (default value).
psDash 1 Dashed pen.
psDot 2 Dotted pen.
psDashDot 3 Dash-dot pen.
psDashDotDot 4 Dash-dot-dot pen.
psTransparent 5 Transparent pen (no lines).
psInsideSolid 6 Solid pen drawn inside shapes.
Note: Non-solid settings are only valid when the PenWidth property is set to zero (which translates into a pen one-pixel
wide). This is a Windows GDI limitation, not imposed by the VSPrinter control.
197
Data Type
PenStyleSettings (Enumeration)
Default Value
psSolid (0)
See Also
PenWidth Property (VSDraw)

Returns or sets the pen width, in logical units.
Syntax
[form!]VSDraw.PenWidth[ = value As Double ]
Remarks
control.
The pen width is specified in scale units, defined by the ScaleWidth, ScaleHeight, ScaleLeft, and ScaleHeight
properties.
If you set this property to zero, the resulting pen is one pixel wide. This is the only settings that allows the creation of
non-solid pens (also see PenStyle).
Data Type
Double
Default Value
0
See Also
Picture Property
Returns a snapshot of the current drawing.
Syntax
[form!]VSDraw.Picture[ = Picture ]
Remarks
Reading this property returns a picture (Windows metafile) that can be rendered by another control, such as the
VSPrinter.
Assigning a bitmap or an icon to this property draw the picture at the position specified by the X1, Y1, X2, and Y2
properties. Assigning a metafile to this property replaces the current drawing with the specified metafile.
See also the DrawPicture method.
Data Type
Picture
See Also
198
Polygon Property (VSDraw)

Draws a polygon defined by a string of X,Y coordinates.
Syntax
[form!]VSDraw.Polygon = value As String
Remarks
The string assigned to the Polygon property contains a sequence of coordinates, in scale units, separated by spaces or
commas.
This is a convenient way to draw complex closed shapes using a single drawing command. For example, the code below
draws a rectangle extending from point (1000,1000) to point (2000,2000).
vd.Polygon = "1000 1000, 2000 1000, 2000 2000, 1000 2000"
The Polygon property draws closed shapes. To draw open shapes, use the Polyline property instead.
Data Type
String
See Also
Polyline Property (VSDraw)

Draws a line defined by a string of X,Y coordinates.
Syntax
[form!]VSDraw.Polyline = value As String
Remarks
The string assigned to the Polyline property contains a sequence of coordinates, in scale units, separated by spaces or
commas.
This is a convenient way to draw complex open shapes using a single drawing command. For example, the code below
draws a sine curve.
Const pi = 3.1416
Dim a#, s$
For a = 0 To 6 * pi Step 0.2
s = s & (1000 + 100 * a) & " " & (2000 + Sin(a) * 500) & " "
Next
vd.Polyline = s
The Polyline property draws an open shape using the current pen. To draw closed shapes, use the Polygon property
instead.
Data Type
String
See Also
199
ProportionalBars Property (VSDraw)
Returns or sets whether the scrollbar thumbs should be proportional to the size of the visible area.
Syntax
[form!]VSDraw.ProportionalBars[ = {True | False} ]
Data Type
Boolean
Default Value
True
See Also
ScaleHeight Property
Returns or sets the number of logical units for the vertical dimension of the drawing.
Syntax
[form!]VSDraw.ScaleHeight[ = value As Double ]
Remarks
All drawing on the VSDraw control is done in an arbitrary coordinate system, determined by the ScaleWidth,
ScaleHeight, ScaleLeft and ScaleTop properties. In this respect, the VSDraw control is similar to a VB PictureBox
control with the ScaleMode property set to User (0).
You may change to coordinate system after creating the drawing, and the changes will be reflected on the display. This
allows you to rescale the drawing dynamically.
Positive values for ScaleHeight and ScaleWidth mean coordinates grow down and to the right. Negative values mean
coordinates grow up and to the left.
The picture below shows two typical ways to set up the VSDraw's coordinate system. The diagram on the left shows the
default settings, with the vertical axis pointing down and origin at the top left corner. The diagram on the right shows
how to create a coordinate system with the vertical axis pointing up and origin at the bottom left corner.
Note: All scaling properties must be in the range from -32,768 to 32,767. This is a limitation imposed by Windows
metafiles.
Data Type
Double
See Also
200
ScaleLeft Property
Returns or sets the horizontal coordinate for the left edge of the drawing.
Syntax
[form!]VSDraw.ScaleLeft[ = value As Double ]
Remarks
ScaleHeight, ScaleLeft and ScaleTop properties.
For example, the following code sets the origin of the coordinate system to the center of the control, regardless of its
physical dimensions:
vsDraw.ScaleLeft = -vsDraw.ScaleWidth / 2
vsDraw.ScaleTop = -vsDraw.ScaleHeight / 2
For more details and a diagram, see the ScaleHeight property.

metafiles.
Data Type
Double
See Also
ScaleTop Property
Returns or sets the vertical coordinate for the top edge of the drawing.
Syntax
[form!]VSDraw.ScaleTop[ = value As Double ]
Remarks
metafiles.
Data Type
Double
See Also
ScaleWidth Property
Returns or sets the number of logical units for the horizontal dimension of the drawing.
Syntax
[form!]VSDraw.ScaleWidth[ = value As Double ]
Remarks
201
metafiles.
Data Type
Double
See Also
ScrollLeft Property (VSDraw)

Syntax
[form!]VSDraw.ScrollLeft[ = value As Double ]
Remarks
The ScrollLeft and ScrollTop properties allow you to control the VSDraw's scroll bars. You can read these values to
determine what part of the drawing is visible to the user, or set them to make a part of the drawing visible.
Data Type
Double
See Also
ScrollTop Property (VSDraw)

Syntax
[form!]VSDraw.ScrollTop[ = value As Double ]
Remarks
The ScrollLeft and ScrollTop properties allow you to control the VSDraw's scroll bars. You can read these values to
determine what part of the drawing is visible to the user, or set them to make a part of the drawing visible.
Data Type
Double
See Also
SmallChangeHorz Property (VSDraw)

Returns or sets the amount of change to the ScrollLeft property when the user clicks the scroll arrow.
Syntax
[form!]VSDraw.SmallChangeHorz[ = value As Double ]
202
Remarks
Data Type
Double
See Also
SmallChangeVert Property (VSDraw)

Returns or sets the amount of change to the ScrollTop property when the user clicks the scroll arrow.
Syntax
[form!]VSDraw.SmallChangeVert[ = value As Double ]
Remarks
Data Type
Double
See Also
Text Property (VSDraw)

Prints a string starting at the point defined by the X1, Y1 properties.
Syntax
[form!]VSDraw.Text = value As String
Remarks
The cursor position is not updated after the text is rendered.
The string assigned to the Text property may have embedded carriage-returns (vbCr, or Chr(13)) characters, which
cause line breaks. In this case, the line spacing is determined by the LineSpacing property.
The following properties also affect how text is rendered: TextAlign, TextAngle, TextColor, KeepTextAspect, and
Font.
Data Type
String
See Also
TextAlign Property (VSDraw)

Returns or sets the text alignment.
Syntax
[form!]VSDraw.TextAlign[ = DrawTextAlignSettings ]
Remarks
The settings for the TextAlign property are described below:
203
tadLeft 0 Text is left-aligned. The string starts at the position specified by the
X1 property.
tadCenter 1 Text is center-aligned. The middle of the string line up with the
position specified by the X1 property.
tadRight 2 Text is right-aligned. The string ends at the position specified by
the X1 property.
Data Type
DrawTextAlignSettings (Enumeration)
See Also
TextAngle Property (VSDraw)

Returns or sets the text angle, in tenths of degrees.
Syntax
[form!]VSDraw.TextAngle[ = value As Double ]
Remarks
The rotation is applied in the counter-clockwise direction, starting from the three o'clock position, as show below:
Data Type
Double
Default Value
0
See Also
TextColor Property (VSDraw)

Returns or sets the text color.
Syntax
[form!]VSDraw.TextColor[ = colorref& ]
Data Type
Color
204
See Also
TextHeight Property (VSDraw)

Returns the height of a string in scale units.
Syntax
val# = [form!]VSDraw.TextHeight(Text As String)
Data Type
Double
See Also
TextWidth Property (VSDraw)

Returns the width of a string in scale units.
Syntax
val# = [form!]VSDraw.TextWidth(Text As String)
Remarks
The value returned is the width of the string measured using the current font and scaling.
If the control is resized, or the scaling changes, the width of the string measured in scale units may change, depending on
the setting of the KeepTextAspect property. If KeepTextAspect is set to True (the default), then the text width will
change in order to keep the aspect ratio constant. If KeepTextAspect is set to False, then the width of the string will
remain constant.
Data Type
Double
See Also
Track Property (VSDraw)

Syntax
[form!]VSDraw.Track[ = {True | False} ]
Remarks
Data Type
Boolean
Default Value
True
See Also
205
Version Property (VSDraw)
Syntax
val% = [form!]VSDraw.Version
Remarks
Data Type
Integer
See Also
X1 Property (VSDraw)
Returns or sets the left coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSDraw.X1[ = value As Double ]
Remarks
The X1, Y1, X2, and Y2 properties set or return the boundaries of a rectangle used to define the position and size of
objects drawn with the Draw and Text properties.
The coordinate system used is determined by the ScaleWidth, ScaleHeight, ScaleLeft, and ScaleTop properties.
Data Type
Double
See Also
X2 Property (VSDraw)
Returns or sets the right coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSDraw.X2[ = value As Double ]
Data Type
Double
See Also
Y1 Property (VSDraw)
Returns or sets the top coordinate of the rectangle used with the Draw property.
206
Syntax
[form!]VSDraw.Y1[ = value As Double ]
Data Type
Double
See Also
Y2 Property (VSDraw)
Returns or sets the bottom coordinate of the rectangle used with the Draw property.
Syntax
[form!]VSDraw.Y2[ = value As Double ]
Data Type
Double
See Also
Zoom Property (VSDraw)

Returns or sets the preview scale: set to a percentage, or zero to fill the control.
Syntax
[form!]VSDraw.Zoom[ = value As Double ]
Remarks
If the drawing has physical dimensions (PageHeight and PageWidth properties set to non-zero values), then the Zoom
and ZoomMode properties determine how these dimensions are mapped to the screen. The control will automatically
add and manage scrollbars if the dimensions of the drawing become larger than the control.
If PageWidth and PageHeight are set to zero, this property has no effect.
See also the ZoomMode property.
Data Type
Double
Default Value
100
See Also
ZoomMode Property (VSDraw)

Sets or returns the zoom mode (explicit percentage or one of the automatic settings).
Syntax
[form!]VSDraw.ZoomMode[ = ZoomModeSettings ]
207
Remarks
If the drawing has physical dimensions (PageHeight and PageWidth properties set to non-zero values), then the Zoom
and ZoomMode properties determine how these dimensions are mapped to the screen. The control will automatically
add and manage scrollbars if the dimensions of the drawing become larger than the control.
If PageWidth and PageHeight are set to zero, this property has no effect.
The settings for the ZoomMode property are described below:

zmPercentage 0 Use zoom factor set by the user with Zoom property.
zmThumbnail 1 Not applicable to this control.
zmTwoPages 2 Not applicable to this control.
zmWholePage 3 Show a whole page.
zmPageWidth 4 Show page so that it fits horizontally within the control.
zmStretch 5 Stretch page to fill the control without preserving the aspect ratio.
Settings zmThumbnail and zmTwoPages are used only with the VSPrinter control. VSDraw does not support multi-page
drawings, so these settings are automatically converted to zmWholePage.
Data Type
ZoomModeSettings (Enumeration)
See Also
VSDraw Methods
Clear Method (VSDraw)

Resets the control and discards its contents.
Syntax
[form!]VSDraw.Clear
See Also
ClientToPage Method (VSDraw)

Converts mouse coordinates to page coordinates.
Syntax
[form!]VSDraw.ClientToPage X As Single, Y As Single
Remarks
Use the ClientToPage method to convert screen coordinates (expressed in twips) to drawing coordinates (defined by
the control's ScaleWidth, ScaleHeight, ScaleLeft, and ScaleHeight properties).
Note that the parameters used in mouse events (MouseDown, MouseMove, and MouseUp) are in page coordinates, so
this conversion is not necessary when handling these events.
208
The code below illustrates this method:
' set default scaling values
vd.ScaleWidth = 1000
vd.ScaleHeight = 1000
vd.ScaleLeft = 1000
vd.ScaleTop = 0
' set x,y properties to half of the control

x = vd.Width / 2
y = vd.Height / 2
' convert to scale units

vd.ClientToPage x, y
' half of the control is 1000/2, 1000/2

Debug.Print x y
500 500
See Also
PageToClient Method (VSDraw) (page 212)
Copy Method
Updates the drawing and copies it to the clipboard.
Syntax
[form!]VSDraw.Copy
Remarks
The drawing is copied to the clipboard as a metafile. The dimensions of the drawing are determined by the PageWidth
and PageHeight properties. If either or both of these properties are set to zero (the default), then the dimensions are
determined by the control's dimensions.
See Also
DrawCircle Method (VSDraw)

Draws a circle, circular wedge, or circular arc.
Syntax
[form!]VSDraw.DrawCircle CenterX As Double, CenterY As Double, Radius As Double, [ Start As Variant ], [ End As
Variant ]
Remarks
The parameters for the DrawCircle method are described below:
CenterX X coordinate of the center of the circle, arc, or wedge.
CenterY Y coordinate of the center of the circle, arc, or wedge.
Radius Radius of the circle, arc, or wedge.
radians. If omitted, a circle is drawn.
209
omitted, a circle is drawn.
The CenterX, CenterY, and Radius parameters are specified in scale units, defined by the ScaleWidth, ScaleHeight,
ScaleLeft, and ScaleHeight properties.
See Also
DrawEllipse Method (VSDraw)

Draws an ellipse, wedge, or arc.
Syntax
[form!]VSDraw.DrawEllipse X1 As Double, Y1 As Double, X2 As Double, Y2 As Double, [ Start As Variant ], [ End
As Variant ]
Remarks
The parameters for the DrawEllipse method are described below:
X1, Y1 First corner of the rectangle that encloses the ellipse.
X2, Y2 Second corner of the rectangle that encloses the ellipse.
Start Optional parameter that specifies the beginning position of an arc or wedge,
in radians. If omitted, an ellipse is drawn.
End Optional parameter that specifies the end position of an arc or wedge, in
radians. If omitted, an ellipse is drawn.
The CenterX, CenterY, and Radius parameters are specified in scale units, defined by the ScaleWidth, ScaleHeight,
See Also
DrawLine Method (VSDraw)

Draws a line segment.
210
Syntax
[form!]VSDraw.DrawLine X1 As Double, Y1 As Double, [ X2 As Variant ], [ Y2 As Variant ]
Remarks
The DrawLine method draws a line between point (X1, Y1) and (X2, Y2). If (X2, Y2) are omitted, the line is drawn from
the last point used in a call to DrawLine and (X1, Y1).
Lines are drawn with the current pen, defined by the PenColor, PenStyle, and PenWidth properties.
The X1, Y1, X2, and Y2 parameters are specified in scale units, defined by the ScaleWidth, ScaleHeight, ScaleLeft, and
ScaleHeight properties.
To draw complex shapes, you may prefer to use the Polygon or PolyLine properties instead.
See Also
DrawPicture Method (VSDraw)

Draws a bitmap or an icon.
Syntax
[form!]VSDraw.DrawPicture Picture As Picture, Left As Double, Top As Double, Width As Double, Height As
Double
Remarks
The DrawPicture method draws a bitmap or an icon at the specified position.
The Left, Top, Width, and Height parameters are specified in scale units, defined by the ScaleWidth, ScaleHeight,
If the Picture parameter is a metafile, rather than a bitmap or an icon, then the specified metafile replaces the contents of
the control.
See Also
DrawRectangle Method (VSDraw)

Draws a rectangle.
Syntax
[form!]VSDraw.DrawRectangle X1 As Double, Y1 As Double, X2 As Double, Y2 As Double, [ Radius1 As Variant ],
[ Radius2 As Variant ]
Remarks
The parameters for the DrawRectangle method are described below:
X1, Y1 First corner of the rectangle.
X2, Y2 Second corner of the rectangle.
Radius1 Optional parameter that specifies the radius of a rounded rectangle's corner, in
the horizontal direction.
Radius2 Optional parameter that specifies the radius of a rounded rectangle's corner, in
the vertical direction.
211
If the Radius1 and Radius2 parameters are omitted, a rectangle is drawn.
All measurements are specified in scale units, defined by the ScaleWidth, ScaleHeight, ScaleLeft, and ScaleHeight
properties.
See Also
LoadDoc Method (VSDraw)

Loads a VSDraw document (metafile) from disk.
Syntax
[form!]VSDraw.LoadDoc FileName As String
Remarks
The file specified must exist and must contain a windows metafile (the usual extension for these files is WMF).
The SaveDoc method can be used to create these files.
See Also
PageToClient Method (VSDraw)

Converts page coordinates to mouse coordinates.
Syntax
[form!]VSDraw.PageToClient X As Single, Y As Single
Remarks
Use the PageToClient method to convert drawing coordinates (defined by the control's ScaleWidth, ScaleHeight,
ScaleLeft, and ScaleHeight properties) to screen coordinates (expressed in twips).
See also the ClientToPage method.
See Also
ClientToPage Method (VSDraw) (page 208)
PrintDoc Method (VSDraw)

Updates the drawing and copies it to the printer.
Syntax
[form!]VSDraw.PrintDoc
See Also
SaveDoc Method (VSDraw)

Saves a VSDraw document (metafile) to disk.
212
Syntax
[form!]VSDraw.SaveDoc FileName As String
Remarks
The usual extension for Windows metafiles files is WMF.
You may load the document back from disk using the LoadDoc method.
See Also
SetPageExtent Method
Sets the PageWidth and PageHeight properties.
Syntax
[form!]VSDraw.SetPageExtent PageWidth As Double, PageHeight As Double
See Also
Show Method
Updates the drawing and shows it on the screen.
Syntax
[form!]VSDraw.Show
Remarks
This is equivalent to the Refresh method.
See Also
VSDraw Events
Scroll Event (VSDraw)

Fired after the control scrolls its contents.
Syntax
Private Sub VSDraw_Scroll()
Remarks
See Also
VSViewPort Control
The VSViewPort is a scrollable container control. With VSViewPort, you no longer have to write tedious code to
synchronize scroll bars and picture boxes. You decide how big your window should be, then let the VSViewPort scroll
213
your controls for you. You can use the VSViewPort to implement fill-out forms that are larger than the visible window,
and print them later using the VSPrinter control.
The new VSViewPort control has a FocusTrack property that automatically scrolls the viewport so that the control with
the input focus is visible to the user.
Note: Before you can use a VSViewPort control in your application, you must add the VSVPort8.ocx file to your
project. Please refer to the VB documentation for details on adding controls to your projects.
To distribute applications you create with the VSViewPort control, you must install and register it on the user's
computer. The Setup Wizard provided with Visual Basic provides tools to help you do that. Please refer to the Visual
Basic manual for details.
The VSViewPort control provides the following properties, events and methods:
All of the properties, events and methods for the VSViewPort control are listed in the following tables. Properties,
events and methods that apply only to this control, or that require special consideration when used with it, are marked
with an asterisk (*). These are documented in later sections. For documentation on the remaining properties, see the
Visual Basic documentation.
Properties
*AccessibleDescription Gets or sets the description of the control used by

accessibility client applications.
*AccessibleName Gets or sets the name of the control used by accessibility
*AccessibleRole Gets or sets the role of the control used by accessibility
*AccessibleValue Gets or sets the value of the control used by accessibility
*AutoScroll Returns or sets whether contents are scrolled
automatically by the control.
Enabled See the Visual Basic documentation.
*FocusMarginLeft Returns or sets the left margin for tracking the child with
focus.
*FocusMarginTop Returns or sets the right margin for tracking the child
with focus.
*FocusTrack Returns or sets whether the control should scroll to keep
visible the child with focus.
hWnd See the Visual Basic documentation.
*LargeChangeHorz Returns or sets the amount of change to the VirtualLeft
*LargeChangeVert Returns or sets the amount of change to the VirtualTop
MouseIcon See the Visual Basic documentation.
214
MousePointer See the Visual Basic documentation.
*MouseScroll Returns or sets whether contents may be scrolled by
dragging the control's client area.
Picture Returns or sets a picture to be used as a background for
the control.
*ProportionalBars Returns or sets whether the scrollbar thumbs should be
proportional to the size of the visible area.
*SmallChangeHorz Returns or sets the amount of change to the VirtualLeft
*SmallChangeVert Returns or sets the amount of change to the VirtualTop
*Track Returns or sets whether scrolling occurs as the user drags
the scroll thumb.
*VirtualHeight Returns or sets the height of the scrollable area, in twips.
*VirtualLeft Returns or sets the left coordinate of the visible area, in
twips.
*VirtualTop Returns or sets the top coordinate of the visible area, in
twips.
*VirtualWidth Returns or sets the width of the scrollable area, in twips.
Methods

*SetVirtualExtent Sets the VirtualWidth and VirtualHeight properties to
fit the contained controls.
Events

*Scroll Fired after the control scrolls its contents.
215
VSViewPort Properties
AccessibleDescription Property (VSViewPort)

Syntax
Property AccessibleDescription As String
Data Type
String
See Also
VSViewPort Control (page 213)
AccessibleName Property (VSViewPort)

Syntax
Property AccessibleName As String
Data Type
String
See Also
AccessibleRole Property (VSViewPort)

Syntax
Property AccessibleRole As Variant
Data Type
Variant
See Also
AccessibleValue Property (VSViewPort)

Syntax
Property AccessibleValue As String
Data Type
String
See Also
216
AutoScroll Property
Returns or sets whether contents are scrolled automatically by the control.
Syntax
[form!]VSViewPort.AutoScroll[ = {True | False} ]
Remarks
This property should be set to True in most applications, so that scrolling is done automatically by the VSViewPort
control.
If you wish to process scrolling yourself, set AutoScroll to False and respond to the Scroll event.
Data Type
Boolean
Default Value
True
See Also
FocusMarginLeft Property
Returns or sets the left margin for tracking the child with focus.
Syntax
[form!]VSViewPort.FocusMarginLeft[ = value As Double ]
Remarks
This property is used in conjunction with the FocusTrack property.
It allows you to specify a minimum distance, in twips, between the left edge of the control with the focus and the
VSViewPort control. This distance (margin) allows labels placed on the left of the controls to remain visible as the user
scrolls the form.
Data Type
Double
See Also
FocusMarginTop Property
Returns or sets the right margin for tracking the child with focus.
Syntax
[form!]VSViewPort.FocusMarginTop[ = value As Double ]
Remarks
This property is used in conjunction with the FocusTrack property.
It allows you to specify a minimum distance, in twips, between the top edge of the control with the focus and the
VSViewPort control. This distance (margin) allows labels placed above the controls to remain visible as the user scrolls
the form.
Data Type
Double
217
Default Value
0
See Also
FocusTrack Property
Returns or sets whether the control should scroll to keep visible the child with focus.
Syntax
[form!]VSViewPort.FocusTrack[ = {True | False} ]
Remarks
This property is useful if you want to implement a form-like data entry screen, and the form is larger than the control.
If you place the fields in a VSViewPort control and set the FocusTrack property to True, the control will scroll
automatically as the user presses the TAB key, so the field that has the focus is visible to the user.
In many types of forms, fields have labels on their left or top. To keep the labels visible as well as the field, use the
FocusMarginLeft and FocusMarginTop properties. These properties specify the size of the margins (in twips) that
should be added to the left and top of the control with the focus so that the labels remain visible.
The picture below illustrates the behavior of the FocusMarginLeft and FocusMarginTop properties:
Note: The FocusTrack property works automatically as long as the controls getting the focus are directly contained in
the VSViewPort control. If the control getting the focus is contained in another control (for example, a picture box
inside the VSViewPort control), then VSViewPort will not get the notifications it needs to track the focus
automatically. In these cases, you have to add code to the child control's GetFocus event and set the FocusTrack
property to True explicitly.
For example, assuming you have an array of text boxes in a frame or picture box which in turn is in a VSViewPort
control, you could track the control with the focus using this code:
Private Sub txtTextBoxArray_GotFocus(Index As Integer)
' scroll the control with the focus into view

VSViewPort8.FocusTrack = True
End Sub
Data Type
Boolean
Default Value
False
See Also
218
LargeChangeHorz Property (VSViewPort)
Returns or sets the amount of change to the VirtualLeft property when the user clicks the scroll bar area.
Syntax
[form!]VSViewPort.LargeChangeHorz[ = value As Double ]
Data Type
Double
Default Value
300
See Also
LargeChangeVert Property (VSViewPort)

Returns or sets the amount of change to the VirtualTop property when the user clicks the scroll bar area.
Syntax
[form!]VSViewPort.LargeChangeVert[ = value As Double ]
Data Type
Double
Default Value
300
See Also
MouseScroll Property (VSViewPort)

Returns or sets whether contents may be scrolled by dragging the control's client area.
Syntax
[form!]VSViewPort.MouseScroll[ = {True | False} ]
Data Type
Boolean
Default Value
False
See Also
Picture Property (VSViewPort)

Returns or sets a picture to be used as a background for the control.
Syntax
[form!]VSViewPort.Picture[ = Picture ]
Remarks
219
If used, the picture is stretched to fill the entire virtual area.
Data Type
Picture
See Also
ProportionalBars Property (VSViewPort)

Returns or sets whether the scrollbar thumbs should be proportional to the size of the visible area.
Syntax
[form!]VSViewPort.ProportionalBars[ = {True | False} ]
Data Type
Boolean
Default Value
True
See Also
SmallChangeHorz Property (VSViewPort)

Returns or sets the amount of change to the VirtualLeft property when the user clicks the scroll arrow.
Syntax
[form!]VSViewPort.SmallChangeHorz[ = value As Double ]
Data Type
Double
Default Value
30
See Also
SmallChangeVert Property (VSViewPort)

Returns or sets the amount of change to the VirtualTop property when the user clicks the scroll arrow.
Syntax
[form!]VSViewPort.SmallChangeVert[ = value As Double ]
Data Type
Double
Default Value
30
See Also
220
Track Property (VSViewPort)
Syntax
[form!]VSViewPort.Track[ = {True | False} ]
Remarks
Setting this property to True provides more user feedback during scrolling, but it can slow down your application and
cause some flicker. If in doubt, try it both ways and see which works best for you.
Data Type
Boolean
Default Value
False
See Also
Version Property (VSViewPort)

Syntax
val% = [form!]VSViewPort.Version
Remarks
Data Type
Integer
See Also
VirtualHeight Property
Returns or sets the height of the scrollable area, in twips.
Syntax
[form!]VSViewPort.VirtualHeight[ = value As Double ]
Remarks
The VirtualWidth and VirtualHeight properties determine the size of the virtual area that may contain controls and be
scrolled into view. The VirtualLeft and VirtualTop properties determine what portion of the virtual area is currently
visible. See the VirtualLeft property for a diagram that illustrates the relationship between these properties.
If the VirtualWidth or VirtualHeight are set to values smaller than the control dimensions, the control will not display
scrollbars along that dimension.
To set this property automatically, based on the control contents, use the SetVirtualExtent method.
Data Type
221
Double
Default Value
1000
See Also
VirtualLeft Property
Syntax
[form!]VSViewPort.VirtualLeft[ = value As Double ]
Remarks
visible.
If this property is set to a value larger than VirtualWidth, it is set to VirtualWidth.
If the AutoScroll property is set to True, the VirtualLeft and VirtualTop properties are automatically updated by the
control when the user uses the scrollbars or drags the control by its client area.
The diagram below shows the relationship between the VirtualWidth, VirtualHeight, VirtualLeft, and VirtualTop
properties:
Data Type
Double
Default Value
222
0
See Also
VirtualTop Property
Syntax
[form!]VSViewPort.VirtualTop[ = value As Double ]
Remarks
visible.
If this property is set to a value larger than VirtualHeight, it is set to VirtualHeight.
If the AutoScroll property is set to True, the VirtualLeft and VirtualTop properties are automatically updated by the
control when the user uses the scrollbars or drags the control by its client area.
See the VirtualLeft property for a diagram that illustrates the relationship between the VirtualWidth, VirtualHeight,
VirtualLeft, and VirtualTop properties.
Data Type
Double
Default Value
0
See Also
VirtualWidth Property
Returns or sets the width of the scrollable area, in twips.
Syntax
[form!]VSViewPort.VirtualWidth[ = value As Double ]
Remarks
visible. See the VirtualLeft property for a diagram that illustrates the relationship between these properties.
If the VirtualWidth or VirtualHeight are set to values smaller than the control dimensions, the control will not display
scrollbars along that dimension.
To set this property automatically, based on the control contents, use the SetVirtualExtent method.
Data Type
Double
Default Value
1000
See Also
223
VSViewPort Methods
SetVirtualExtent Method
Sets the VirtualWidth and VirtualHeight properties to fit the contained controls.
Syntax
[form!]VSViewPort.SetVirtualExtent [ VirtualWidth As Variant ], [ VirtualHeight As Variant ]
Remarks
This method allows you to set the VirtualWidth and VirtualHeight properties simultaneously.
If you omit one or both of the parameters, the corresponding dimensions are set automatically, based on the contents of
the VSViewPort control. To set the dimensions automatically, the control scans its contents and determines the how
large each virtual dimension must be so that all contained controls can be made visible with the scroll bars.
See Also
VSViewPort Events
Scroll Event (VSViewPort)

Fired after the control scrolls its contents.
Syntax
Private Sub VSViewPort_Scroll()
Remarks
This event is especially useful if the AutoScroll property is set to False.
In this case, you should respond to the Scroll event by reading the VirtualLeft and VirtualTop properties and moving
the controls inside the VSViewPort control.
See Also
VSPDF Control
Properties
AnchorTag Gets or sets the tag prefix to use for building hyperlink destinations.
Author Gets or sets the name of the person who created the PDF document.
Compress Gets or sets the type of element that should be compressed.
Creator Gets or sets the name of the application that created the PDF
document.
Index Returns/sets the number identifying a control in a control array.
Keywords Gets or sets the keywords associated with the PDF document.
224
LinkTag Gets or sets the tag prefix to use for building hyperlinks.
Name Returns the name used in code to identify an object.
Object Returns an object in a control.
OutlineTag Gets or sets the tag prefix to use for building outlines.
Parent Returns the object on which this object is located.
Subject Gets or sets the subject of the PDF document.
Tag Stores any extra data needed for your program.
Title Gets or sets the title of the PDF document.
Methods
ConvertDocument Converts the current document in a VSPrinter control into a PDF

file.
ConvertDocumentRange Converts part of the current document in a VSPrinter control into a
PDF file.
ConvertFile Converts an existing VSPrinter document into a PDF file.
ConvertFileRange Converts part of an existing VSPrinter document into a PDF file.
VSPDF Properties
AnchorTag Property
Gets or sets the tag prefix to use for building hyperlink destinations.
Syntax
Property AnchorTag As String
Data Type
String
See Also
VSPDF Control (page 224)
Author Property
Gets or sets the name of the person who created the PDF document.
Syntax
Property Author As String
Data Type
String
See Also
225
Compress Property
Gets or sets the type of element that should be compressed.
Syntax
Property Compress As CompressSettings
Data Type
CompressSettings Enumeration
See Also
Creator Property
Gets or sets the name of the application that created the PDF document.
Syntax
Property Creator As String
Data Type
String
See Also
Index Property
Returns/sets the number identifying a control in a control array.
Syntax
Property Index As Integer
Data Type
Integer
See Also
Keywords Property
Gets or sets the keywords associated with the PDF document.
Syntax
Property Keywords As String
Data Type
String
See Also
LinkTag Property
Gets or sets the tag prefix to use for building hyperlinks.
Syntax
226
Property LinkTag As String
Data Type
String
See Also
Name Property
Returns the name used in code to identify an object.
Syntax
Property Name As String
Data Type
String
See Also
Object Property
Returns an object in a control.
Syntax
Property Object As Object
Data Type
Object
See Also
OutlineTag Property
Gets or sets the tag prefix to use for building outlines.
Syntax
Property OutlineTag As String
Data Type
String
See Also
Parent Property
Returns the object on which this object is located.
Syntax
Property Parent As Object
Data Type
Object
227
See Also
Subject Property
Gets or sets the subject of the PDF document.
Syntax
Property Subject As String
Data Type
String
See Also
Tag Property
Stores any extra data needed for your program.
Syntax
Property Tag As String
Data Type
String
See Also
Title Property
Gets or sets the title of the PDF document.
Syntax
Property Title As String
Data Type
String
See Also
VSPDF Methods
ConvertDocument Method
Converts the current document in a VSPrinter control into a PDF file.
Syntax
Sub ConvertDocument(VSPrinterControl As Object, PDFFile As String)
See Also
228
ConvertDocumentRange Method
Converts part of the current document in a VSPrinter control into a PDF file.
Syntax
Sub ConvertDocumentRange(VSPrinterControl As Object, PDFFile As String, FirstPage As Integer, LastPage As
Integer)
See Also
ConvertFile Method
Converts an existing VSPrinter document into a PDF file.
Syntax
Sub ConvertFile(VSPrinterFile As String, PDFFile As String)
See Also
ConvertFileRange Method
Converts part of an existing VSPrinter document into a PDF file.
Syntax
Sub ConvertFileRange(VSPrinterFile As String, PDFFile As String, FirstPage As Integer, LastPage As Integer)
See Also
229

VSPrint 7

Uploaded by

Copyright:

Available Formats

VSPrint 7

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

VSPrint 7

Uploaded by

Copyright:

Available Formats

ComponentOne

ComponentOne, a division of GrapeCity

Copying and Distribution

This manual was produced using ComponentOne Doc-To-Help™.

Using the VSPrinter Control........................................................................................................................ 13

Using the VSDraw Control ......................................................................................................................... 23

VSView8 Samples ...................................................................................................................................... 26

Control Reference ...................................................................................................................................... 63

Installing VSView 8.0 for ActiveX

VSPrint8.ocx Contains the VSPrint8 control.

Upgrading from VSView7

Installing Demonstration Versions

End-User License Agreement

How does Licensing Work?

Upgrading From Previous Versions

Adding the VSView8 Components to the Toolbox

Using ComponentOne ActiveX Controls in the .NET

Hints and Troubleshooting

3) Why do so many methods have parameters of type Variant?

' no export file? no work!

VSPrinter Property Groups

Using Unit-Aware Properties

Visual C++ Topics

Using VSPrinter in MFC projects

// create the VSPrinter control and

Handling ActiveX Optional Parameters in MFC

Handling ActiveX Picture Properties in MFC

// create CPictureHolder from a bitmap resource

// get the LPDISPATCH pointer (must release later)

// draw the picture

// don't forget to release the LPDISPATCH

Dual Interfaces in MFC

// generate the document

// report how long it took

// get VTBL (dual) interface

// generate the document

// report how long it took

Using VSPrinter in ATL projects

extern "C" int WINAPI _tWinMain(HINSTANCE hInstance,

//MSG msg; // comment these lines out

Creating Controls Dynamically in ATL

// create the control (will fail if not registered)

// create the host window (nID = IDC_VSPRINTER1)

4. Attach the control to the host window.

VSPrinter Utilities - VPUtil

Using the VSDraw Control

Note: The ComponentOne Samples are also available at

Shows how to implement fill-out pre-printed forms. This sample uses a

Use a picture as a background for your documents (watermark-style). The

Render database tables (recordsets) using the AddTableArray method. This

Render database tables (recordsets) using the AddTableArray method. This

Create documents based on RTF text stored in a database. The document

Shows the effect of properties on paragraph spacing, indentation, and alignment.

Creates a compressed version of the image file and renders up to 12 images of

Visual C++ Samples

VSPrinter Tutorial - QuickPrinter

Step 1: Create the Form

' get file to open

' keep track of file being previewed