ComponentOne VSView 8.0

Product Profile

Using the VSPrinter Control

Using the VSDraw Control

Tutorials


Overview

Welcome to ComponentOne VSView8, a set of four ActiveX controls designed to support the creation and management of documents for printing and previewing. If you like VSView8, check out our other products by visiting our website at http://www.componentone.com/.

ComponentOne has a user-friendly distribution policy. We want every programmer to get copies of our products and try them for as long as they want. Those who like the tools and find them useful can buy licenses at reasonable prices. The only restriction is that unlicensed copies of the software will display a ComponentOne banner when they are loaded, as a friendly reminder that we do expect people to pay for the software if they use it on a regular basis.

We are confident that you'll like Product for .NET. 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:

Corporate Headquarters

ComponentOne LLC
4516 Henry Street
Suite 500
Pittsburgh, PA 15213 USA
412.681.4343
412.681.4384 (Fax)

http://www.componentone.com


Product Profile

The ComponentOne VSView8 package consists of four custom controls:

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.


Installation

To install VSView8, use the SETUP.EXE utility provided on the installation CD or diskettes. When you are prompted, enter the registration key (found on the CD case or the diskette) exactly as it is printed and click REGISTER to complete the registration.

The following files will be installed into your Windows\Help directory:

VSPrint8.chm

Contains the VSPrinter8 online help topics.

The following files will be installed into your Windows\System 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 following folders will be created by the setup utility:

ComponentOne

Directory used to store ComponentOne control information.

ComponentOne\VSView8

Contains sample projects and a README.TXT file with information about VSView8.

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 or any of our other products, and do not have a registration key, use the SETUP.EXE utility provided on the distribution CD. When prompted, leave the registration key box blank and press FINISH. 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.

Uninstalling VSView8

To uninstall VSView8, use the UNSETUP.EXE utility provided on the installation CD or diskettes. It will remove the VSView8 files from your WINDOWS\SYSTEM directory and from the system registry.


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:

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, for example, “VSView8”, in the dialog box. Select the new tab. Right-click the gray area under that tab and select Components from the context menu. The Components dialog box opens.

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

Click OK.


Upgrading from VSView 7

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 CONVERT 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, e.g. 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 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 (e.g. 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 (e.g. 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 (e.g. 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 (e.g. m_Printer) to use the class name declared in the new wrappers. From then on, follow steps 4 and 5 described above.


End-User License Agreement

IMPORTANT-READ CAREFULLY: This End User License Agreement (this "EULA") contains the terms and conditions regarding your use of the SOFTWARE (as defined below). This EULA contains material limitations to your rights in that regard. You should read this EULA carefully and treat it as valuable property.

I. THIS EULA.

1.

Software Covered by this EULA. This EULA governs your use of the ComponentOne, LLC ("C1") software product(s) enclosed or otherwise accompanied herewith (individually and collectively, the "SOFTWARE"). The term "SOFTWARE" includes, to the extent provided by C1: 1) any revisions, updates and/or upgrades thereto; 2) any data, image or executable files, databases, data engines, computer software, or similar items customarily used or distributed with computer software products; 3) anything in any form whatsoever intended to be used with or in conjunction with the SOFTWARE; and 4) any associated media, documentation (including physical, electronic and on-line) and printed materials (the "Documentation").

2.

This EULA is a Legally Binding Agreement Between You and C1. If you are acting as an agent of a company or another legal person, such as an officer or other employee acting for your employer, then "you" and "your" mean your principal, the entity or other legal person for whom you are acting. However, importantly, even if you are acting as an agent for another, you may still be personally liable for violation of federal and State laws, such as copyright infringement.

This EULA is a legally binding agreement between you and C1. You intend to be legally bound to this EULA to the same extent as if C1 and you physically signed this EULA. By installing, copying, or otherwise using the SOFTWARE, you agree to be bound by the terms and conditions contained in this EULA. If you do not agree to all of the terms and conditions contained in this EULA, you may not install or use the SOFTWARE. If, for whatever reason, installation has begun or has been completed, you should cancel installation or un-install the SOFTWARE, as the case may be. (You may click on the "exit" button or its equivalent to immediately abort installation.) If you do not agree to all of these terms and conditions, then you must promptly return the SOFTWARE to the place of business from which you obtained it in accordance with any return policies of such place of business. Return policies may vary between or among resellers, and you must comply with your particular reseller's return policies as agreed at the point of purchase. If the place of business from which you purchased the SOFTWARE does not honor a complete refund for a period of thirty (30) days from the date of proof of purchase, then you may return the SOFTWARE directly to C1 for a period of thirty (30) days from the date of your purchase. To return the product directly to C1, you must obtain a C1 Return Authorization Number by contacting C1, and you must forward all items purchased, including the proof of purchase, directly to C1. The return must be postage-prepaid, and post-marked within thirty (30) days from the proof of purchase, time being of the essence. The return option to C1 is only available to the original purchaser of an unopened factory packaged item.

II. YOUR LICENSE TO DEVELOP AND TO DISTRIBUTE.

As provided in more detail below, this EULA grants you two licenses: 1) a license to use the SOFTWARE to develop other software products (the "Development License"); and 2) a license to use and/or distribute the Developed Software (the "Distribution License"). Both of these licenses (individually and collectively, the "Licenses") are explained and defined in more detail below.

1.

Definitions. The following terms have the respective meanings as used in this EULA:

"Network Server" means a computer with one or more computer central processing units (CPU's) that operates for the purpose of serving other computers logically or physically connected to it, including, but not limited to, other computers connected to it on an internal network, intranet or the Internet. "Web Server" means a type of Network Server that serves other computers more particularly connected to it over an intranet or the Internet.

"Developed Software" means those computer software products that are developed by or through the use of the SOFTWARE. "Developed Web Server Software" means those Developed Software products that reside logically or physically on at least one Web Server and are operated (meaning the computer software instruction set is carried out) by the Web Server's central processing unit(s) (CPU). "Developed Legacy Software" means those Developed Software products that are not Developed Web Server Software, including, for example, stand-alone applications and applications accessed by a file server only. "Redistributable Files" means the SOFTWARE files or other portions of the SOFTWARE that are provided by C1 and are identified as such in the Documentation for distribution by you with the Developed Software. "Developer" means a human being or any other automated device using the SOFTWARE in accordance with the terms and conditions of this EULA.

"Developer Seat License" means that each Developer using or otherwise accessing the programmatic interface or the SOFTWARE must obtain the right to do so by purchasing a separate End User License. "Network Server CPU License" means that a separate End User License must be purchased for each CPU operating the computer software at issue in the reference.

“Source Code” shall mean computer software code or programs in human readable format, such as a printed listing of such a program written in a high-level computer language. The term "Source Code" includes, but is not limited to, documents and materials in support of the development effort of the SOFTWARE, such as flow charts, pseudo code and program notes.

2.

Your Development License. You are hereby granted a limited, royalty-free, non-exclusive right to use the SOFTWARE to design, develop, and test Developed Software, on the express condition that, and only for so long as, you fully comply with all terms and conditions of this EULA.

The SOFTWARE is licensed to you on a Developer Seat License basis.

The Developer Seat License means that you may perform a single install of the SOFTWARE for use in designing, testing and creating Developed Software by a single Developer on a single computer with a single set of input devices, so long as such computer is used only by one Developer. Conversely, you may not install or use the SOFTWARE on a computer that is a network server or a computer at which the SOFTWARE is used by more than one Developer. You may not network the SOFTWARE or any component part of it, where it is or may be used by more than one Developer unless you purchase an additional Development License for each Developer. You must purchase another separate license to the SOFTWARE in order to add additional developer seats, whether the additional developers are accessing the SOFTWARE in a stand-alone environment or on a computer network. If the SOFTWARE is used to create Developed Web Server Software, then you may perform a single install of the SOFTWARE for use in designing, testing and creating Developed Web Server Software by a single Developer on a single computer or Network Server, either with a single CPU only. An additional Network Server CPU License is required for each additional CPU on the single computer or Network Server, as the case may be, upon which the SOFTWARE and/or the Developed Web Server Software is installed and a separate license for each separate computer. That is, for Developed Web Server Software, if the computer or Network Server operating the SOFTWARE has 2 CPU's, then you would need to purchase one additional Network Server CPU License (beyond the one Developer Seat License granted in this EULA).

In all cases, you may not use C1's name, logo, or trademarks to market your Developed Software without the express written consent of C1; (b) you must include the following C1 copyright notice in your Developed Software documentation and/or in the "About Box" of your Developed Software, and wherever the copyright/rights notice is located in the Developed Software (“Portions Copyright © ComponentOne, LLC 1991-2002. All Rights Reserved.”); (c) agree to indemnify, hold harmless, and defend C1, its suppliers and resellers, from and against any claims or lawsuits, including attorney's fees that may arise from the use or distribution of your Developed Software; (d) you may use the SOFTWARE only to create Developed Software that is significantly different than the SOFTWARE.

3.

Your Distribution License.

a. License to Distribute Developed Legacy Software. Subject to the terms and conditions in this EULA, you are granted the license to use and to distribute Developed Legacy Software on a royalty-free basis, provided that the Developed Legacy Software incorporates the SOFTWARE as an integral part of the Developed Software in machine-language compiled format (customarily an ".exe", or ".dll", etc.). You may not distribute, bundle, wrap or subclass the SOFTWARE as Developed Software which, when used in a "designtime" development environment, exposes the programmatic interface of the SOFTWARE. You may distribute, on a royalty-free basis, Redistributable Files with Developed Legacy Software only.

b. License to Distribute Developed Web Server Software. Subject to the terms and conditions in this EULA, you are granted the license to use and to distribute Developed Web Server Software, provided that you must purchase one Network CPU License for each CPU operating the Developed Web Server Software (and/or Redistributable Files called or otherwise used directly by the Developed Web Server Software). You may purchase an additional Network CPU License by purchasing an additional separate End User License for the SOFTWARE; one Network CPU License is included in this EULA. Notwithstanding the foregoing, however, you may distribute or transfer, free of royalties, the Redistributable Files (and/or any Developed Legacy Software) to the extent that they are used separately on a single CPU on the client/workstation side of the network served by the Web Server.

4.

Specific Product Limitations. Notwithstanding anything in this EULA to the contrary, if the license you have purchased is for any of the following products, then the following additional limitations will apply:

a. C1 ReportDesigner. C1ReportDesigner includes at least: 1) one dynamic link library (c1.win.c1reportdesigner.dll) file known as C1ReportDesigner Component, 2) one executable (ReportDesigner.exe) file known as C1ReportDesigner Application and, 3) the Source Code of the C1ReportDesigner Application. The C1ReportDesigner Component is subject to the general terms and restrictions set forth in this EULA. The C1ReportDesigner Application is an executable file used to design and prepare reports; the C1ReportDesigner Application may be distributed, free of royalties, only in conjunction with the Developed Software.

