|
Ciansoft PDFBuilderX User Manual
Note: This User Manual is also available in pdf format. The pdf version is included in download files for both the trial and full versions of PDFBuilderX.
Introduction
Ciansoft PDFBuilderX is an ActiveX control that enables applications to create PDF files. This document contains comprehensive instructions on installing and using PDFBuilderX.
For further information, visit our website: www.ciansoft.com.
Alternatively, contact us by email, we will be pleased to answer your questions: info@ciansoft.com.
Getting Started
An instance of PDFBuilderX placed on a form in an application represents a single PDF document. In order to create and save a document, the following steps must be followed:
- Configure document settings such as the default page size and units of measure.
- Add pages to the document.
- Add objects to the document that are to be written on the pages. This can include images, graphics or blocks of text. These objects are referred to as "Resources".
- Draw resources onto the pages.
- Save the file to disk.
Resources are added to the document in different ways. For images, the AddImageFile function can be used to add an image from a file on disk. Graphics and blocks of text are created using the CreateGraphic or CreateText functions, with further functions then being used to draw the graphic or add the text block content.
All resources are allocated a unique identifying number. This is the return value of the function used to add or create the resource.
Resources are drawn on pages using the ApplyResource function. This function also returns a reference number, which can then be used to identify the object on the page. This reference number is used when calling functions to change the position or size of the object as it is displayed on the page.
Note that this reference number is not the same as the number that identifies resources in the document as a whole and should not be confused with it. To help clarify this issue, parameters used in functions will usually be called Resource where they refer to a resource identifier, Page where they refer to a page number and Index where they refer to an object on a page.
A resource can be used as many times as necessary, either on the same page, or on multiple pages. This is useful, for example, for setting up headers and footers on pages of a document, or for displaying an image full size on one page and as a thumbnail elsewhere in the document.
These instructions include the following sections:
- Installation.
- The Trial Version.
- Managing Pages in the Document.
Adding pages, setting page sizes, applying resources to pages and modifying the size and position of those resources as displayed on the page.
- Working with Images.
- Working with Graphics.
- Working with Text.
- General Document Functions.
Functions for setting the units of measure, saving documents to PDF files, including Document Info etc.
- Deploying an Application.
For Visual Basic users, a simple example project is included with the installation. This can be accessed from the Windows Start Menu.
Installation
The OCX file, PDFBuilderX.ocx, must be registered on the computer running the application. This should be done during the installation, but if it is not, the command line utility Regsvr32.exe can be used. This is usually found in the Windows system folder and runs using the syntax:
regsvr32 ocxname
where ocxname is the path and name of the ocx file to register. When deploying an application that uses PDFBuilderX, the ocx file will also need to be registered on the target machine. Note that the licence file, PDFBuilderX.lic, is needed to use this control in a design environment and this file must not be distributed with an application, as is confirmed in your licence agreement.
To use this control in a Visual Basic project, select Project and Components from the pull down menu. This gives a list of available controls. Select PDFBuilderX Library and click Apply. This adds the control to the component palette. The class name is "PDFDoc" and this will appear in the Object Browser where the properties and methods are listed. For other design environments, consult the documentation for importing ActiveX controls.
As an ActiveX control, PDFBuilderX can be used in a range of Windows based environments and languages. There will be slight differences in syntax especially with the use of parentheses/brackets surrounding method parameters.
The Trial Version
The trial version of PDFBuilderX is supplied as a different OCX file, called PDFBuilderXTrial.ocx, and has a separate installation programme. The trial version has all the functionality of the full version of the control. The only limitation is that each page of PDF files created using the control will have a line of text written on it indicating that trial software was used. Visit www.ciansoft.com to purchase the full version.
Managing Pages in the Document
The following functions are used to add pages to the document, to change the page sizes and to adjust the position and size of objects on a page. Note that the functions Locate, ScaleObject and Rotate can be applied to images and text, but not to graphics.
AddPage (Page As Long) - Adds a new page to the document. The position of the page in the document is defined by Page. If Page is 0, the page will be added at the end of the document. The page size is initially defined by the DefaultPageSize property, but can be modified.
PageSize (Page As Long) As TxPageSize - The size of the page referenced by Page. This is an enumerated property of type TxPageSize, the possible values of which are listed below.
|
| TxPageSize |
| psCustom: | 0 | Page size is defined by the PageWidth and PageHeight properties |
| psA4_P: (Default) | 1 | A4 Portrait (210 mm x 297 mm) |
| psA4_L: | 2 | A4 Landscape (297 mm x 210 mm) |
| psLetter_P: | 3 | Letter Portrait (8.5" x 11") |
| psLetter_L: | 4 | Letter Landscape (11" x 8.5") |
| psA3_P: | 5 | A3 Portrait (297 mm x 420 mm) |
| psA3_L: | 6 | A3 Landscape (420 mm x 297 mm) |
| psA5_P: | 7 | A5 Portrait (148.5 mm x 210 mm) |
| psA5_L: | 8 | A5 Landscape (210 mm x 148.5 mm) |
| psTabloid_P: | 9 | Tabloid Portrait (11" x 17") |
| psTabloid_L: | 10 | Tabloid Landscape (17" x 11") |
| psLegal_P: | 11 | Legal Portrait (8.5" x 14") |
| psLegal_L: | 12 | Legal Landscape (14" x 8.5") |
| psStatement_P: | 13 | Statement Portrait (5.5" x 8.5") |
| psStatement_L: | 14 | Statement Landscape (8.5" x 5.5") |
| psExecutive_P: | 15 | Executive Portrait (7.25" x 10.5") |
| psExecutive_L: | 16 | Executive Landscape (10.5" x 7.25") |
|
PageWidth (Page As Long) As Double - The width of the page referenced by Page in the units of measure currently set by the property Units.
PageHeight (Page As Long) As Double - The height of the page referenced by Page in the units of measure currently set by the property Units.
DefaultPageSize As TxPageSize - The page size that will be used for new pages as they are added to the document. (Default = psA4_P).
ApplyResource (Page As Long, Resource As Long) As Long - Applies the resource referenced by Resource to the page referenced by Page. The resource is applied using default sizing and positioning which can then be modified using the Locate or ScaleObject functions. The return value of this function indicates the index number of this specific resource on this specific page.
Locate (Page As Long, Index As Long, X As Double, Y As Double) - The object referenced by Index on the page referenced by Page will be positioned on the page. If the object is an image or a left-justified text block, its top-left corner will be at the co-ordinates X, Y measured from the bottom-left corner of the page. If the object is a centred or right-justified text block, then the co-ordinates will refer to the top-centre or top-right of the object instead.
ScaleObject (Page As Long, Index As Long, ScaleFactor As Double) - The object referenced by Index on the page referenced by Page will be scaled. ScaleFactor is a percentage value, so an object will be displayed at normal size if this value is 100. For example, to display an image as a thumbnail, one eighth of its normal size, use a ScaleFactor of 12.5, i.e., 100/8.
Rotate (Page As Long, Index As Long, Angle As Double) - The object referenced by Index on the page referenced by Page will be rotated counter-clockwise by Angle degrees. The object pivots on its top-left corner.
Working with Images
Images can be added to the document as resources either by reading image files in a supported format from disk, by copying a bitmap in memory as a bitmap handle or by reading an image stored as an array of bytes in memory.
AddImageFile (FileName As String) As Long - Adds an image from a file on disk as a resource in the document. The return value of the function is the resource identifying number. Images in the following file formats can be used: .bmp, .tif, .jpg, .png, .gif, .pcx, .psd, .wbmp. FileName is a complete path to the file including the file extension.
AddImageBMPHandle (Handle As Long) As Long - Adds an image referenced by a bitmap handle. This can be used to transfer an image to PDFBuilderX directly from another control used for processing images, without the need to save the image to disk and read it back into memory.
For example, to add an image from a VB PictureBox control, the syntax would be in the form:
Dim NewResource As Integer
NewResource = PDFDoc1.AddImageBMPHandle(Picture1.Picture.Handle)
PDFBuilderX does not take ownership of the handle unless the ReleaseBMPHandle property has been set to False, in which case the original copy of the image will be freed from memory. If an image is copied from the Image property of a VB PictureBox, the handle must not be released as the PictureBox will not clear the memory used for transferring the image and a memory leak will result. In this case, the following code should be used:
PDFDoc1.ReleaseBMPHandle = False
NewResource = PDFDoc1.AddImageBMPHandle(Picture1.Image.Handle)
It is also necessary to set the ReleaseBMPHandle property to False when transferring an image from Ciansoft TwainControlX, or from the csXImage control from Chestysoft, our recommended control for image processing. Example code for use with PDFBuilderX is as follows:
PDFDoc1.ReleaseBMPHandle = False
NewResource = PDFDoc1.AddImageBMPHandle(Twain1.BMPHandle)
AddImageBytes (ImageData As Variant) As Long - Adds an image currently held in memory as an array of bytes. This method might typically be used when images are retrieved from a database as binary data. The return value of the function is the resource identifying number.
ReleaseBMPHandle As Boolean - This property is used to determine whether the handle is released to its original owner when the AddImageBMPHandle function is used. See above examples for further explanation. (Default = True).
ImageReadNumber As Long - When adding an image resource from a TIFF file containing multiple images, ImageReadNumber indicates the number of the image in the file that is to be read. (Default = 1).
ImageCount (FileName As String) As Long - Read-only property. Gives the number of images contained within a file. FileName must be a complete path to the file, including the file extension. Reading of multiple images is only supported for TIFF files, so this will normally return the value 1 for any other files.
ImageWidth (Resource As Long) As Double - Read-only property. The width of the image resource referenced by Resource in the units of measure currently set by the property Units.
ImageHeight (Resource As Long) As Double - Read-only property. The height of the image resource referenced by Resource in the units of measure currently set by the property Units.
For most purposes, it is not necessary for the user of PDFBuilderX to be concerned about the compression algorithms used for storing images. The default behaviour of the control is appropriate for most situations.
Images stored in a PDF document will be either uncompressed or compressed using one of the following methods:
|
| TxCompressionFormat |
| cfNone: | 0 | Uncompressed. |
| cfGroup4: | 1 | CCITT Group4 compression. Used only for black and white images. |
| cfZIP: | 2 | ZIP (or Flate) compression. |
| cfJPEG: | 3 | JPEG compression. |
|
Group4 and ZIP are lossless compression methods which means that the full quality of the image is retained whilst the space occupied by the image on disk is reduced. JPEG compression is a lossy method which sacrifices some image quality for a significant reduction in size and is commonly used for full colour or greyscale photographic images.
The compression method can be set for each possible image type independently using the following properties.
CompressionBW As TxCompressionFormat - The compression method to be used for storing black and white images in the document. (Default = cfGroup4).
CompressionGray As TxCompressionFormat - The compression method to be used for storing greyscale images in the document. (Default = cfZIP).
CompressionIndexed As TxCompressionFormat - The compression method to be used for storing indexed (paletted) colour images in the document. (Default = cfZIP).
CompressionRGB As TxCompressionFormat - The compression method to be used for storing full colour images in the document. (Default = cfZIP).
UseSourceCompression As Boolean - If this is set to True, the image compression method used in the source file will be retained if possible. This is used to avoid unnecessary decoding of images to satisfy the settings of one of the other compression properties when the image is already compressed using an efficient method. (Default = True).
Working with Graphics
Graphics are drawings made up of combinations of shapes and lines. When drawing a graphic as a resource, the size of the page on which the graphic will eventually be displayed should be kept in mind. The graphic functions require that the co-ordinates of the shapes and lines on the page be specified during drawing and these co-ordinates cannot be changed using the Locate function when the graphic resource is later applied to a page. Also, the graphic cannot be resized using the ScaleObject function nor rotated using the Rotate function.
Typical uses for graphics in a document are the drawing of borders and tables.
CreateGraphic ( ) As Long - Creates a new graphic resource. The return value of the function is the resource identifying number. The value of CurrentGraphic will automatically be set to this value.
CurrentGraphic As Long - The reference number of the graphic resource that is currently in use. This must be set before any drawing is done on the graphic by using the DrawLine, Rectangle functions etc.
DrawLine (X1 As Double, Y1 As Double, X2 As Double, Y2 As Double) - Draws a line on the current graphic using the current line settings (LineWidth, LineColor etc.) from co-ordinates X1, Y1 to X2, Y2.
Rectangle (X1 As Double, Y1 As Double, X2 As Double, Y2 As Double) - Draws a rectangle on the current graphic using the current line and fill settings (LineWidth, LineColor, FillColor) with opposite corners at co-ordinates X1, Y1 to X2, Y2.
Circle (X As Double, Y As Double, R As Double) - Draws a circle on the current graphic using the current line and fill settings (LineWidth, LineColor, FillColor). The circle will be centred at X, Y and have radius R.
Ellipse (X As Double, Y As Double, RX As Double, RY As Double, Angle As Double) - Draws an ellipse on the current graphic using the current line and fill settings (LineWidth, LineColor, FillColor). The circle will be centred at X, Y and have radius RX in the X-direction, RY in the Y-direction and will be rotated counter-clockwise through Angle degrees
LineColor As OLE_COLOR - The colour to be used on the current graphic for drawing lines. (Default = Black).
LineWidth As Long - The thickness of lines drawn on the current graphic. A value of zero will give a line of the minimum thickness that can be rendered by the output device. (Default = 1).
FillColor As OLE_COLOR - The colour to be used on the current graphic for filling shapes. (Default = White).
Working with Text
Blocks of text can be added to the document as resources. Each block consists of any number of single lines of text written underneath each other. Within each line of text, a single font, font size and colour must be used, but these properties can be different for each line of text within the block. Line spacing and the maximum line width can also be varied within the block. The whole block will be positioned according to the value of TextAlign.
This means that the procedure for building a block of text should be to set the values of TextFont, TextSize, TextColor, TextLineSpacing, TextMaxWidth, TextSkewX and TextSkewY before writing the first line of text. These properties can then be changed as required before subsequent lines are written. The value of TextAlign can be set at any time prior to generating the PDF document with the SaveToFile command.
Text can be wrapped from one line to the next by setting a value for the TextMaxWidth property.
CreateText ( ) As Long - Creates a new text resource. The return value of the function is the resource identifying number. The value of CurrentText will automatically be set to this value.
CurrentText As Long - The reference number of the text resource that is currently in use. This must be set before writing any text on the graphic, or modifying settings such as TextColor or TextFont.
WriteText (Text As String) - Adds a single line of text to the current text resource. The text will be written immediately below the last line of text to be written. The first line of text added to the resource will be written at the position on the page defined by a call to the Locate function.
TextColor As OLE_COLOR - The colour to be used on the current text block for text. (Default = Black).
TextSize As Long - The size of the text for the current text block, in points. If a block of text is scaled using the ScaleObject after it is applied to a page, the size of the text will also be scaled accordingly. (Default = 10).
TextLineSpacing As Double - The size of the gap that will be left between the previous line of text and the next line of text to be written. The value is expressed in terms of percentage of the height of one line of text. (Default = 15.0).
TextMaxWidth As Double - The maximum width of a line of text in the units of measure defined by Units. By setting a value for this property, long lines of text will be wrapped to use two or more lines. A value of -1 indicates that no maximum width is set and there will be no wrapping of the text. (Default = -1.0).
To use TextMaxWidth and wrap lines of text, a TrueType font must be used. This property has no effect with the 14 standard fonts.
TextAlign As TxTextAlign - This property determines how the lines of text in a text block are positioned relative to each other.
TextAlign can take any of the following values:
|
| TxTextAlign |
| taLeft: (Default) | 0 | Left-justified text. |
| taCenter: | 1 | Centred text. |
| taRight: | 2 | Right-justified text. |
|
This property cannot be set to different values for each line of text.
If any of the 14 standard fonts are used in the text block, then the text will always be left-justified. In order to use centred or right-justified text, TrueType fonts must be used.
TextSkewX As Double - Setting this property to a value other than zero will skew the text by the given number of degrees in the horizontal direction. (Default = 0.0).
TextSkewY As Double - Setting this property to a value other than zero will skew the text by the given number of degrees in the vertical direction. The main use of TextSkewY is to create italic text when using a font that does not include an in-built italic character set. A typical value to use for italic text is 18.0. (Default = 0.0).
TextFont As Long - Text can be written using any TrueType font previously added to the document by the AddFont function. Alternatively, any one of the 14 standard Type 1 fonts listed below can be used. The TextFont property indicates the font to be used for the current text resource.
|
| 1 | Courier |
| 2 | Courier-Bold |
| 3 | Courier-BoldOblique |
| 4 | Courier-Oblique |
| 5 (Default) | Helvetica |
| 6 | Helvetica-Bold |
| 7 | Helvetica-BoldOblique |
| 8 | Helvetica-Oblique |
| 9 | Times-Roman |
| 11 | Times-Bold |
| 11 | Times-Italic |
| 12 | Times-BoldItalic |
| 13 | Symbol |
| 14 | ZapfDingbats |
|
AddFont (FontName As String) As Long - Adds a TrueType font from a file on disk. FontName is the full path and name of the font file, which will usually have a .ttf extension. The return value of the function identifies the font and is used to reference it each time it is used in the document.
EmbedFont (FontNum As Long) As Boolean - If this property is set to True for a font that has been added using the AddFont function, the font will be embedded into the PDF document. This ensures that the font will be available to the end user who is viewing or printing the PDF, regardless of whether the chosen font is already installed on their system. If the font is not embedded in the document, and is not available to the end user, the software used to view or print the document will substitute another font. (Default = False).
The following example VB code shows how to add a font, select the font for use in the current text resource, and embed the font file in the PDF document:
|
| Dim F As Integer |
| |
| |
| ............ |
| F = PDF1.AddFont("C:\WINNT\Fonts\Arial.ttf") |
| PDF1.EmbedFont(F) = True |
| PDF1.TextFont = F |
| ............ |
|
TextBlockHeight As Double - Read-only property. Returns the height that the current text block will require when added to a page, in the units of measure currently set by the property Units.
General Document Functions
General functions operating at a document level.
Clear ( ) - Deletes all pages and all resources from the control, allowing a new document to be started.
DeleteAllPages ( ) - Deletes all pages from the control, but retains all resources for use in a new document.
SaveToFile (FileName As String) - Saves the document to disk in PDF format using FileName.
Units As TxUnitsMeas - The units of measure to be used for sizing and locating all pages and objects in the current document. It is recommended that this property be set to the preferred value before any pages or resources are added to the document, and not subsequently changed. The results can be confusing if resources created using one value for Units are then drawn onto pages using a different value.
Units can take any of the following values:
|
| TxUnitsMeas |
| umPoints: (Default) | 0 | A point is 1/72 of an inch. |
| umInches: | 1 | Inches. 1 inch = 72 points. |
| umCentimeters: | 2 | Centimeters. 1 cm = 28.3465 points. |
| umMillimeters: | 3 | Millimeters. 1 mm = 2.83465 points. |
|
All PDF documents generated by PDFBuilderX use points as the internal unit of measure. Nevertheless, any of the above options can be used in your application as all conversions will be made automatically.
All co-ordinates used in the Locate function and graphic drawing functions are based on Units and are measured from the bottom-left corner of each page.
The following properties allow general information about the document to be included. They are all strings and their use is self-explanatory. All are empty strings by default.
Title As String
Subject As String
Author As String
Keywords As String
Deploying an Application
In order to deploy an application that uses PDFBuilderX you will need to distribute the OCX file, PDFBuilderX.ocx, together with the files that make up your application. This file will need to be registered on the machine running your application and you may wish to use a proprietary installer to do this. When PDFBuilderX was installed on your system our installer will have copied the OCX file to the directory "Program Files\Ciansoft\ PDFBuilderX \", assuming you used the installer and accepted the defaults.
The number of copies of the OCX file that may be distributed is not limited by the licence. In order to use the control in a design environment the licence file, PDFBuilderX.lic, is also required. A separate licensed copy of PDFBuilderX is required for each computer it is used on in the design environment.
Revision History
The current version of PDFBuilderX is 2.1.
New in Version 1.1
Support for TrueType fonts using the AddFont function.
EmbedFont property.
AddImageBytes function.
New in Version 2.0
Improved functionality for writing text blocks including TextAlign and TextLineSpacing functions and greater flexibility to mix fonts and sizes within a single text block.
Rotate function.
General document information properties (Title, Subject, Author, Keywords).
ImageCount property.
New in Version 2.1
TextMaxWidth property.
TextSkewX and TextSkewY properties.
Circle and Ellipse functions.
PDF (Portable Document Format) is copyright of Adobe Systems Incorporated
|
|
