EasyPrint
Manual
Contents
NeededPages_Horizontal, NeededPages_Vertical
WantedPages_Horizontal, WantedPages_Vertical
The following END USER LICENSE AGREEMENT applies to the EasyPrint ActiveX software package (the “SOFTWARE”).
This End-User license Agreement ("EULA”) is a legal agreement between you (the “USER” - either an individual or a single entity) and Gil Shalit (the “AUTHOR”) for the use of the SOFTWARE. By installing, copying, or otherwise using the SOFTWARE, you agree to be bound by the terms of this EULA.
The trial (Shareware) version of this software may be used for evaluation purposes at the USER's own risk for a period of 30 days from the date of installation. At the end of the trial period, the USER must either purchase a license (register) to continue using the software, or remove it from his/her system. Software developed using the trial version must not be distributed to end-users for profit or otherwise, except so far as this is for demonstration purposes
Registered (Commercial) Version
GRANT OF LICENSE. The SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as by other intellectual property laws and treaties. The SOFTWARE is licensed, not sold. You may install and use the SOFTWARE on a single computer to design, develop, and test software application products ("Application").
COPYRIGHT. All right, title, and copyright in and to the SOFTWARE and any copies of the SOFTWARE, are owned by the AUTHOR. The SOFTWARE is protected by copyright laws and international treaty provisions. Therefore, 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. You may not copy the printed materials which might accompany the SOFTWARE.
LIMITED WARRANTY. The AUTHOR warrants that in the case of a CDROM disk being sent to you, the original distribution media is free from defects for 90 days from the date of delivery of the SOFTWARE. This limited warranty does not apply in the case of online download of the SOFTWARE.
NO OTHER WARRANTIES. To the maximum extent permitted by applicable law, the AUTHOR expressly disclaims any warranty for the SOFTWARE. The SOFTWARE and any related documentation is provided "as is" without warranty of any kind, either express or implied, including, without limitation, the implied warranties or merchantability of fitness for a particular purpose. The entire risk arising out of use or performance of the SOFTWARE remains with you.
LIMITATION OF LIABILITY AND CUSTOMER REMEDIES. The AUTHOR’s entire liability and your exclusive remedy under this EULA shall be, at the AUTHOR’s option, either (a) return of the price paid for the SOFTWARE or (b) replacement of the SOFTWARE which does not meet the AUTHOR’s Limited Warranty and which is returned to the AUTHOR’s with a copy of your receipt. Any replacement SOFTWARE will be warranted for the remainder of the original warranty period or 30 days, whichever is longer.
NO LIABILITY FOR CONSEQUENTIAL DAMAGES. To the maximum extent permitted by applicable law, in no event shall the AUTHOR 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 this product, even if the AUTHOR 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, the above limitation may not apply to you.
The manual
is best viewed in MSWord 2000 to get full use of the hypertext links liberally
sprinkled throughout the text. Or
you can open Manual.htm in you browser of choice and get the same
functionality.
This is the format for code snippets in the text.
The
installation file places my demo “EasyPrint Demo.vbp” in the same directory as
this manual, as well as the code
for the three forms:
·
frmTest
frmTest is a small graphical application. It contains a PictureBox (pb) which can be resized, on which a grid is
drawn every time it is resized. A
Toolbar (tb) allows the drawing of rectangles, lines,
text boxes and an MSChart on pb.
To draw one of those objects,
press the appropriate button at the upper left corner of the required
area and then at the lower right corner and the object will be drawn.
frmTest contains an instance of EasyPrint and the ‘Printer Setup’ and
‘Preview’ tb buttons set the control’s properties and
call the other forms for printing or previewing.
The ‘Print’ button sends pb to be printed with the currently selected
properties of EasyPrint.
·
frmPreview
frmPreview is my implementation of the EasyPrint preview
capabilities. It displays all the
picture objects returned from calling epPrint at the Form_Load event and in the
PreviewRefresh method. There are
many other possible implementations, like displaying the pictures one at a
time, or letting the user decide how many to display (like MSWord does). With EasyPrint you are the boss!
·
frmPrinterSetup
frmPrinterSetup gives the user access to all of the EasyPrint features. As a developer you can allow access to a subset of these features or you can implement them differently, or you can use code to set the features the way you want them and allow no user intervention. . With EasyPrint you really are the boss!
If you
like my implementations of
page-and-printer-setup and preview forms then put the frmPrintSetup and
frmPreview forms in your Template folder so you can click for a new form and
get PrintSetup and Preview as options in all your new applications.
You are in
a hurry… You have no time to read a description of printing or previewing, browse the demo, or send me an inquiring EMail. You want it to work
NOW. Here are your options:
Put an
EasyPrint control on your form. At
runtime, set the PictureSource
property to the PictureBox which contains the graphics you want to print (after
creating them) and have a MenuItem or button activate the epPrint method. This is all you need for your (possibly huge and complex)
PictureBox to be printed on the default printer, on the correct number of pages
required for the job!
Put an
EasyPrint control on your form.
Add my frmPreview and frmPrintSetup forms from the demo program to your project and make a tiny
code adjustment in each (see the Form_Load event code on each form for
details). Set the PictureSource
property to your PictureBox at runtime and have a MenuItem or button show
either the frmPreview or frmPrintSetup forms. You now have an application with full print preview and
printer setup capabilities!
Follow
the steps in Quick and full featured and then start making
changes, improvements and adjustments to the way I’ve implemented EasyPrint in
my demo program. Make it work for
you the way you want it to! If you
like this approach, you might want to put the frmPreview and frmPrintSetup
forms in your Template folder so you can click for a new form and get
PrintSetup and Preview as options in all your new applications.
Printing is
what EasyPrint all about. So
before listing all the properties, methods and events in EasyPrint, here’s a description of what EasyPrint does and what you,
the developer, need to do to make it happen.
EasyPrint
takes a PictureBox and sends it to the printer (or to a previewing form). The PictureBox is your graphics canvas – you place all the
controls, graphical method output, text and background images on the
PictureBox. Using a PictureBox as
a canvas for a graphical application instead of drawing directly on a form has
the advantage that a PictureBox can be as large as you wish while a form can
only be as large as the computer screen.
You can see an example of this in my demo.
After
creating your graphics on a PictureBox, you tell EasyPrint to prepare it for
output by setting the PictureSource property to your PictureBox. This is all it takes for EasyPrint to
be ready to print or preview your creation!
You can
preset margins, captions with different formats, number of pages to
be used in the horizontal and vertical dimensions or a zoom level. Or, you can provide the users of your application with
standard windows screens to choose all of these settings by themselves. Additionally you can provide the
printer’s setup dialog,
directly from your application!
To print, simply
call the epPrint
method. Your output will be divided into the required number of
pages, expanded or shrunken, have margins and captions added to it and sent to
the selected printer.
Preview
screens have become a standard, almost required, feature in windows
applications. Providing such a
screen in a VB application is not easy, to say the least. But EasyPrint makes it as easy as can
be!
This is how
it works: Prepare your PictureBox
and set PictureSource to it in the same way you would for printing.
Call epPrint with a single variant argument. Instead of printing, epPrint will
create a StdPicture object for each page to be printed. Each picture is a replica of the page,
with the graphical output, the margins and the captions set in EasyPrint. The pictures are returned in an array
contained in the epPrint argument.
Note: A StdPicture object is a standard VB object
and is used as the source in PaintPicture operations. This means you can almost anything with the array of
pictures returned from epPrint.
How you use
the preview pictures is up to you.
You can display them one at a time, or all on the same form. See my demo for my implementation. You
can allow the user to make changes to the EasyPrint settings like margins, captions, number of pages to
be used in the horizontal and vertical dimensions or the zoom level. Call epPrint again and display the new pictures it returns
to see the effect of the changes.
Once you
have the array of pictures for each of the pages to be printed, you can add an
option for the user of your application to print just one of the pages. To do
so use:
Printer.PaintPicture PicturePreviews(w,h),0,0
where PicturePreviews
is the variant array containing the stdPicture objects, w is the index of the
wanted picture in the horizontal dimension and h in the vertical
dimension. Because the pictures
where prepared to print on the current printer, you only need to specify the
coordinates of the upper left corner of the printable area (0,0).
Another
feature you can implement is saving page images to files – simply call SavePicture
with one if the array elements and save it as a bitmap.
SavePicture PicturePreviews(w,h),FileName
where PicturePreviews is the variant array containing the stdPicture objects, w is the index of the wanted picture in the horizontal dimension and h in the vertical dimension and FileName is the full path of the file to be created, with a .bmp extension.
Boolean,
Read/Write.
Works with epPrint when sending to the printer.
If False (default), the
whole picture is sent to the printer.
If True, each page of the picture is sent to the printer as a separate
print job, to prevent the printer choking on large print jobs.
Boolean,
Read/Write.
Works with epPrint when sending to the printer. Set to False each time epPrint is
called. If set to True while
epPrint is sending pages to the printer, the printing job will be cancelled at
the next page to be printed.
Indicates if the PictureSource was set successfully and AddControls executed correctly (only if it was
called). Should be checked before printing or previewing.
If True - you can proceed to print or preview, if False, do not proceed.
Boolean,
Read/Write.
Determines
how the control handles errors. If
True (default), a trapped error in the control will pop a MessageBox with the error message in addition to firing the ErrorMsg Event. If False, only the
event will be fired.
It is
recommended that this property kept True during development, so all error
messages will be displayed, but changed to False in the finished application so
the end user is not faced with (to him) cryptic messages.
PictureBox,
Write only.
These
properties are used to set the Header and Footer strings as well as their
alignment, font, color, size and style.
The TextBox which is passed for each of the properties is treated as a
“caption object” and it’s properties are used to format the respective
caption.
Example: to have a Header with the string “My
Print Job” print at the center top of each page, create a TextBox on your form
with the string as it’s caption, set it’s alignment to ‘Center’ and choose it’s
font, size, style (bold, italic etc.) and ForeColor. After passing this TextBox to the HeaderText property, each
page will have the desired header.
Changes
made to the TextBox after passing it to the HeaderText or FooterText properties
have no effect on the output!
The header
is printed at the highest position possible on the page, depending on the
selected printer. Likewise, the footer is printed at the
extreme lower end of the page. You
might need to set the appropriate Margin so the caption is not printed on the content (picture).
See also: GetCaptionTexts
Array of
Single, Read/Write.
Margin is
an array of four single precision numbers which determine the margins on all
four sides of the printed page.
The array index is of the eDirections enumeration. The unit of measurement is determined by Margin_Mode.
When Margin_Mode is changed, all margins are recalculated to the new
unit system.
Example: to
set the left margin to 1 use:
EasyPrint.Margin(epLeft)=1
The margins
are measured from the edge of the printable area, determined by the selected printer.
So if the selected printer leaves at least 0.4 inch at the top of the
page, a statement like Margin(epTop)=0.5 will result in the output beginning 0.9 inch from the top of the page.
Valid
values for the margins are between 0 and about 1/3 of the respective printable
dimension, e.g.: the right margin can be between 0 and 2.5 inch if the printable width is 7.5
inch.
eMarginScale
enumeration, Read/Write.
Determines
the units for the Margin property. The enumeration corresponds to the VB constants
VBCentimeters and VBInches. When
changed, all margins are recalculated to reflect the new units.
Integer,
Read only.
Returns the
number of pages in the horizontal or vertical dimensions, needed to print the
picture in PictureSource on the
current printer, with the margin settings. The numbers are recalculated when either the margins, the
current printer or the printer’s properties are changed.
See also: NeededPagesChanged.
PictureBox,
Write only.
Pass
EasyPrint.PictureSource the PictureBox that should be previewed and printed. All the graphics, text,
contained controls (see AddControls) and
background images on it will be prepared for output. After setting PictureBox, check CanPrint to see if you can proceed to print or preview.
String. Read/Write.
Used by the
host application to let EasyPrint know if the Printer object was changed. At startup, EasyPrint will use the
default printer for output. If the
host changes it’s printer, it must tell EasyPrint about the change, as in:
Set Printer = Printers(Some_Index)
EasyPrint.PrinterDeviceName = Printer.DeviceName
The string
passed to PrinterDeviceName must be identical to the way it appears in the
printer object, so it is advisable to use similar code as shown above.
ePrintingMethod
enumeration, Read/Write.
PrintingMethod
determines how epPrint will output
when either printing
or previewing.
The options are:
Allows the user to determine the number of
pages in the horizontal or vertical dimensions, which will be used to print the
picture in PictureSource on the current printer, with margin settings. The numbers are recalculated When PrintingMethod = epZoomed and epPrint is called.
See also: WantedPagesChanged.
Single. Read/Write.
Determines
the zoom ratio used by epPrint if PrintingMethod = epZoomed. A ratio of 300 means the output will be
enlarged three fold, and a ratio of 70 will result in output 70 percent of the
original size. 100 means no
change.
Valid
values for the ZoomRatio are between 10 and 500.
Syntax:
EasyPrint.AddControls (ControlsToPrint)
ControlsToPrint
is a comma separated list
of one or more controls.
EasyPrint
does a better job then all the other printing solutions in reproducing a
complex PictureBox with several controls contained in it (as well as all the
other graphics on it). Some
controls are more difficult then others to capture - certain controls do not
print correctly when placed on the PictureBox which is set to PictureSource.
They either leave a blank square where they are supposed to appear or do
not show at all. These are mostly
complex graphical controls, like the MSChart. These controls must be added separately after setting
PictureSource.
Addcontrol
is used to add these controls to the picture being captured in EasyPrint. The code below sets the
PictureSource, adds two charts, checks if these operations were successful and
sends the result to the printer.
Set EasyPrint.PictureSource = PictureBox1
EasyPrint.AddControls MSChart1, MSChart2
If EasyPrint.CanPrint Then
EasyPrint.epPrint
End If
If you plan
on using a new control on your PictureBox which you intend to be printed with
EasyPrint, check to see if it is captured correctly with the standard PictureSource. If not, add it with AddControls.
Syntax:
EasyPrint.epPrint ([PicturePreviews])
PicturePreviews is an optional variant argument which (if
included) will return an array of
preview pictures (see below).
epPrint
does most of the work in EasyPrint.
It is used to print (when called
without parameters) or to prepare the preview pictures (when called with the PicturePreviews parameter).
The output
of epPrint is dependant on the following settings: PrintingMethod, Margin, PrinterDeviceName
and the printer properties such as orientation and paper size, selected with ShowPrinterProperties.
If HeaderText and FooterText are set, their properties will be reflected
in the output.
The size of
the PictureBox set to PictureSource, as well as the properties in the paragraph
above, determine the number of pages epPrint will send to the printer. Alternatively, they determine the
number of pictures epPrint will return in PicturePreviews, if called with that
parameter.
BreakPrintJob
determines if all the pages are sent to the printer in one print job or
separately.
Syntax EasyPrint.GetCaptionTexts([HeaderTextBox],
[FooterTextBox])
HeaderTextBox, FooterTextBox
are the TextBoxes to which the caption object should be returned.
Captions (header and footer) are passed
between the host application and EasyPrint with the help of TextBoxes which
contain what is defined as a caption object: the text and the corresponding
font, size, alignment, color and style (bold, italic etc.).
HeaderText and FooterText are the properties used to set captions in
EasyPrint. GetCaptionTexts is used
to retrieve those settings back in the host application. When called with either parameters, or
with both, the text and other attributes of the respective captions, if those
were set previously, are retrieved.
For example
EasyPrint.GetCaptionTexts
, MyFooterTextBox
will retrieve the Footer text and other
attributes into the TextBox MyFooterTextBox, if the footer was set in
EasyPrint.FooterText earlier.
Syntax:
EasyPrint.ShowPrinterProperties
ShowPrinterProperties
is used to display the setup dialog for the current EasyPrint printer, i.e. the default printer or the printer
which was chosen by setting PrinterDeviceName.
Each printer driver installed on a PC has a different set of properties
which are accessible through it’s setup dialog, and all these properties are
available to the host application’s users by calling ShowPrinterProperties!
Some of the
changes performed in the printer setup dialog might change the NeedePages_x values,
which will fire the NeededPagesChanged event.
Syntax:
ErrorMsg(ErrMsg as String, ErrNum as Integer)
ErrMsg: Error message text.
ErrNum: Error message number.
EasyPrint
error handling depends on the ErrorMsg event. When an error is trapped in the control, ErrorMsg is fired
with ErrMsg and ErrNum for the designer to display or further act upon.
See Also: ErrorMessagesOn.
Syntax:
StatusChanged(StatusString as string)
StatusString: A string indicating a new status.
StatusChange
is fired by epPrint to indicate the progress of (long) print
jobs, or the cancellation of
print jobs. It is up to the
application developer to display such status reports.
Syntax: NeededPagesChanged()
NeededPagesChanged
is fired when at least one of the NeededPages_x values
changes. This is due to a change
in a Margin value, the selection of a different printer or changing a printer
setup property.
Syntax:
WantedPagesChanged()
WantedPagesChanged
is fired when at least one of the WantedPages_x values
changes. This is due to a change
in ZoomRatio when epPrint is called with PrintingMethod set to epZoomed.
Used in PrintingMethod and has the following members:
epOriginalSize = 1
epZoomed = 2
epWantedPagesFull = 3
epWantedPagesProportional = 4
used in Margin_Mode and has the following members:
epCentimeters = vbCentimeters (7)
epInches = vbInches (5)
Used in Margin and has the following members:
epLeft = 1
epRight = 2
epTop = 3
epBottom = 4
|
Message |
Cause |
# |
|
No
Printers Installed |
At least 1 printer must be installed on
the PC. |
1 |
|
The Object
X has no HWND |
All
controls passed to AddControls must
have an hWND. |
2 |
|
The
Object is too large to print |
In some
cases, the system resources don’t permit the setting of a huge PictureBox to PictureSource. |
3 |
|
Printing
Job Failed, try breaking job into individual pages |
Raised by
epPrint if sending a print job to printer
failed. Setting BreakPrintJob=True might solve the problem. |
4 |
|
You must
first set PictureSource before Adding Controls with AddControls |
AddControls can be
called only after Setting PictureSource. |
5 |
|
PictureSource
Must be PictureBox |
Although PictureSource is an object, it will accept only a
PictureBox. |
6 |
|
ZoomRatio
must be between 10 and 500 (Percent). |
As clear
a message as can be… |
7 |
|
Value
must be between 0 and X inches/centimeters |
Margin values must
be between 0 and about 1/3 of the corresponding printer dimension. |
8 |
|
Header
& Footer must be TextBox controls |
Although HeaderText and FooterText are objects, they will accept only
TextBoxs. |
9 |
|
X is not
a valid PrinterDeviceName |
An
incorrect PrinterDeviceName
was specified. |
10 |
|
Margin_Mode
must have an eMarginScale value |
Margin_Mode
accepts only epInches or epCentimeters as parametes |
11 |
|
Margin
Index must be of type eDirections |
Margin index must
be epLeft, epRight, epTop or epBottom. |
12 |
Registering
your own copy of EasyPrint is easy to do at:
www.visual-basic-solutions.com/easyprint/register.htm
You will be
given all the payment options:
Full
details are found on the site.
The best
place for information is the EasyPrint web site at:
www.visual-basic-solutions.com/easyprint/
Or you can
mail me at: EasyPrint@visual-basic-solutions.com
with requests for information, technical assistance or bug reports.
If you
rather use the Fax here are the numbers:
In
the US: 603-658-8847
In
the UK: 0870-167-9445