Subject to the terms and conditions in this EULA, C1 hereby grants you the right to use the C1ReportDesigner Application Source Code. You are hereby also granted the right to modify such Source Code and to create derivative works that are based on the licensed Source Code. You may distribute the derivative works that you develop, solely in object code format and exclusively in conjunction with and/or as a part of the Developed Software. You are expressly not granted the right to distribute, disclose or otherwise make available to any third party the licensed Source Code, any modified version, derivative work, or any portion thereof, in source code format.

C1 shall retain all right, title and interest in and to the licensed Source Code, and all C1 updates, modifications or enhancements thereof. Nothing herein shall be deemed to transfer any ownership or title rights in and to the licensed Source Code from C1 to you.

SOURCE CODE IS LICENSED TO YOU AS IS. C1 DOES NOT AND SHALL NOT PROVIDE YOU WITH ANY TECHNICAL SUPPORT FOR YOUR SOURCE CODE LICENSE.

b. VS View Reporting Edition. VS View Reporting Edition includes at least one executable file listed as “VSRpt7.exe”, known as “Designer.” The file "VSRpt7.exe”, or any upgrade or future versions of the Designer, are subject to the restrictions set forth in this EULA and may not be distributed with your Developed Software or in any other way.

c. VSForum. VSForum is intended to be installed on a Network Server. C1 grants to you the following rights to the SOFTWARE: a) Installation: You may install one copy of the SOFTWARE on a single Network Server; b) Use: When installed and initialized, the SOFTWARE creates a database file which contains the embodiment of a discussion forum (the database hereinafter referred to as the "Forum"). You may use the SOFTWARE to create one Forum on one Network Server only, which server may be connected at any point to an unlimited number of workstations or computers operating on one or more networks. You are specifically NOT LICENSED to create or operate multiple Forums. To create or to operate more than one FORUM, you must purchase one additional SOFTWARE license for each additional Forum.

d. Doc-to-Help. You may use Doc-To-Help to create online help, manuals or other documentation in electronic or printed format (the "Output Documents"). You may distribute and incorporate in such Output Documents those files identified in the documentation as Redistributable Files. Except for those specific Redistributable Files, you MAY NOT distribute the SOFTWARE, in any format, to others.

e. Studio Products. You may not share the component parts of the Studio Products licensed to you with other Developers, nor may you allow the use and/or installation of such components by other Developers.

5.

Updates/Upgrades; Studio Subscription. Subject to the terms and conditions of this EULA, the Licenses are perpetual. Updates and upgrades to the SOFTWARE may be provided by C1 from time-to-time, and, if so provided by C1, are provided upon the terms and conditions offered at that time by C1 in its sole discretion. C1 may provide updates and upgrades to the SOFTWARE for free or for any charge, at any time or never, and through its chosen manner of access and distribution, all in C1's sole and complete discretion.

C1 licenses certain of its separately-licensed products bundled together in a product suite, called the C1 "Studio" product line (the "Studio Products"). The exact separately-licensed products that are bundled into the Studio Products may change from time-to-time in C1's sole discretion. If the SOFTWARE is identified as a C1 "Studio" product, then the SOFTWARE is one of the Studio Products. The SOFTWARE and the Studio Products are revised from time-to-time (meaning, for example, revised with updates, upgrades and, in the case of Studio products, possibly changes to which specific products are included in the bundle). For you to be entitled to receive any such revisions to the SOFTWARE or the Studio Products, as the case may be, you must have a valid SOFTWARE license or a valid Studio subscription. The original purchaser of the SOFTWARE or of a Studio product receives a one-year subscription from the date of purchase of the SOFTWARE. After one year, the Studio subscription and/or the SOFTWARE license must be renewed to continue to be entitled to receive the SOFTWARE and/or the Studio Products revisions as the case may be.

6.

Serial Number. Within the packaging of the SOFTWARE, a unique serial number (the "Serial Number") is included, which allows for the registration of the SOFTWARE. The Serial Number is subject to the restrictions set forth in this EULA and may not be disclosed or distributed either with your Developed Software or in any other way. The disclosure or distribution of the Serial Number shall constitute a breach of this EULA, the effect of which shall be the automatic termination and revocation of all the rights granted herein.

7.

Evaluation Copy. If you are using an "evaluation copy" or similar version, specifically designated as such by C1 on its website or otherwise, then the Licenses are limited as follows: a) you are granted a license to use the SOFTWARE for a period of thirty (30) days counted from the day of installation (the "Evaluation Period"); b) upon completion of the Evaluation Period, you shall either i) delete the SOFTWARE from the computer containing the installation, or you may ii) contact C1 or one of its authorized dealers to purchase a license of the SOFTWARE, which is subject to the terms and limitations contained herein; and c) any Developed Software may not be distributed or used for any commercial purpose.

III. INTELLECTUAL PROPERTY.

1.

Copyright. You agree that all right, title, and interest in and to the SOFTWARE (including, but not limited to, any images, photographs, animations, video, audio, music, text, and “applets” incorporated into the SOFTWARE), and any copies of the SOFTWARE, and any copyrights and other intellectual properties therein or related thereto are owned exclusively by C1, except to the limited extent that C1 may be the rightful license holder of certain third-party technologies incorporated into the SOFTWARE. The SOFTWARE is protected by copyright laws and international treaty provisions. The SOFTWARE is licensed to you, not sold to you. C1 reserves all rights not otherwise expressly and specifically granted to you in this EULA.

2.

Backups. You may either: (a) copy the SOFTWARE solely for backup or archival purposes; or (b) install the SOFTWARE on a single computer, provided you keep the original solely for backup or archival purposes. Notwithstanding the foregoing, you may not copy the Documentation.

3.

General Limitations. You may not reverse engineer, decompile, or disassemble the SOFTWARE, except and only to the extent that applicable law expressly permits such activity notwithstanding this limitation.

4.

Software Transfers. You may not rent or lease the SOFTWARE. You may transfer the SOFTWARE to another computer, provided that it is completely removed from the computer from which it was transferred. You may permanently transfer all of your rights under the EULA, provided that you retain no copies, that you transfer all the SOFTWARE (including all component parts, the media and printed materials, any dates, upgrades, this EULA and, if applicable, the Certificate of Authenticity), and that the recipient agrees to the terms and conditions of this EULA as provided herein. If the SOFTWARE is an update or upgrade, any transfer must include all prior versions of the SOFTWARE.

5.

Termination. Without prejudice to any other rights it may have, C1 may terminate this EULA and the Licenses if you fail to comply with the terms and conditions contained herein. In such an event, you must destroy all copies of the SOFTWARE and all of its component parts.

6.

Export Restrictions. You acknowledge that the SOFTWARE is of U.S. origin. You acknowledge that the license and distribution of the SOFTWARE is subject to the export control laws and regulations of the United States of America, and any amendments thereof, which restrict exports and re-exports of software, technical data, and direct products of technical data, including services and Developed Software. You agree that you will not export or re-export the SOFTWARE or any Developed Software, or any information, documentation and/or printed materials related thereto, directly or indirectly, without first obtaining permission to do so as required from the United States of America Department of Commerce's Bureau of Export Administration ("BXA"), or other appropriate governmental agencies, to any countries, end-users, or for any end-uses that are restricted by U.S. export laws and regulations, and any amendments thereof, which include, but are not limited to, the following:

Restricted Countries: Restricted Countries currently include, but are not necessarily limited to Cuba, Iran, Iraq, Libya, Montenegro, North Korea, Serbia, Sudan, and Syria.

Restricted End-Users: Any End-User whom you know or have reason to know will use SOFTWARE or Developed Software in the design, development, or production of missiles and missile technology, nuclear weapons and weapons technology, or chemical and biological weapons. Any national of any of the Restricted Countries, wherever located, who intends to transmit or transport the SOFTWARE or Developed Software to one of the Restricted Countries.

Restricted End-Uses: Any use of SOFTWARE and Developed Software related to the design, development, or production of missiles and missile technology, nuclear weapons and weapons technology, or chemical and biological weapons.

These restrictions change from time to time. You represent and warrant that neither the BXA nor any other United States federal agency has suspended, revoked or denied your export privileges. C1 acknowledges that it shall use reasonable efforts to supply you with all reasonably necessary information regarding the SOFTWARE and its business to enable you to fully comply with the provisions of this Section. If you have any questions regarding your obligations under United States of America export regulations, you should contact the Bureau of Export Administration, United States Department of Commerce, Exporter Counseling Division, Washington DC. U.S.A. (202) 482-4811, http://www.bxa.doc.gov.

7.

U.S. Government Restricted Rights. The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. For solicitations issued before December 1, 1995, by the United States of America, its agencies and/or instrumentalities (the "Government"), other than the Department of Defense, the use, duplication or disclosure of the software and documentation provided to the Government under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights clause at 48 CFR ch.1 52.227-19. For solicitations issued before September 29, 1995, by the Department of Defense, the use, duplication or disclosure of the software and documentation provided under this EULA shall be subject to the RESTRICTED RIGHTS as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 48 CFR ch.2 252.227-7013. You will comply with any requirements of the Government to obtain such RESTRICTED RIGHTS protection, including without limitation, the placement of any restrictive legends on the SOFTWARE, and any license agreement used in connection with the distribution of the SOFTWARE. Manufacturer is ComponentOne, LLC, 4516 Henry Street, Suite 501, Pittsburgh, Pennsylvania 15213 USA. For solicitations issued by the Government on or after December 1, 1995 and the Department of Defense on or after September 29, 1995, the only rights provided in the software and documentation provided herein shall be those contained in this EULA. Under no circumstances shall C1 be obligated to comply with any Governmental requirements regarding the submission of or the request for exemption from submission of cost or pricing data or cost accounting requirements. For any distribution of the SOFTWARE that would require compliance by C1 with the Government's requirements relating to cost or pricing data or cost accounting requirements, you must obtain an appropriate waiver or exemption from such requirements for the benefit of C1 from the appropriate Government authority before the distribution and/or license of the SOFTWARE to the Government.

IV. WARRANTIES AND REMEDIES.

1.

Limited Warranty. C1 warrants that the original media, if any, are free from defects for ninety (90) days from the date of delivery of the SOFTWARE. EXCEPT AS OTHERWISE PROVIDED IN THE PRECEDING SENTENCE, AND TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, C1 EXPRESSLY DISCLAIMS ANY WARRANTY FOR THE SOFTWARE, DOCUMENTATION AND ANYTHING ELSE PROVIDED BY C1 HEREBY AND C1 PROVIDES THE SAME IN “AS IS” CONDITION WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION REMAINS WITH YOU. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS WHICH VARY FROM STATE TO STATE.

2.

Limited Remedy. C1's entire liability and your exclusive remedy under this EULA shall be, at C1's sole option, either (a) return of the price paid for the SOFTWARE; (b) repair the SOFTWARE through updates distributed online or otherwise in C1's discretion; or (c) replace the SOFTWARE with its reasonable, provided that you return the SOFTWARE in the same manner as provided in Section I.2 for return of the SOFTWARE for non-acceptance of this EULA. Any media for any repaired or replacement SOFTWARE will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. THESE REMEDIES ARE NOT AVAILABLE OUTSIDE OF THE UNITED STATES OF AMERICA. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL C1 BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFIT, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF C1 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES IN CERTAIN CASES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

V. MISCELLANEOUS.

1.

This is the Entire Agreement. This EULA (including any addendum or amendment to this EULA included with the SOFTWARE) is the final, complete and exclusive statement of the entire agreement between you and C1 relating to the SOFTWARE. This EULA supersedes any prior and contemporaneous proposals, purchase orders, advertisements, and all other communications in relation to the subject matter of this EULA, whether oral or written. No terms or conditions, other than those contained in this EULA, and no other understanding or agreement which in any way modifies these terms and conditions, shall be binding upon the parties unless entered into in writing executed between the parties, or by other non-oral manner of agreement whereby the parties objectively and definitively act in a manner to be bound (such as by continuing with an installation of the SOFTWARE, "clicking-through" a questionnaire, etc.) Employees, agents and other representatives of C1 are not permitted to orally modify this EULA.

2.

You Indemnify C1. You agree to indemnify, hold harmless, and defend C1 and its suppliers and resellers from and against any and all claims or lawsuits, including attorney's fees, that arise or result from this EULA.

3.

Interpretation of this EULA. If for any reason a court of competent jurisdiction finds any provision of this EULA, or any portion thereof, to be unenforceable, that provision of this EULA will be enforced to the maximum extent permissible so as to effect the intent of the parties, and the remainder of this EULA will continue in full force and effect. Formatives of defined terms shall have the same meaning of the defined term. Failure by either party to enforce any provision of this EULA will not be deemed a waiver of future enforcement of that or any other provision. Except as otherwise required or superseded by law, this EULA is governed by the laws of the Commonwealth of Pennsylvania, without regard to its conflict of laws principles. The parties consent to the personal jurisdiction and venue of the Commonwealth of Pennsylvania, in the County of Allegheny, and agree that any legal proceedings arising out of this EULA shall be conducted solely in such Commonwealth. If the SOFTWARE was acquired outside the United States, then local law may apply.


Redistributable Files

VSView8 is royalty-free. You may include copies of the OCX files with as many copies of as many applications you ship. If you work with other developers, you may be interested in ComponentOne's site licenses. Call us for details.

To distribute your application, you will probably need to create a set up utility. This utility will take care of detecting the files your application needs to run (EXEs, DLLs, OCXs, and others), compressing these files and later copying them to the user's computer, and also dealing with details such as potential version conflicts, component registration, etc. We recommend you use the Set Up Wizard that ships with Microsoft Visual Basic or a professional program such as Wise or InstallShield.

If you haven't yet registered your copy of VSView8 and would like to do it now, please use the enclosed order form or visit http://www.componentone.com/.


Technical Support

ComponentOne VSView is developed and supported by ComponentOne LLC, a company formed by the merger of APEX Software Corporation and VideoSoft. You can obtain technical support using any of the following methods:


ComponentOne Web site

The ComponentOne Web site at www.componentone.com provides a wealth of information and software downloads for VSView users, including:

•

Descriptions of the various support options available through the ComponentOne Service Team.

•

Answers to frequently asked questions (FAQ's) about our products, organized by functionality. Please consult the FAQ's before contacting us directly, as this can save you time and also introduce you to other useful information pertaining to our products.

•

Free product updates, which provide you with bug fixes and new features.


Internet E-mail

For technical support through the Internet, e-mail us at:

support.vsview@componentone.com

To help us provide you with the best support, please include the following information when contacting ComponentOne:

•

Your ComponentOne product serial number.

•

The version and name of your operating system.

•

Your development environment and its version.

For more information on technical support, go to:

www.componentone.com/support


Peer-to-Peer Newsgroup

ComponentOne also sponsors peer-to-peer newsgroups for users. ComponentOne does not offer formal technical support in this newsgroup, but instead sponsors it as a forum for users to post and answer each other's questions regarding our products. However, ComponentOne may monitor the newsgroups to ensure accuracy of information and provide comments when necessary. You can access the newsgroup from the ComponentOne Web site at http://www.componentone.com/newsgroups.


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, 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 in the distribution CD.

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.


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, etc.

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.

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

Using Unit-Aware Properties

Visual C++ Topics

VSPrinter Utilities - VPUtil


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.

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

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 (e.g. 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's a relatively minor inconvenience. (And one that can be avoided, read on).

If you take a 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()

{

// Wizard-generated code

. . .

// TODO: Add extra initialization here

// 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. There are a couple of issues that deserve additional explaining (at least our tech support department gets many questions on these): 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()

{

// 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");

COleVariant vNone(0L, VT_ERROR);

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 (e.g., 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:

1) 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.

2) 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 vNone(0L, VT_ERROR);

COleVariant v1in(1440L);

m_Printer.DrawLine(v1in, v1in, vNone, vNone);

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

COleVariant vNone(0L, VT_ERROR);

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

}

}

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 "Insert|New ATL Object…" menu option, 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).

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

// wizard-generated code . . .

/////////////////////////////////////////////////////////////////

//

extern "C" int WINAPI _tWinMain(HINSTANCE hInstance,

HINSTANCE /*hPrevInstance*/,

LPTSTR lpCmdLine, int /*nShowCmd*/)

{

// wizard-generated code . . .

CMyDlg dlg; // create the dialog

dlg.DoModal(); // show the dialog

//MSG msg; // comment these lines out

//while (GetMessage(&msg, 0, 0, 0))

// DispatchMessage(&msg);

// wizard-generated code . . .

}

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:

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, no 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:

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:

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

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

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.


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

VSPrinter Tutorial - Calendar

VSDraw Tutorial - Chart

VSPrinter Examples


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, then add the following controls to the main form:

•

A ComponentOne VSPrinter 8 control (from VSPrint8.OCX),

•

A Microsoft CommonDialog control (from ComDlg32.OCX), and

•

Three command buttons.

Set the Name property of the controls to the following:

•

VSPrinter control to vp,

•

CommonDialog control to dlg, and

•

Command buttons to cmdOpen, cmdPrint, and cmdSetup.

Set the Caption property of the command buttons to the following:

•

&Open…

•

&Print, and

•

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:

Step 2: Opening Files

Double click on the Open… button, and add the following code to the 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$

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$

On Error Resume Next

Open FileName For Input As #1

sText = Input$(LOF(1), 1)

Close #1

On Error GoTo 0

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.

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

On Error Resume Next

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:

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.

Set the Name property of the controls to the following:

•

VSPrinter control to vp, and

•

Command buttons to cmdPrev, cmdNext, cmdPrint, and cmdHTML.

Set the Caption property of the command buttons to the following:

•

<<

•

>>,

•

&Print, and

•

View &HTML.

Set the form's Caption property to "VSPrinter Calendar".

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.

Private Sub Form_Load()

' 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

' 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, that 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.

' 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(tcFontBold, 0) = True

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

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, etc.

' done, render the table

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

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 add this 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 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's 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 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

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.

Step 6: Final touches

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:

Private Sub Form_Resize()

On Error Resume Next

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 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, then add the following controls to the main form:

•

A ComponentOne VSDraw control (from VSVIEW7.OCX),

•

A CheckBox control, and

•

Two command buttons.

Set the Name property of the controls to the following:

•

VSDraw control to vd,

•

CheckBox control to chk, and

•

Command buttons to cmdPie, and cmdBar.

Set the Caption property of the command buttons to the following:

•

&Pie Chart and

•

&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, then call a general-purpose pie drawing routine. Double-click on the Pie Chart button and add the following code to the 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)

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, 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 rocket science 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)

For i = 0 To UBound(ChartData, 2)

' 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

' 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

For i = 0 To UBound(ChartData, 2)

' set color

.BrushColor = ChartData(2, i)

' calculate arc

arc = Abs(ChartData(0, i)) / tot * 2 * Pi

a = start + arc / 2

' get slice origin

cx = .ScaleWidth / 2

cy = .ScaleWidth / 2

' 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

'---------------------------------------------

' set up to draw slice labels

.TextAlign = tadCenter

.TextColor = vbWhite

.FontBold = True

.FontSize = Radius / 10

'---------------------------------------------

' draw slice labels

start = 0

For i = 0 To UBound(ChartData, 2)

' calculate arc

arc = Abs(ChartData(0, i)) / tot * 2 * Pi

a = start + arc / 2

' get slice origin

cx = .ScaleWidth / 2

cy = .ScaleWidth / 2

' 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 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

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

For i = 0 To UBound(ChartData, 2)

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

.BrushStyle = bsSolid

.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 > 300 Then stp = 100

If max > 3000 Then stp = 1000

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

.BrushStyle = bsSolid

barwid = 1000 / 2 / (UBound(ChartData, 2) + 1)

'---------------------------------------------

' draw bars

.TextAlign = tadLeft

.TextAngle = -900

.TextColor = vbWhite

.FontBold = True

For i = 0 To UBound(ChartData, 2)

' 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

That's it. The application can already draw pie and bar charts. We're almost done now.

Step 4: Final touches

We will add our standard Form_Resize event handler to make the VSDraw control resize with the form. Here it is:

Private Sub Form_Resize()

On Error Resume Next

With vd

.Move .Left, .Top, _

ScaleWidth - 2 * .Left, _

ScaleHeight - .Top - .Left

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 control's 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:

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, etc) 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 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 a an interesting sample you would like to share with others, or a suggestion for one, please let us know.

Page n of m

Shaded Table

Table Formatting

Data-based Tables

Custom NavBar Button

Find Text

Build an Index

Build a Table of Contents


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 expensive 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).


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

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

Add the following code to initialize the form and controls:

Private Sub Form_Load()

' 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

Now we are almost done. The only thing missing is the main routine, the one that renders the recordset. The RenderRecordset routine below 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(tcFontBold, 0) = True

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)

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 picture below:

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:

•

VSPrinter control (name it vp)

•

Two Image controls (name them img(0) and img(1))

•

Two PictureBox controls (name them picBtn(0) and picBtn(1))

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:

Private Sub Form_Load()

' 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

Private Sub Form_Resize()

On Error Resume Next

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 FrameBtn routine below 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:

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, _

Shift As Integer, X As Single, Y As Single)

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, _

Shift As Integer, X As Single, Y As Single)

If Button <> 1 Then Exit Sub

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:

•

VSPrinter control (name it vp)

•

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:

Private Sub Form_Load()

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:

•

VSPrinter control (name it vp)

•

CommandButton control (name it btnDoIt).

Next, you will need two external files:

•

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

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 picture below shows what a typical index looks like:


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:

•

VSPrinter control (name it vp)

•

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

' create ith header with header tag

s = GetRandomTitle()

.Styles.Apply "Heading"

.StartTag "H1|" & i & "|" & s

.Paragraph = i & " " & s

.EndTag

' create some text

s = GetRandomText()

.Styles.Apply "Normal"

.Paragraph = s

Next

' create TOC

.NewPage

pgTOC = .PageCount

.Styles.Apply "Heading"

.Paragraph = "Random Document" & vbCrLf & "Table of Contents"

.Styles.Apply "Normal"

.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. The it builds the table of contents by searching the document for the heading tags ("H1|1", "H1|2", etc.) using the FindTag property. For each tag found, the code uses the RetrieveTag property to retrieve the full tag text, 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

' 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

If Button <> 2 Then Exit Sub

' 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", "|")

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 picture below. Try tracing through the code to see exactly how the tags work.


Control Reference

VSPrinter Control

VSDraw Control

VSViewPort Control

VSPDF Control


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 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 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.
*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 (e.g. 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.
*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.
*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.
*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 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, X2, and Y2 properties.
*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
*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 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

AbortTextButton Property

AbortTextDevice Property

AbortTextPage Property

AbortWindow Property

AbortWindowPos Property

AccessibleDescription Property (VSPrinter)

AccessibleName Property (VSPrinter)

AccessibleRole Property (VSPrinter)

AccessibleValue Property (VSPrinter)

Action Property (VSPrinter)

ArchiveInfo Property

AutoLinkNavigate Property

AutoRTF Property

BrushColor Property (VSPrinter)

BrushStyle Property (VSPrinter)

CalcParagraph Property

CalcPicture Property

CalcTable Property

CalcText Property

CalcTextRTF Property

Collate Property

ColorMode Property

Columns Property

ColumnSpacing Property

Copies Property

CurrentColumn Property

CurrentLine Property

CurrentPage Property

CurrentX Property

CurrentY Property

DefaultDevice Property

Device Property

Devices Property

DocName Property

DPI Property

Draw Property (VSPrinter)

Driver Property

Duplex Property

EmptyColor Property (VSPrinter)

Error Property

ErrorDescription Property

ExportFile Property

ExportFormat Property

ExportNavBar Property

ExportRaw Property

FileName Property

FindTag Property

FindText Property

Footer Property

hDC Property

HdrColor Property

HdrFont Property

Header Property

IndentFirst Property

IndentLeft Property

IndentRight Property

IndentTab Property

LargeChangeHorz Property (VSPrinter)

LargeChangeVert Property (VSPrinter)

LineSpacing Property (VSPrinter)

LoadPicture Property

MarginBottom Property

MarginFooter Property

MarginHeader Property

MarginLeft Property

MarginRight Property

MarginTop Property

Measure Property

Measuring Property

NavBar Property

NavBarColor Property

NavBarMenuText Property

NavBarText Property

Navigation Property

NDevices Property

NPorts Property

Orientation Property

OutputFileName Property

PageBorder Property

PageCount Property

PageHeight Property (VSPrinter)

PageWidth Property (VSPrinter)

PalettePicture Property

PaperBin Property

PaperBins Property

PaperHeight Property

PaperSize Property

PaperSizes Property

PaperWidth Property

Paragraph Property

PenColor Property (VSPrinter)

PenStyle Property (VSPrinter)

PenWidth Property (VSPrinter)

PhysicalPage Property

Picture Property (VSPrinter)

Polygon Property (VSPrinter)

Polyline Property (VSPrinter)

Port Property

Ports Property

Preview Property

PreviewPage Property

PreviewPages Property

PrintQuality Property

ProportionalBars Property (VSPrinter)

ReadyState Property

RenderControl Property

RetrieveTag Property

RetrieveText Property

ScaleOutput Property

ScrollLeft Property (VSPrinter)

ScrollTop Property (VSPrinter)

ShowGuides Property

SmallChangeHorz Property (VSPrinter)

SmallChangeVert Property (VSPrinter)

SpaceAfter Property

SpaceBefore Property

Styles Property

Table Property

TableBorder Property

TableCell Property

TablePen Property

TablePenLR Property

TablePenTB Property

TableSep Property

Text Property (VSPrinter)

TextAlign Property (VSPrinter)

TextAngle Property (VSPrinter)

TextColor Property (VSPrinter)

TextHei Property

TextHeight Property (VSPrinter)

TextRTF Property

TextWid Property

TextWidth Property (VSPrinter)

Track Property (VSPrinter)

TrueType Property

TwipsPerPixelX Property

TwipsPerPixelY Property

URL Property

Version Property (VSPrinter)

X1 Property (VSPrinter)

X2 Property (VSPrinter)

Y1 Property (VSPrinter)

Y2 Property (VSPrinter)

Zoom Property (VSPrinter)

ZoomMax Property

ZoomMin Property

ZoomMode Property (VSPrinter)

ZoomStep Property


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

VSPrinter Control


AbortTextButton Property

Returns or sets the caption for the button in the default Abort dialog.

Syntax

[form!]VSPrinter.AbortTextButton[ = 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

"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 property allows you to customize the appearance of the default Abort dialog. This is especially useful for developers working with languages other than English.

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

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

"on the %s on %s"

See Also


AbortTextPage Property

Returns or sets the caption for the Page string in the default Abort dialog.

Syntax

[form!]VSPrinter.AbortTextPage[ = 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.

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

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

"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 picture below shows the layout of the automatic Abort dialog and the default captions for each element on it.

Data Type

Boolean

See Also


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


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:

Constant | Value | Description
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.
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 below.
Index% | Optional zero-based index that specifies which file in the archive should be processed.

Valid settings for the Info parameter are:

Constant | Value | Description
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.

For example, the code below lists the contents of an archive file.

Private Sub ArcList(fn$)

Dim i%, cnt%

With vp

On Error Resume Next

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.

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

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.

The settings for the BrushStyle property are described below:

Constant | Value | Description
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.
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

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.

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:

Constant | Value | Description
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:

Constant | Value | Description
cmMonochrome | 1 | Print in black and white.
cmColor | 2 | Print in color.

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

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

Data Type

Variant

Default Value

180

See Also


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.

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

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


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.

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

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.

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

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.

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 code below 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

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

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

Constant | Value | Description
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


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:

Constant | Value | Description
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.

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

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 ]

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.

The code below 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 topic.

Notes:

1.

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.

2.

You cannot export a document after it has been created. The output must be generated while the document is being created.

3.

Remember to reset the ExportFile property when you are done creating each document, to avoid accidentally overwriting the file.

4.

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:

Constant | Value | Description
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 option results in larger HTML files, but all paragraph formatting is included in the document.
vpxPagedHTML | 2 | Similar to vpxPlainHTML, but the creates several hyperlinked HTML files.
vpxPagedDHTML | 3 | Similar to vpxDHTML, but the creates several hyperlinked DHTML files.
vpxRTF | 4 | Causes the control to generate RTF output.

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) = "<!-- navbar beg -->" & _

"<p><font face=Arial size=2><b>" & _

"<a%s>[&lt;&lt;]</a> <a%s>[&lt;]</a>" & _

"&nbsp;&nbsp; Page %d of %d &nbsp;&nbsp;" & _

"<a%s>[&gt;]</a> <a%s>[&gt;&gt;]</a>" & _

"</b></font></p>" & _

"<!-- navbar end -->"

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 code below 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>" & _

"&nbsp;&nbsp; This is the top of page %d of %d &nbsp;&nbsp;" & _

"<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>&nbsp;&nbsp;&nbsp;" & _

"Page %d of %d&nbsp;&nbsp;&nbsp;&nbsp;</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 code below 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 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

' 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 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".

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

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 code below 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 (e.g. "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.

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

[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 (e.g. "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

.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

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

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 diagram below 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.

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

Data Type

Variant

See Also


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.

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

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.

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

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

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 (e.g. 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 table below 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 (e.g. "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 topic.

Data Type

Variant

Default Value

100

See Also


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

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

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.

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

For a diagram showing the effect of the Margin properties, see the MarginLeft property.

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.

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

For a diagram showing the effect of the Margin properties, see the MarginLeft property.

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.

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

The diagram below shows the effect of the Margin properties:

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.

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

For a diagram showing the effect of the Margin properties, see the MarginLeft property.

Data Type

Variant

Default Value

1440

See Also


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.

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

For a diagram showing the effect of the Margin properties, see the MarginLeft property.

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.

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:

Constant | Value | Description
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 diagram below 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.

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"

To fully localize the VSPrinter control, you should also set the following properties: AbortCaption, AbortTextButton, AbortTextDevice, and AbortTextPage.

NOTE: Setting this property to an empty string restores it default value.

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 code below 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:

Constant | Value | Description
vpnvNone | 0 | No built-in navigation.
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.

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:

Constant | Value | Description
orPortrait | 0 | The page is rendered in Portrait mode (tall).
orLandscape | 1 | The page is rendered in Landscape mode (wide).

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.

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:

Private Sub Command1_Click()

Dim i%

With vp

' start in portrait mode

.Orientation = orPortrait

.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

.Orientation = orPortrait

.NewPage

For i = 1 To 10

.Paragraph = i & ": This is portrait mode."

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


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 picture below 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


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.

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:

Constant | Value | Description
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.
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.

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.

You can determine which bins are available on the current device by reading the PaperBins property. For example, the code below 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.

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:

Constant | Value | Description
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.
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
pprEnvC3 | 29 | Envelope C3, 324 x 458 mm
pprEnvC4 | 30 | Envelope C4, 229 x 324 mm
pprEnvC6 | 31 | Envelope C6, 114 x 162 mm
pprEnvC65 | 32 | Envelope C65, 114 x 229 mm
pprEnvB4 | 33 | Envelope B4, 250 x 353 mm
pprEnvB5 | 34 | Envelope B5, 176 x 250 mm
pprEnvB6 | 35 | Envelope B6, 176 x 125 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 code below 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

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.

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.

Graphical objects are created using the Draw and Polygon properties as well as the DrawRectangle, DrawCircle, and DrawEllipse methods. The pen is also used to outline text boxes drawn using the TextBox method when the Shade parameter is set to True.

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

The PenColor, PenStyle, and PenWidth properties define the pen used to outline 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 settings for the PenStyle property are described below:

Constant | Value | Description
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.

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

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.

Graphical objects are created using the Draw and Polygon properties as well as the DrawRectangle, DrawCircle, and DrawEllipse methods. The pen is also used to outline text boxes drawn using the TextBox method when the Shade parameter is set to True.

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

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} ]

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 code below shows the difference between the two settings:

Private Sub Command1_Click()

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 picture below shows the output generated by the code when PhysicalPage is set to True and to False:

Data Type

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.

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

vp.StartDoc

vp.Polygon = "1000 1000, 2000 1000, 2000 2000, 1000 2000"

vp.EndDoc

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.

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 code below 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.

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 code below 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

DoPrinting

End Sub

For more details on creating and printing documents, see the VSPrinter Basic Operation topic.

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


PrintQuality Property

Returns or sets the print quality.

Syntax

[form!]VSPrinter.PrintQuality[ = PrintQualitySettings ]

Remarks

Valid settings for the PrintQuality property are described below:

Constant | Value | Description
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.

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

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

The values returned by the ReadyState property are described below:

Constant | Value | Description
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 code below 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 code below 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

</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 code below 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, etc.

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

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

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 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 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 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 code below 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

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

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.

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.

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:

Constant | Value | Description
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 picture below shows what the preview page looks like with and without the guides:

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

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.

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

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.

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

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

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:

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 code below 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

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 picture below 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)

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:

Parameter | Description
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.

Constant | Value | Description
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.
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:

Constant | Value | Description
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.

Column Properties: These settings affect entire columns or column ranges. The Row1 and Row2 parameters are ignored:

Constant | Value | Description
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:

Constant | Value | Description
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.
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 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 topic.

The example below 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

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

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.

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

See the TablePen property for more details and an example.

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

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.

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

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

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 code below 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


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:

Constant | Value | Description
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.

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 show below:

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


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 code below 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 code below 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.

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


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:

Constant | Value | Description
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.

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

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


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 etc). 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 example below 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"

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.

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 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 ]

See the X1 property.

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 ]

See the X1 property.

Data Type

Variant

See Also


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.

Syntax

[form!]VSPrinter.ZoomMin[ = 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

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:

Constant | Value | Description
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 pictures below show the effect of each setting on the control's appearance:

ZoomMode = zmThumbnail

ZoomMode = zmTwoPages

ZoomMode = zmWholePage

ZoomMode = zmPageWidth

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

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

25

See Also


VSPrinter Methods

AddLink Method

AddLinkTarget Method

AddTable Method

AddTableArray Method

Archive Method

Clear Method (VSPrinter)

ClientToPage Method (VSPrinter)

DrawCircle Method (VSPrinter)

DrawEllipse Method (VSPrinter)

DrawLine Method (VSPrinter)

DrawPicture Method (VSPrinter)

DrawRectangle Method (VSPrinter)

EndDoc Method

EndOverlay Method

EndTable Method

EndTag Method

GetMargins Method

KillDoc Method

LoadDoc Method (VSPrinter)

MovePages Method

NewColumn Method

NewPage Method

PageToClient Method (VSPrinter)

PrintDialog Method

PrintDoc Method (VSPrinter)

PrintFile Method

SaveDoc Method (VSPrinter)

ScrollIntoView Method

StartDoc Method

StartOverlay Method

StartTable Method

StartTag Method

TextBox Method


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 (e.g. "http://www.componentone.com") or local reference (e.g. "#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


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 lists 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 on using unit-aware measurements, see the Using Unit-Aware Properties topic.

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.

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 (e.g. 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, etc. 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 (e.g. "{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 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 ]

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 topic and the Data-based Tables 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:

Parameter | Description
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 below.

Valid settings for the Action parameter are:

Constant | Value | Description
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:

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 code below 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


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:

Parameter | Description
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.

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.

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

Parameter | Description
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.

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.

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

The Start and End parameters are measured counter-clockwise, starting from the 3 o'clock position.

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

Parameter | Description
Picture | Picture to draw. May be a reference to a bitmap, icon, or metafile.
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 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

vp.DrawPicture Picture1, "2in", "2in", "100%", "100%"

' draw a picture, scale to twice the natural size

vp.DrawPicture Picture1, "2in", "2in", "200%", "200%"

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

Constant | Value | Description
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).

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


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:

Parameter | Description
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.

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.

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

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

' done, render the table

vp.EndTable

For a complete example, see the VSPrinter Tutorial - Calendar topic.

See Also


EndTag Method

Ends the definition of a document tag started with StartTag.

Syntax

[form!]VSPrinter.EndTag

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.

For details on the mechanics of creating VSPrinter documents, see the VSPrinter Basic Operation topic.

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.

The parameters for the LoadDoc method are described below:

Parameter | Description
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


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:

Constant | Value | Description
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, 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 (e.g. device, paper size, orientation, margins, copies, etc). 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:

' ** 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:

Parameter | Description
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 (e.g. "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.

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:

Parameter | Description
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")

' ** 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:

Parameter | Description
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 example.

See Also


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

' done, render the table

vp.EndTable

For a complete example, see the VSPrinter Tutorial - Calendar topic.

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

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. For details and examples about creating and using tags, see the Build an Index 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

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:

Parameter | Description
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.
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

AfterHeader Event

AfterTableCell Event

AfterUserPage Event

AfterUserScroll Event

AfterUserZoom Event

BeforeFooter Event

BeforeHeader Event

BeforeTableCell Event

BeforeUserPage Event

BeforeUserScroll Event

BeforeUserZoom Event

EndDoc Event

EndPage Event

Error Event

LayoutThumbnails Event

LoadingDoc Event

MouseLink Event

NewColumn Event

NewLine Event

NewPage Event

ReadyStateChange Event

ResetDC Event

SavingDoc Event

StartDoc Event


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.

These events allow you to customize margins, fonts, and other characteristics for the footers. Make the changes during the BeforeHeader event and restore the control state during the AfterHeader event.

See Also


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


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 of the NavBar and Navigation properties.

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 of the NavBar and Navigation properties.

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.

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


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.

These events allow you to customize margins, fonts, and other characteristics for the footers. Make the changes during 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 of the NavBar and Navigation properties.

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 of the NavBar and Navigation properties.

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 of the NavBar and Navigation properties.

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

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

Parameter | Description
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)

Remarks

The parameters for the LoadingDoc event are described below:

Parameter | Description
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 Escape 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:

Parameter | Description
Link | String containing the link target (e.g., "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.

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.

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:

Parameter | Description
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.

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 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 actions such as clear, show, and print.
Appearance | See the Visual Basic documentation.
BackColor | See the Visual Basic documentation.
*BackStyle | Returns or sets whether text is transparent or opaque.
BorderStyle | See the Visual Basic documentation.
*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, X2, and Y2 properties.
*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 property when the user clicks the scroll bar area.
*LineSpacing | Returns or sets the line spacing as a percentage (e.g. 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 property when the user clicks the scroll arrow.
*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.
*Version | Returns the version of the control currently loaded.
*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.
*Refresh | See the Visual Basic documentation.
*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

Click | See the Visual Basic documentation.
DblClick | See the Visual Basic documentation.
KeyDown | See the Visual Basic documentation.
KeyPress | See the Visual Basic documentation.
KeyUp | See the Visual Basic documentation.
MouseDown | See the Visual Basic documentation.
MouseMove | See the Visual Basic documentation.
MouseUp | See the Visual Basic documentation.
*Scroll | Fired after the control scrolls its contents.


VSDraw Properties

AccessibleDescription Property (VSDraw)

AccessibleName Property (VSDraw)

AccessibleRole Property (VSDraw)

AccessibleValue Property (VSDraw)

Action Property (VSDraw)

BackStyle Property

BrushColor Property (VSDraw)

BrushStyle Property (VSDraw)

Draw Property (VSDraw)

EmptyColor Property (VSDraw)

KeepTextAspect Property

LargeChangeHorz Property (VSDraw)

LargeChangeVert Property (VSDraw)

LineSpacing Property (VSDraw)

MouseScroll Property (VSDraw)

PageHeight Property (VSDraw)

PageWidth Property (VSDraw)

PenColor Property (VSDraw)

PenStyle Property (VSDraw)

PenWidth Property (VSDraw)

Picture Property

Polygon Property (VSDraw)

Polyline Property (VSDraw)

ProportionalBars Property (VSDraw)

ScaleHeight Property

ScaleLeft Property

ScaleTop Property

ScaleWidth Property

ScrollLeft Property (VSDraw)

ScrollTop Property (VSDraw)

SmallChangeHorz Property (VSDraw)

SmallChangeVert Property (VSDraw)

Text Property (VSDraw)

TextAlign Property (VSDraw)

TextAngle Property (VSDraw)

TextColor Property (VSDraw)

TextHeight Property (VSDraw)

TextWidth Property (VSDraw)

Track Property (VSDraw)

Version Property (VSDraw)

X1 Property (VSDraw)

X2 Property (VSDraw)

Y1 Property (VSDraw)

Y2 Property (VSDraw)

Zoom Property (VSDraw)

ZoomMode Property (VSDraw)


AccessibleDescription Property (VSDraw)

Gets or sets the description of the control used by accessibility client applications.

Syntax

Property AccessibleDescription As String

Data Type

String

See Also

VSDraw Control


AccessibleName Property (VSDraw)

Gets or sets the name of the control used by accessibility client applications.

Syntax

Property AccessibleName As String

Data Type

String

See Also

VSDraw Control


AccessibleRole Property (VSDraw)

Gets or sets the role of the control used by accessibility client applications.

Syntax

Property AccessibleRole As Variant

Data Type

Variant

See Also

VSDraw Control


AccessibleValue Property (VSDraw)

Gets or sets the value of the control used by accessibility client applications.

Syntax

Property AccessibleValue As String

Data Type

String

See Also

VSDraw Control


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:

Constant | Value | Description
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

VSDraw Control


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:

Constant | Value | Description
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

VSDraw Control


BrushColor Property (VSDraw)

Returns or sets the brush color.

Syntax

[form!]VSDraw.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.

Data Type

Color

See Also

VSDraw Control


BrushStyle Property (VSDraw)

Returns or sets the brush style.

Syntax

[form!]VSDraw.BrushStyle[ = BrushStyleSettings ]

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.

Data Type

BrushStyleSettings (Enumeration)

Default Value

bsSolid (0)

See Also

VSDraw Control


Draw Property (VSDraw)

Draws an object within the rectangle defined by the X1, Y1, X2, and Y2 properties.

Syntax

[form!]VSDraw.Draw = DrawSettings

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

Constant | Value | Description
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

VSDraw Control


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

VSDraw Control


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

VSDraw Control


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

Default Value

300

See Also

VSDraw Control


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

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Double

Default Value

300

See Also

VSDraw Control


LineSpacing Property (VSDraw)

Returns or sets the line spacing as a percentage (e.g. 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

VSDraw Control


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

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Boolean

Default Value

True

See Also

VSDraw Control


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

VSDraw Control


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

0

See Also

VSDraw Control


PenColor Property (VSDraw)

Returns or sets the pen color.

Syntax

[form!]VSDraw.PenColor[ = colorref& ]

Remarks

The PenColor, PenStyle, and PenWidth properties define the pen used to outline 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.

Data Type

Color

See Also

VSDraw Control


PenStyle Property (VSDraw)

Returns or sets the pen style.

Syntax

[form!]VSDraw.PenStyle[ = PenStyleSettings ]

Remarks

The PenColor, PenStyle, and PenWidth properties define the pen used to outline 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 settings for the PenStyle property are described below:

Constant | Value | Description
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.

Data Type

PenStyleSettings (Enumeration)

Default Value

psSolid (0)

See Also

VSDraw Control


PenWidth Property (VSDraw)

Returns or sets the pen width, in logical units.

Syntax

[form!]VSDraw.PenWidth[ = value As Double ]

Remarks

The PenColor, PenStyle, and PenWidth properties define the pen used to outline 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 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

VSDraw Control


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

VSDraw Control


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"

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.

The Polygon property draws closed shapes. To draw open shapes, use the Polyline property instead.

Data Type

String

See Also

VSDraw Control


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

VSDraw Control


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

VSDraw Control


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

VSDraw Control


ScaleLeft Property

Returns or sets the horizontal coordinate for the left edge of the drawing.

Syntax

[form!]VSDraw.ScaleLeft[ = 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.

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.

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

VSDraw Control


ScaleTop Property

Returns or sets the vertical coordinate for the top edge of the drawing.

Syntax

[form!]VSDraw.ScaleTop[ = 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.

For more details and a diagram, see the ScaleHeight property.

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

VSDraw Control


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

All drawing on the VSDraw control is done in an arbitrary coordinate system, determined by the ScaleWidth, ScaleHeight, ScaleLeft and ScaleTop properties.

For more details and a diagram, see the ScaleHeight property.

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

VSDraw Control


ScrollLeft Property (VSDraw)

Returns or sets the left coordinate of the visible area, in twips.

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.

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Double

See Also

VSDraw Control


ScrollTop Property (VSDraw)

Returns or sets the top coordinate of the visible area, in twips.

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.

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Double

See Also

VSDraw Control


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 ]

Remarks

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Double

See Also

VSDraw Control


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

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Double

See Also

VSDraw Control


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

VSDraw Control


TextAlign Property (VSDraw)

Returns or sets the text alignment.

Syntax

[form!]VSDraw.TextAlign[ = DrawTextAlignSettings ]

Remarks

The settings for the TextAlign property are described below:

Constant | Value | Description
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

VSDraw Control


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

VSDraw Control


TextColor Property (VSDraw)

Returns or sets the text color.

Syntax

[form!]VSDraw.TextColor[ = colorref& ]

Data Type

Color

See Also

VSDraw Control


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

VSDraw Control


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

VSDraw Control


Track Property (VSDraw)

Returns or sets whether scrolling occurs as the user drags the scroll thumb.

Syntax

[form!]VSDraw.Track[ = {True | False} ]

Remarks

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

Data Type

Boolean

Default Value

True

See Also

VSDraw Control


Version Property (VSDraw)

Returns the version of the control currently loaded.

Syntax

val% = [form!]VSDraw.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

VSDraw Control


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

VSDraw Control


X2 Property (VSDraw)

Returns or sets the right coordinate of the rectangle used with the Draw property.

Syntax

[form!]VSDraw.X2[ = value As Double ]

See the X1 property.

Data Type

Double

See Also

VSDraw Control


Y1 Property (VSDraw)

Returns or sets the top coordinate of the rectangle used with the Draw property.

Syntax

[form!]VSDraw.Y1[ = value As Double ]

See the X1 property.

Data Type

Double

See Also

VSDraw Control


Y2 Property (VSDraw)

Returns or sets the bottom coordinate of the rectangle used with the Draw property.

Syntax

[form!]VSDraw.Y2[ = value As Double ]

See the X1 property.

Data Type

Double

See Also

VSDraw Control


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

VSDraw Control


ZoomMode Property (VSDraw)

Sets or returns the zoom mode (explicit percentage or one of the automatic settings).

Syntax

[form!]VSDraw.ZoomMode[ = ZoomModeSettings ]

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:

Constant | Value | Description
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 Control


VSDraw Methods

Clear Method (VSDraw)

ClientToPage Method (VSDraw)

Copy Method

DrawCircle Method (VSDraw)

DrawEllipse Method (VSDraw)

DrawLine Method (VSDraw)

DrawPicture Method (VSDraw)

DrawRectangle Method (VSDraw)

LoadDoc Method (VSDraw)

PageToClient Method (VSDraw)

PrintDoc Method (VSDraw)

SaveDoc Method (VSDraw)

SetPageExtent Method

Show Method


Clear Method (VSDraw)

Resets the control and discards its contents.

Syntax

[form!]VSDraw.Clear

See Also

VSDraw Control


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.

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

VSDraw Control

PageToClient Method (VSDraw)


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

VSDraw Control


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:

Parameter | Description
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.

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.

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 are specified in scale units, defined by the ScaleWidth, ScaleHeight, ScaleLeft, and ScaleHeight properties.

The Start and End parameters are measured counter-clockwise, starting from the 3 o'clock position.

See Also

VSDraw Control


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:

Parameter | Description
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.

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.

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 are specified in scale units, defined by the ScaleWidth, ScaleHeight, ScaleLeft, and ScaleHeight properties.

The Start and End parameters are measured counter-clockwise, starting from the 3 o'clock position.

See Also

VSDraw Control


DrawLine Method (VSDraw)

Draws a line segment.

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

VSDraw Control


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, ScaleLeft, and ScaleHeight properties.

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

VSDraw Control


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:

Parameter | Description
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.

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.

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

VSDraw Control


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

VSDraw Control


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

VSDraw Control

ClientToPage Method (VSDraw)


PrintDoc Method (VSDraw)

Updates the drawing and copies it to the printer.

Syntax

[form!]VSDraw.PrintDoc

See Also

VSDraw Control


SaveDoc Method (VSDraw)

Saves a VSDraw document (metafile) to disk.

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

VSDraw Control


SetPageExtent Method

Sets the PageWidth and PageHeight properties.

Syntax

[form!]VSDraw.SetPageExtent PageWidth As Double, PageHeight As Double

See Also

VSDraw Control


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 Control


VSDraw Events


Scroll Event (VSDraw)

Fired after the control scrolls its contents.

Syntax

Private Sub VSDraw_Scroll()

Remarks

Scrollbars are visible only if the PageWidth, PageHeight, and Zoom properties are set to non-zero values.

See Also

VSDraw Control


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 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 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.
Appearance | See the Visual Basic documentation.
*AutoScroll | Returns or sets whether contents are scrolled automatically by the control.
BackColor | See the Visual Basic documentation.
BorderStyle | See the Visual Basic documentation.
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 property when the user clicks the scroll bar area.
*LargeChangeVert | Returns or sets the amount of change to the VirtualTop property when the user clicks the scroll bar area.
MouseIcon | See the Visual Basic documentation.
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 property when the user clicks the scroll arrow.
*SmallChangeVert | Returns or sets the amount of change to the VirtualTop property when the user clicks the scroll arrow.
*Track | Returns or sets whether scrolling occurs as the user drags the scroll thumb.
*Version | Returns the version of the control currently loaded.
*VirtualHeight | Returns or sets the height of the 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

*Refresh | See the Visual Basic documentation.
*SetVirtualExtent | Sets the VirtualWidth and VirtualHeight properties to fit the contained controls.

Events

Click | See the Visual Basic documentation.
DblClick | See the Visual Basic documentation.
MouseDown | See the Visual Basic documentation.
MouseMove | See the Visual Basic documentation.
MouseUp | See the Visual Basic documentation.
*Scroll | Fired after the control scrolls its contents.


VSViewPort Properties

AccessibleDescription Property (VSViewPort)

AccessibleName Property (VSViewPort)

AccessibleRole Property (VSViewPort)

AccessibleValue Property (VSViewPort)

AutoScroll Property

FocusMarginLeft Property

FocusMarginTop Property

FocusTrack Property

LargeChangeHorz Property (VSViewPort)

LargeChangeVert Property (VSViewPort)

MouseScroll Property (VSViewPort)

Picture Property (VSViewPort)

ProportionalBars Property (VSViewPort)

SmallChangeHorz Property (VSViewPort)

SmallChangeVert Property (VSViewPort)

Track Property (VSViewPort)

Version Property (VSViewPort)

VirtualHeight Property

VirtualLeft Property

VirtualTop Property

VirtualWidth Property


AccessibleDescription Property (VSViewPort)

Gets or sets the description of the control used by accessibility client applications.

Syntax

Property AccessibleDescription As String

Data Type

String

See Also

VSViewPort Control


AccessibleName Property (VSViewPort)

Gets or sets the name of the control used by accessibility client applications.

Syntax

Property AccessibleName As String

Data Type

String

See Also

VSViewPort Control


AccessibleRole Property (VSViewPort)

Gets or sets the role of the control used by accessibility client applications.

Syntax

Property AccessibleRole As Variant

Data Type

Variant

See Also

VSViewPort Control


AccessibleValue Property (VSViewPort)

Gets or sets the value of the control used by accessibility client applications.

Syntax

Property AccessibleValue As String

Data Type

String

See Also

VSViewPort Control


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

VSViewPort Control


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

VSViewPort Control


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

Default Value

0

See Also

VSViewPort Control


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 (e.g. 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

VSViewPort Control


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

VSViewPort Control


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

VSViewPort Control


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

VSViewPort Control


Picture Property (VSViewPort)

Returns or sets a picture to be used as a background for the control.

Syntax

[form!]VSViewPort.Picture[ = Picture ]

Remarks

If used, the picture is stretched to fill the entire virtual area.

Data Type

Picture

See Also

VSViewPort Control


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

VSViewPort Control


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

VSViewPort Control


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

VSViewPort Control


Track Property (VSViewPort)

Returns or sets whether scrolling occurs as the user drags the scroll thumb.

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

VSViewPort Control


Version Property (VSViewPort)

Returns the version of the control currently loaded.

Syntax

val% = [form!]VSViewPort.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

VSViewPort Control


VirtualHeight Property

Returns or sets the height of the 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

Double

Default Value

1000

See Also

VSViewPort Control


VirtualLeft Property

Returns or sets the left coordinate of the visible area, in twips.

Syntax

[form!]VSViewPort.VirtualLeft[ = 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.

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

0

See Also

VSViewPort Control


VirtualTop Property

Returns or sets the top coordinate of the visible area, in twips.

Syntax

[form!]VSViewPort.VirtualTop[ = 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.

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

VSViewPort Control


VirtualWidth Property

Returns or sets the width of the scrollable area, in twips.

Syntax

[form!]VSViewPort.VirtualWidth[ = 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

Double

Default Value

1000

See Also

VSViewPort Control


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 Control


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

VSViewPort Control


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

Author Property

Compress Property

Creator Property

Index Property

Keywords Property

LinkTag Property

Name Property

Object Property

OutlineTag Property

Parent Property

Subject Property

Tag Property

Title Property


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


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

VSPDF Control


Compress Property

Gets or sets the type of element that should be compressed.

Syntax

Property Compress As CompressSettings

Data Type

CompressSettings Enumeration

See Also

VSPDF Control


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

VSPDF Control


Index Property

Returns/sets the number identifying a control in a control array.

Syntax

Property Index As Integer

Data Type

Integer

See Also

VSPDF Control


Keywords Property

Gets or sets the keywords associated with the PDF document.

Syntax

Property Keywords As String

Data Type

String

See Also

VSPDF Control


LinkTag Property

Gets or sets the tag prefix to use for building hyperlinks.

Syntax

Property LinkTag As String

Data Type

String

See Also

VSPDF Control


Name Property

Returns the name used in code to identify an object.

Syntax

Property Name As String

Data Type

String

See Also

VSPDF Control


Object Property

Returns an object in a control.

Syntax

Property Object As Object

Data Type

Object

See Also

VSPDF Control


OutlineTag Property

Gets or sets the tag prefix to use for building outlines.

Syntax

Property OutlineTag As String

Data Type

String

See Also

VSPDF Control


Parent Property

Returns the object on which this object is located.

Syntax

Property Parent As Object

Data Type

Object

See Also

VSPDF Control


Subject Property

Gets or sets the subject of the PDF document.

Syntax

Property Subject As String

Data Type

String

See Also

VSPDF Control


Tag Property

Stores any extra data needed for your program.

Syntax

Property Tag As String

Data Type

String

See Also

VSPDF Control


Title Property

Gets or sets the title of the PDF document.

Syntax

Property Title As String

Data Type

String

See Also

VSPDF Control


VSPDF Methods

ConvertDocument Method

ConvertDocumentRange Method

ConvertFile Method

ConvertFileRange Method


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

VSPDF Control


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

VSPDF Control


ConvertFile Method

Converts an existing VSPrinter document into a PDF file.

Syntax

Sub ConvertFile(VSPrinterFile As String, PDFFile As String)

See Also

VSPDF Control


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

VSPDF Control