ReportPro 2.0

ReportPro 2

Developer's Guide

Overviews | Class Reference | Other
Developer's Overview | DiBMP Class | Distributing ReportPro with Your Applications
Multiple Section Reports | PtrDevice Class | Examples
RpReport Class Overview | rpDataSource Class | External Function Libraries
RpPrinter & PtrDevice | RpPrinter Class | Internationalization
 | RpReport Class |
 | RpRDDTable Class |
 | RpSection Class |
 | RpSQLQuery Class |
 | RTF Class | Customer Support

ReportPro Developer's Help Copyright 1995-2009 by DataPro, Inc. All rights reserved.


Copyright

ReportPro, Copyright 1995-2007 by DataPro, Inc. All rights reserved.

DataPro, Inc.

PO Box 6663

Warner Robins, GA 31095-6663

United States of America

The information contained in this document is subject to change without notice. DataPro makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of marketability and fitness for a particular purpose.

DataPro shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

No part of this document may be photocopied, reproduced, or translated to another language without the prior written consent of DataPro, Inc.

ReportPro and RP2 are a trademarks of DataPro, Inc.

Windows is a registered trademark of Microsoft Corporation

Visual Objects is a trademark of Computer Associates International

All other product names are trademarks of their respective companies


Developer's Overview

Using ReportPro in Your Application

The ReportPro Developer's Library allows you to programmatically access the ReportPro reporting engine from within your application.

ReportPro ships with both 16-bit and 32-bit versions in the same package. Each version of the ReportPro Developer's library contains three runtime libraries designed to fulfill a specific reporting need.

Runtime Library

Properties

RDD
· Supports Replaceable Data Drivers (RDD). Natively supports NTX, CDX and MDX drivers. Third party RDDs are also supported.
· Runs RDD reports created with the ReportPro Designer.
· Runs reports that are hand-coded with the RpPrinter class.

RDD/SQL
· Supports RDD and ODBC/SQL data sources.
· Runs all reports created with the ReportPro Designer.
· Runs reports that are hand-coded with the RpPrinter Class.

Designer
· Provides report design capability for the end-user.
· Supports RDD and ODBC/SQL data sources.
· Runs all reports created with the ReportPro Designer. Reports can be run from the design interface or without displaying the design interface. There is no need to link the RDD or RDD/SQL runtime libraries into your application if you link in the designer library.
· Runs reports that are hand-coded with the RpPrinter Class.

There are four primary classes contained in the runtime libraries. These classes are used to print existing reports, allow the end user to define and edit reports and print hand-coded reports. The classes are present in each of the runtime libraries, however, some classes have reduced functionality depending on which library it is in. Each primary class is identified in the table below:

Class | Description
RpReport | This is the class you use to access the ReportPro runtime. Use this class to print reports from your application. If you link in the Designer library, you can also use this class to access ReportPro's design interface.
RpPrinter | Use this class when you wish to hand-code reports. This class provides methods to print lines, rectangles, circles and text. It also has a built-in print preview which you can use with your hand-coded reports.
RTF | This class provides the ability to print text stored in Rich Text Format (RTF). This class loads RTF from various sources, automatically parses the RTF into a usable format and provides the capability to print the RTF text using ReportPro's RpPrinter class.
DIBMP | Windows provides several API functions to display and manipulate bitmaps. The DIBMP class not only provides a wrapper around some of these functions, it also simplifies the tasks associated with bitmap loading and memory management. The DIBMP class can handle bitmaps larger than 64K and containing up to 256 colors.

Using ReportPro with CA-VO version 2

The 32-bit version of the ReportPro Developer's library is designed to work with CA-Visual Objects 2.0. Each runtime library is contained in a separate CA-VO Application Export File (AEF) which must be imported and linked into your application before you can access the ReportPro runtime. The runtime libraries and associated AEF files are identified in the following table:

Runtime Library | Library File
RDD | Rp2Rdd32.AEF
RDD/SQL | Rp2Sql32.AEF
Designer | Rp2Dsn32.AEF

To import a runtime library:

• From the CA-VO application explorer, select the desired project and choose the Import option from the File menu.
• Select the desired library AEF (see table above).
• Compile the imported library by choosing the Build option from the Application menu.

After the ReportPro library has been imported, you must also import the RP2_HOOK.MEF file into each application that uses ReportPro. The MEF contains code that forces the CA-VO linker to properly link ReportPro support functions into your applications.

To import the MEF:

• Select the desired application, choose the Import option from the File menu.
• Choose the RP2_HOOK.MEF file.

After you import the MEF, add the ReportPro runtime library imported above to the Included Libraries list for your application. Your application can now access the ReportPro runtime.

Information for Users Upgrading from ReportPro 1.x

If you are upgrading from ReportPro version 1 to version 2, there are a few differences that may affect your application:

• There is now only one hook module (RP2_HOOK.MEF). It is designed for use in both RP2/16 and RP2/32. Make sure you delete the 1.0 hook MEF from your application and import the newer RP2_HOOK.MEF.
• The RpReport:ReportWizard() callback method has become the RpReport:StandardReportWizard() callback method.
• The RpReport:GetVariableValue() method may require a call to RpReport:Connect2Source() before use.
• The RpReport:SetIndex() method may require a call to RpReport:Connect2Source() before use.
• The RpReport:Seek() method is obsolete and is no longer supported. You should use the RpReport:SeekExpression assign instead.
• RpPrinter:DrawText() now has a ALIGN_FULL option for full justification of text output.
• The code for the PtrDevice and RpPrinter classes is provided in the SDK directory rather than residing in the runtime libraries themselves.

A Note to CA-Visual Objects Programmers

To improve performance, many of ReportPro's classes use exported data types. You should not modify an exported variable directly unless it is documented to do so in this manual.

The underlying structure of ReportPro is subject to change without notice or support. Developers should use the methods, accesses and assigns provided to minimize the effect these changes will have on your application.


RpReport Class Overview

The RpReport class provides access to the ReportPro runtime engine. The ReportPro runtime allows you to integrate reports created with the ReportPro design environment into your application.

The basic concept behind ReportPro is to design a report using the ReportPro design environment and then write code in your application to print the report. The task of printing a report from your application is simple and requires only a few lines of code:

Example

METHOD PrintReport CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL cJobName,cPrint2Filename,cCaption,cMessage AS STRING

oReport := RpReport{ SELF, "C:\RP2\BIT.RPT" }

IF oReport:IsValid

cJobName := "My Report"

cPrint2Filename := "REPORT.PRN"

cCaption := "My App Name"

cMessage := "Printing in progress..."

oReport:Print(cJobName,cPrint2Filename,cCaption,cMessage)

ENDIF

oReport:Close()

First the RpReport object is instantiated.

Next, the RpReport object is checked to insure the report initialized correctly. You should always test the IsValid access. If the report initializes correctly, it can be sent to either the printer or print preview window. If IsValid returns false, you should not attempt to print or preview the report.

Next, Print or PrintPreview is called. During this process, the tables in the data source are opened. If the report is ODBC based, ReportPro connects to the designated SQL server and submits the SQL query.

In all cases, it is necessary to close the report when you are finished with the RpReport object. This allows ReportPro to clean up and free resources.

The RpReport contains many additional methods that allow you to completely control the reporting process. Each of these methods is fully documented in the next chapter.


RpReport Class

Purpose

The purpose of this class is to provide access to the ReportPro runtime from an application.

Class

CLASS RpReport

Properties

FilterExpression Access/Assign

IsValid Access

PrinterDevice Access/Assign

ReportTitle Access

ReportDescription Access

SeekExpression Access/Assign

SQLAlwaysSelectAll Access/Assign RDD/SQL & Design Only

SQLDelimiter Access/Assign RDD/SQL & Design Only

SQLDistinct Access/Assign RDD/SQL & Design Only

SQLFilterWhere Access/Assign RDD/SQL & Design Only

SQLFrom Access/Assign RDD/SQL & Design Only

SQLGroupBy Access/Assign RDD/SQL & Design Only

SQLHaving Access/Assign RDD/SQL & Design Only

SQLOrderBy Access/Assign RDD/SQL & Design Only

SQLTableWhere Access/Assign RDD/SQL & Design Only

SQLUnion Access/Assign RDD/SQL & Design Only

SQLUserCols Access/Assign RDD/SQL & Design Only

StartRec Access/Assign

Support1ofN Access/Assign

WhileExpression Access/Assign

YieldAfter Assign

Methods

Close

Connect2Source

ExpressionBuilder

GetVariableValue

Init

LoadRpt

NewCrossTabRpt

NewLabelRpt

NewRpt

Print

PrintExport

PrintPreview

SetBottomMargin

SetFilterExpression

SetIndex

SetLandscape

SetLeftMargin

SetPaperBin

SetPaperLength

SetPaperSize

SetPaperWidth

SetRightMargin

SetSeekExpression

SetSortOrder

SetStartRec

SetSQLConnection

SetTableAttributes

SetTopMargin

SetVariableValue

SetVarInitExpression

SetVarUpdateExpression

SetWhileExpression

ShowPrintDlg

ShowSetupDlg

Callback Methods

CrossTabReportWizard

FileExit

LabelReportWizard

NewCrossTabReport

NewLabelReport

NewReport

OpenReport

RemoveChild

RpReportEnded

StandardReportWizard

Description

Many of the methods, accesses and assigns of the RpReport class map directly to the primary section of the report. The primary section is defined as the first data aware section in the report. Normally, this is the first section; however, if the first report section is a Title section, the second section is the primary section.

For example, the following two lines of code are equivalent:

oRpReport:FilterExpression:="Cstmr.Name = 'SMITH'"

oRpReport:aSections[1]:FilterExpression:="Cstmr.Name = 'SMITH'"

Both assign a filter expression to the primary section.

The methods are provided at the report level for convienence and to retain compatibility with ReportPro version 1. If you need to modify attributes for subsequent sections, you must retrieve the section from the report's section list. See the discussion under Multiple Section Reports for more information.


RpReport:FilterExpression

RpReport:FilterExpression Access/Assign
Type String

Purpose

To get/set an optional expression used as a filter. The filter determines which records are included in the primary section. The assigned value must be a valid expression or an empty string ("") to clear the filter expression.

Example

// Set the filter to include only customers named Smith

oRpReport:FilterExpression := " Customer.Name = 'Smith' "

// Clear the current filter

oRpReport:FilterExpression := ""

Note: This access/assign maps directly to the primary section of the report.


RpReport:IsValid

RpReport:IsValid Access
Type Logic

Purpose

To get a logical value which indicates if the RpReport object initialized correctly and can be printed. If this access returns FALSE, do not print the report. This access should be tested each time an RpReport object is created.

Example

// Make sure the report is valid and can be printed

if oRpReport:IsValid

// report is valid and can be printed

endif


RpReport:PrinterDevice

RpReport:PrinterDevice Access/Assign
Type PtrDevice Object

Purpose

To get/set the PtrDevice object used by the RpReport object to print the report.

Example

// Set the number of copies to print

oRpReport:PrinterDevice:Copies := 2


RpReport:ReportTitle

RpReport:ReportTitle Access
Type String

Purpose

To get the Report Title saved in the report file.

Example

// Get the Report Title

cReportTitle := oRpReport:ReportTitle


RpReport:ReportDescription

RpReport:ReportDescription Access
Type String

Purpose

To get the Report Description saved in the report file.

Example

// Get the Report Description

cReportTitle := oRpReport:ReportDescription


RpReport:SeekExpression

RpReport:SeekExpression Access/Assign
Type String

Purpose

To get/set the seek expression of a rpRDDTable object. If a seek expression is specified, it is evaluated at the beginning of the report prior to printing. The value returned from the seek expression is used to perform a soft seek against the index of the primary table in the section. After the seek is performed, reporting starts. The assigned value must be a valid expression or an empty string ("") to clear the seek expression.

Example

// To force an inventory report to start at a

// certain part number

oRpReport:SeekExpression := " padr('3173081',20) "

// Clear the seek expression

oRpReport:SeekExpression := ""

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpRDDTable.


RpReport:SQLAlwaysSelectAll

RpReport:SQLAlwaysSelectAll Access/Assign
Type Logic

Purpose

To force a rpSQLQuery object to select all columns when issuing a SQL SELECT statement. This assign is provided for cases where the ODBC driver does not support column names that are supported by the SQL server.

Example

// To force ReportPro to select all columns

oRpReport:SQLAlwaysSelectAll := TRUE

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLDelimiter

RpReport:SQLDelimiter Access/Assign
Type String

Purpose

To get/set the delimiter used by a rpSQLQuery object to delimit SQL identifiers. By setting this value, you can force the rpSQLQuery object to use a different identifier delimiter than that returned by the ODBC driver.

Example

// To force ReportPro to use ` as the delimiter

oRpReport:SQLDelimiter := "`"

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLDistinct

RpReport:SQLDistinct Access/Assign
Type Logic

Purpose

To determine or set whether or not the DISTINCT keyword is used in the SQL SELECT statement. Setting this assign to TRUE forces the rpSQLQuery to include the DISTINCT keyword when a SQL SELECT statement is issued.

Example

// Force ReportPro to issue SELECT DISTINCT

oRpReport:SQLDistinct := TRUE

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLFilterWhere

RpReport:SQLFilterWhere Access/Assign
Type String

Purpose

To get/set the optional filtering condition in a rpSQLQuery's SQL SELECT statement. Internally, the rpSQLQuery object stores the select statement in distinct chunks. This allows sections of the SELECT statement to be manipulated without disrupting other sections which are automatically maintained by the rpSQLQuery object. The assigned value must be a valid expression to the ODBC driver and/or SQL server.

Example

// Set SQL filter to show customers in California

oRpReport:SQLFilterWhere := "customer.state = 'CA'"

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLFrom

RpReport:SQLFrom Access/Assign
Type String

Purpose

To get/set the FROM clause in the SQL SELECT statement. Generally, the use of this assign should be avoided since the rpSQLQuery object automatically manages the FROM clause.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLGroupBy

RpReport:SQLGroupBy Access/Assign
Type String

Purpose

To get/set the GROUP BY clause in a rpSQLQuery's SQL SELECT statement. This assign allows you to set the grouping performed by the SQL server. Do not confuse this assign with ReportPro's grouping. ReportPro performs it's grouping locally independent of any grouping performed by the SQL server.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLHaving

RpReport:SQLHaving Access/Assign
Type String

Purpose

To get/set the HAVING clause in a rpSQLQuery's SQL SELECT statement. This assign works with the SQLGroupBy assign and is passed directly to the SQL server.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLOrderBy

RpReport:SQLOrderBy Access/Assign
Type String

Purpose

To get/set the ORDER BY clause in a rpSQLQuery's SQL SELECT statement. This assign determines the sort order of the query and is passed directly to the SQL server.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLTableWhere

RpReport:SQLTableWhere Access/Assign
Type String

Purpose

To get/set the table relationship portion of the WHERE clause in a rpSQLQuery's SQL SELECT statement. Generally, use of this assign should be avoided since the rpSQLQuery object automatically manages the WHERE clause.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLUnion

RpReport:SQLUnion Access/Assign
Type String

Purpose

To get/set the UNION clause in a rpSQLQuery's SQL SELECT statement. This assign allows you to specify unions to be performed by the SQL server.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:SQLUserCols

RpReport:SQLUserCols Access/Assign
Type String

Purpose

To get/set the user defined column section in a rpSQLQuery's SQL SELECT statement. This assign allows you to request calculated columns from the SQL server.

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpSQLQuery.


RpReport:StartRec

RpReport:StartRec Access/Assign
Type String

Purpose

To get/set the starting record number of a RDD table.

Example

// Force ReportPro to start on the fifth record

oRpReport:StartRec := 5

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpRDDTable.


RpReport:Support1ofN

RpReport:Support1ofN Access/Assign
Type Logic

Purpose

To turn on/off support for the "Page 1 of N" display and the PgCount() runtime function.

If this value is set to true, ReportPro will calculate the total pages in the report when Print or PrintPreview is called before it begins printing/previewing the report. This effectively doubles reporting time since ReportPro must print the report twice, once in the background to calculate the page count and then again to perform the main printing task. In this case, the PgCount() runtime function will return the total pages in the report.

If this value is set to false, ReportPro will not count the pages in the report before it begins print/previewing. In this case, the PgCount() runtime function will return 0.

Example

// It slows down printing but we need to display

// the page count during the report…

oRpReport:Support1OfN := true


RpReport:WhileExpression

RpReport:WhileExpression Access/Assign
Type String

Purpose

To get/set an optional expression used to implement a print while condition. Records are included into a section until the while expression returns FALSE (or there is no more records to process). This must be a valid expression or an empty string ("") to clear the while condition.

Example

// keep producing the report until you find

// a name that begins with "H" or greater

oRpReport:WhileExpression := "Customer.Name < 'G' "

Note: This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpRDDTable.


RpReport:YieldAfter

RpReport:YieldAfter Assign
Type ShortInt

Purpose

To set the interval at which ReportPro yields control to MS-Windows. By default ReportPro yields control to MS-Windows after processing 100 logical records. If your application is performing a time sensitive task, you may want to decrease YieldAfter. A YieldAfter value of 1 yields control to MS-Windows after each record. Setting a low YieldAfter value increases the amount of time required to run a report.

Example

// Force ReportPro to yield after 10 records

oRpReport:YieldAfter := 10


RpReport:Close()

RpReport:Close() Method

Purpose

Close a RpReport object. You must call this method to free resources used by RpReport.

Syntax

<oRpReport>:Close() NIL

Description

After this call, the RpReport object is no longer valid.

Example

// The report object is no longer needed close it.

oRpReport:Close()


RpReport:Connect2Source()

RpReport:Connect2Source() Method

Purpose

This method instructs RpReport to connect to its data sources and validate all expressions.

Syntax

<oRpReport>:Connect2Source() lSuccess

Description

ReportPro now waits until Print or PrintPreview is called before it connects to its data sources. This allows more flexibility in setting options before the data sources are activated.

There are certain methods which will not work properly before RpReport connects to its data sources and compiles/validates its expressions:

GetVariableValue()

SetIndex()

This method returns true if RpReport is already connected or successful in connecting to its data sources. This method is automatically invoked by a call to Print() or PrintPreview().

Example

// Connect to data sources and validate exps

oRpReport:Connect2Source()


RpReport:ExpressionBuilder()

RpReport:ExpressionBuilder() Method

Purpose

Display the ReportPro Expression Builder.

Syntax

<oRpReport>:ExpressionBuilder(oOwner, cCaption, cExpression, lAllowEmpty, lForceLogic) cExpression

Arguments

oOwner | The window owner of the Expression Builder dialog window.
cCaption | The caption of the Expression Builder dialog window.
cExpression | The initial expression displayed in the Expression Builder.
lAllowEmpty | Logic indicating if the Expression Builder should allow the user to return an empty ("") expression.
lForceLogic | Logic indicating if the expression (when evaluated) must return a logical value.

Description

Returns the new expression or cExpression if the user presses cancel.

Example

// Display the expression builder so the user

// can specify a report filter.

cExp:=oRpReport:ExpressionBuilder(self, "My Caption",;

"Customer.Name='Smith'", true, true)

Note: This method displays the Expression Builder for the primary section of the report.


RpReport:GetVariableValue()

RpReport:GetVariableValue() Method

Purpose

To get the value of a ReportPro user defined variable.

Syntax

<oRpReport>:GetVariableValue(cName) xValue

Arguments

cName

The name of the ReportPro variable.

Description

Returns the ReportPro variable value as a usual.

Example

// Print the value of a ReportPro variable.

? oRpReport:GetVariableValue("ReportHDR")

Note: This method searches for the variable in the primary section of the report. It may be necessary to call RpReport:Connect2Source() before using this method. See the discussion under Connect2Source() for more information.


RpReport:Init() - Runtime Mode

RpReport:Init() - Runtime Mode Method

Purpose

Construct a RpReport object.

Syntax - RDD Only Library

RpReport{oOwner, cFilename, [cDatapath], [aDbfSwap]} SELF

Syntax - RDD/SQL Library / Linkable Design Library

RpReport{oOwner, cFilename, [cDatapath], [aDbfSwap], [cUserID], [cPassword]} SELF

Syntax - Linkable Design Library (Report Design Init)

RpReport{oOwner, aTables} SELF

Arguments

oOwner The window that owns the RpReport object
cFilename The full path and filename of the report file created by ReportPro
cDatapath Optional path for the database. This parameter will override the table path(s) stored in the report file. This parameter applies only to RDD tables.
aDbfSwap Allows you to swap out the tables used in the report. While this parameter applies primarily to RDD tables, it can also be used to substitute tables in a SQL query.

Any value of the array that you do not wish to change should be specified as NIL. If you specify NULL_STRING, the value will be changed to the empty string value.

The format of the array is:

{{RPAlias, Table File, Index File, Index Tag, RDD, RDDAlias}, {...}, ...}

RPAlias | The alias which ReportPro has assigned to the table. This character value can be found in the Setup Sections dialog. This is the key used to designate which table in the data set is being replaced so it must exactly match the ReportPro alias.
Table File | The complete path and file name of the substituted table.
Index File | The index file to use in place of the index filename specified in the Setup Sections dialog.
Index Tag | The index tag used in conjunction with the Index File specified above. If the Index File is specified, you must specify a Tag for DBFCDX and DBFMDX RDDs.
RDD | The RDD to use with this table.
RDDAlias | When specified, this element forces ReportPro to use an already open DBF table instead of opening the one specified in the report. This element can be the alias name, the work area number or the DBServer of the already open table.

cUserID Optional User ID used when ReportPro connects to a SQL server. If this parameter is not specified, ReportPro will use the user ID saved in the report file.
cPassword Optional Password used when ReportPro connects to a SQL server. If this parameter is not specified, ReportPro will use the password saved in the report file.

Description

Creating a RpReport object initializes a report by reading information from the specified report file. You should check the IsValid access of the returned object to make sure the report initialized correctly and a valid printer object is available.

Example

// Instantiate a report object for the invoices example report

oRpReport := RpReport{oMainWindow, "C:\RP2\INVOICES.RPT"}


RpReport:Init() - Designer Mode

RpReport:Init() - Designer Mode Method

(Linkable Design Library Only)

Purpose

Construct a RpReport Designer object.

Syntax

RpReport{oOwner, aTables, cDataPath, aDbfSwap} SELF

Syntax - Report Wizards

CrossTabReportWizard(oOwner, aTables) oRpReport

StandardReportWizard(oOwner, aTables) oRpReport

LabelReportWizard(oOwner, aTables) oRpReport

Arguments

oOwner The window that owns the RpReport design window
aTables An array containing the tables that the user can include in the report. The tables must be specified when the RpReport object is created. The format of the array is:

{{cFileName, cTableName, cDriver, lODBC}, {...}, ...}

CFileName | The file name of the RDD table or the SQL table name.
CTableName | The table name that the user will see when they choose the table.
CDriver | For RDD tables, this is the driver name ("DBFCDX", "DBFNTX"). For SQL Queries, it identifies the ODBC connection name ("SAMPLE").
lODBC | Logical indicating if the report is ODBC based. (TRUE = ODBC)
cDatapath Optional path for the database. This parameter will override the table path(s) stored in the report file. This parameter applies only to RDD tables.
aDbfSwap Allows you to swap out the tables used in the report. While this parameter applies primarily to RDD tables, it can also be used to substitute tables in a SQL query.

Any value of the array that you do not wish to change should be specified as NIL. If you specify NULL_STRING, the value will be changed to the empty string value.

The format of the array is:

{{RPAlias, Table File, Index File, Index Tag, RDD, RDDAlias}, {...}, ...}

RPAlias | The alias which ReportPro has assigned to the table. This character value can be found in the Setup Sections dialog. This is the key used to designate which table in the data set is being replaced so it must exactly match the ReportPro alias.
Table File | The complete path and file name of the substituted table.
Index File | The index file to use in place of the index filename specified in the Setup Sections dialog.
Index Tag | The index tag used in conjunction with the Index File specified above. If the Index File is specified, you must specify a Tag for DBFCDX and DBFMDX RDDs.
RDD | The RDD to use with this table.
RDDAlias | When specified, this element forces ReportPro to use an already open DBF table instead of opening the one specified in the report. This element can be the alias name, the work area number or the DBServer of the already open table.

Description

When an array is specified as the second parameter of the RpReport:Init(), the RpReport object initializes as a report designer window. The report designer initialization is a two step process. First you instantiate the RpReport object by specifying the array of tables the user can include in the report. Next you must call: NewCrossTabRpt(), NewLabelRpt(), NewRpt() or LoadRpt() to complete the initialization.

The RpReport object can also be instantiated by calling one of the three Report Wizard functions: CrossTabReportWizard(), LabelReportWizard(), and StandardReportWizard(). The Report Wizard functions guide the user through the creation of a report through a tabbed dialog.

Example

In addition to the code below, please see the Designer Example program which accompanies ReportPro.

METHOD NewReport CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL aDBS[0] AS ARRAY

AADD(aDbs,{"parcels.dbf","Parcels Table","DBFNTX",FALSE})

AADD(aDbs,{"district.dbf","District Table","DBFNTX",FALSE})

// initialize RpReport as the designer...

oReport:=RpReport{SELF,aDbs}

// initialize the designer for a new report

oReport:NewRpt()

IF oReport:IsValid

AADD(SELF:aChildWindows, oReport)

ELSE

oReport:EndWindow()

ENDIF

METHOD OpenReport CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL aDBS[0] AS ARRAY

LOCAL oDialog AS OpenDialog

AADD(aDbs,{"parcels.dbf","Parcels Table","DBFNTX",FALSE})

AADD(aDbs,{"district.dbf","District Table","DBFNTX",FALSE})

(oDialog:=OpenDialog{SELF,"*.RPT"}):Show()

IF !EMPTY(oDialog:Filename)

// initialize RpReport as the designer...

oReport:=RpReport{SELF,aDbs}

// load the report from file...

oReport:LoadRpt(oDialog:Filename)

IF oReport:IsValid

AADD(SELF:aChildWindows, oReport)

ELSE

oReport:EndWindow()

ENDIF

ENDIF


RpReport:LoadRpt()

RpReport:LoadRpt() Method

Purpose

To load an existing report into the report designer window.

Syntax

<oRpReport>:LoadRpt(cFileName) lSuccess

Arguments

cFileName

The report file name to load into the design window.

Example

// initialize RpReport as the designer...

AADD(aDBS, {"C:\RP2\bit.dbf","Bit","DBFCDX",FALSE})

oReport:=RpReport{SELF, aDBS}

// load the report from file...

oReport:LoadRpt("C:\RP2\BIT.RPT")

Note: This method is only available in the Linkable Design Library and only when the RpReport object is instantiated as a design window.


RpReport:NewCrossTabRpt()

RpReport:NewCrossTabRpt() Method

Purpose

To initialize the report designer window as a new cross-tab report.

Syntax

<oRpReport>:NewCrossTabRpt() lSuccess

Example

// initialize RpReport as the designer...

aadd(aDBS, {"C:\RP2\bit.dbf","Bit","DBFCDX",false})

oReport:=RpReport{self, aDBS}

// initialize the design window as a new label report

oReport:NewCrossTabRpt()

Note: This method is only available in the Linkable Design Library and only when the RpReport object is instantiated as a design window.


RpReport:NewLabelRpt()

RpReport:NewLabelRpt() Method

Purpose

To initialize the report designer window as a new label report.

Syntax

<oRpReport>:NewLabelRpt() lSuccess

Example

// initialize RpReport as the designer...

aadd(aDBS, {"C:\RP2\bit.dbf","Bit","DBFCDX",false})

oReport:=RpReport{self, aDBS}

// initialize the design window as a new label report

oReport:NewLabelRpt()

Note: This method is only available in the Linkable Design Library and only when the RpReport object is instantiated as a design window.


RpReport:NewRpt()

RpReport:NewRpt() Method

Purpose

To initialize the report designer window as a new standard report.

Syntax

<oRpReport>:NewRpt() lSuccess

Example

// initialize RpReport as the designer...

aadd(aDBS, {"C:\RP2\bit.dbf","Bit","DBFCDX",false})

oReport:=RpReport{self, aDBS}

// initialize the design window as a new report

oReport:NewRpt()

Note: This method is only available in the Linkable Design Library and only when the RpReport object is instantiated as a design window.


RpReport:Print()

RpReport:Print() Method

Purpose

Send the report to the printer or print file.

Syntax

<oRpReport>:Print(cJobName, cPrint2Filename, cCaption, cMessage) NIL

Arguments

cJobName | The name used for this print job. This is the name displayed in the Print Manager.
cPrint2Filename | The filename to be used if the user selects the Print To File option.
cCaption | The caption displayed on the dialog window presented to the user during printing.
cMessage | The message displayed on the dialog window presented during printing.

Example

METHOD PrintReport() CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL cJobName,cPrint2Filename,cCaption,cMessage AS STRING

oReport := RpReport{SELF, "C:\RP2\BIT.RPT"}

IF oReport:IsValid

cJobName := "My Report"

cPrint2Filename := "REPORT.PRN"

cCaption := "My App Name"

cMessage := "Printing in progress..."

oReport:Print(cJobName,cPrint2Filename,cCaption,cMessage)

ENDIF

oReport:Close()

The following dialog window is displayed during the print operation:


RpReport:PrintPreview

RpReport:PrintPreview() Method

Purpose

Print the report in the print preview window.

Syntax

<oRpReport>:PrintPreview( [cJobName],

[cPrint2File],

[cCaption],

[cMessage],

[lModal],

[nShowState],

[lZoomed],

[symPPWindow]) NIL

Arguments

CJobName

Optional. The name used for this print job. This is the name that will be displayed in the Windows Print Manager. This parameter is only used if the user selects the print option from the preview window.

cPrint2Filename

Optional. The filename to be used if the user selects the Print To File option. This parameter is only used if the user selects the print option from the preview window.

cCaption

Optional. The caption displayed on the Print Preview window.

cMessage

Optional. The message string displayed on the dialog window presented to the user during printing. This parameter is only used if the user selects the print option from the preview window.

lModal

Optional parameter which if TRUE creates the Print Preview as a modal dialog window; FALSE would produce a modeless one. The default is TRUE.

nShowState

Optional parameter to set the preview window show state. Valid options are:

SW_SHOWNORMAL, SW_SHOWMAXIMIZED and SW_SHOWMINIMIZED

nZoomed

Optional parameter which specifies the initial zoom level of the Print Preview window. Valid options are:

ZOOM_WHOLE_PAGE, ZOOM_PAGE_WIDTH and ZOOM_100

SymPPWindow

Optional parameter to specify a symbol representing a class to instantiate for use as the Print Preview window. The class specified must provide certain callback methods for ReportPro. The code for ReportPro's PrintPreview windows is provided as an example of what methods the window needs to provide.

There are two Print Preview window types provided with ReportPro:

#rpPrintPreviewMDI: this symbol will produce a Print Preview window that is built on an MDI child window. The owner must be an MDI shell type window.#rpPrintPreviewDLG: this symbol will produce a Print Preview window that is built on a modal or modeless dialog window.

Example

METHOD PreviewReport() CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL cJobName, cPrint2Filename, cCaption, cMessage AS STRING

oReport := RpReport{SELF, "C:\RP2\BIT.RPT"}

IF oReport:IsValid

cJobName := "My Report"

cPrint2Filename := "REPORT.PRN"

cCaption := "My App Name"

cMessage := "Printing in progress..."

oReport:PrintPreview(cJobName,cPrint2Filename,cCaption,;

cMessage, TRUE)

ENDIF

oReport:Close()


RpReport:PrintExport()

RpReport:PrintExport() Method

Purpose

Print the report to an export format.

Syntax

<oRpReport>:PrintExport(cCaption, cMessage, [symExport], [cFile]) NIL

Arguments

cCaption | The caption displayed on the Print Export window.
cMessage | The message string displayed on the dialog window presented to the user during export.
symExport | Optional parameter to specify a specific export type to use. If this is not specified, the user is prompted for an export format to use. If this parameter is specified, the <cFile> parameter is required as well. Currently supported types are: #RP_RTF_WORD95 (creates rich text format compatible with Microsoft Office 6) #RP_RTF_WORD97 (creates rich text format compatible with Microsoft Office 97) #RP_HTML (creates hypertext markup language output) #RP_ASCII (creates vanilla text output) #RP_PDF (creates a simple PDF format) #RP_EXCEL (creates a simple Excel format)
cFile | Optional filename for export file. This parameter is required if <symExport> is specified.

Example

METHOD ExportReport() CLASS StandardShellWindow

LOCAL oReport AS RpReport

LOCAL cCaption, cMessage AS STRING

oReport := RpReport{SELF, "C:\RP2\SAMPLES\BIT.RPT"}

IF oReport:IsValid

cCaption := "My App Name"

cMessage := "Export to HTML in progress..."

oReport:PrintExport(cCaption, cMessage, #RP_HTML, "myfile.htm")

ENDIF

oReport:Close()

Notes

When using the PDF Export you can specify fonts that should not be embedded in the PDF file. You can also set options for the name, author etc.

When using the Export Selection dialog, you can set that using the 'Advanced' button. You can also set that in the rpwin.ini file. An example :

[PDFOutPut]
Title=Title
Subject=Subject
Author=Author
Keywords=Keywords
Creator=Application
Compressed=1
EmbedFonts=1

[PDFDoNotEmbed]
Arial=
Arial Bold=
Arial Bold Italic=
Arial Italic=
Times New Roman=
Times New Roman Bold=
Times New Roman Bold Italic=
Times New Roman Italic=
Courier New=
Courier New Bold=
Courier New Bold Italic=
Courier New Italic=
WingDings=


RpReport:SetIndex()

RpReport:SetIndex() Method

Purpose

Use this method to set an index for the primary rpRDDTable object.

Syntax

<oRpReport>:SetIndex(cFileName, cTagName) NIL

Arguments

cFileName The file name of the index.
cTagName This is a string specifying the tag name to select from the index file. This parameter has meaning for RDDs that support compound indexes such as DBFCDX. If you are specifying an index from a compound index file, you must specify this parameter; otherwise, it is not required.

Description

If an index is specified via this method it does not override the sort order of the report; you must clear the sort order for the index to take precedence. Note: It is faster to use an existing index since the report engine does not have to create an index to support the sort order.

Example

// Set the index to be used for the report sort order

oRpReport:SetIndex ( "C:\RP2\BIT.CDX", "BIT" )

Note: This method maps directly to the first table object in the primary section. It only applies if the first table object is a rpRDDTable. It may be necessary to call RpReport:Connect2Source() before using this method. See the discussion under Connect2Source() for more information.


RpReport:SetSortOrder()

RpReport:SetSortOrder() Method

Purpose

This method allows you to specify the sort order of any section in the report.

Syntax

<oReport>:SetSortOrder(cSort, lUnique, [nSection]) NIL

Arguments

cSort The string specifying the new sort order. This string must be specified as follows:

"Table1.Field1 ASC, Table2.Field1 DESC".

Note that ASC is optional and is the default.

lUnique Optional parameter indicating whether the order should be unique (true) or include all values (false).

The default is false.

nSection Optional section number. The default is the first section after the optional title section.

Description

The primary section sort order can be set at runtime using this method. This is useful for when you want to allow your users to change the sort order at runtime.

Example

// Set the report sort order

oReport:SetSortOrder("Customer.CustNo ASC, WKORDER.Date ASC")

Note: This method maps directly to the primary section of the report.


RpReport:SetLandscape()

RpReport:SetLandscape() Method

Purpose

This method allows you to specify the landscape setting for any section of a report.

Syntax

<oReport>:SetLandscape(lValue, [nSection]) lValue

Arguments

lValue A logical value indicating whether the section should print in landscape mode.
nSection Optional section number. The default is the first section after the optional title section.

Description

The landscape setting for a report section must be set in the section to be changed. Use this method instead of setting the value on the printer device directly which will not work.

Example

// Print section 2 in landscape mode

oReport:SetLandscape(TRUE, 2)


RpReport:SetPaperBin()

RpReport:SetPaperBin() Method

Purpose

This method allows you to specify the paper bin setting for any section of a report.

Syntax

<oReport>:SetPaperBin(nValue, [nSection]) nValue

Arguments

lValue The new paper bin constant to use. For more information, see PtrDevice:DefaultPaperSource.
nSection Optional section number. The default is the first section after the optional title section.

Description

The paper bin (default paper source) setting for a report section must be set in the section to be changed. Use this method instead of setting the value on the printer device directly which will not work.

Example

// Print section 2 from the upper paper bin

oReport:SetPaperBin(DMBIN_UPPER, 2)


RpReport:SetFilterExpression()

RpReport:SetFilterExpression() Method

Purpose

This method allows you to specify the filter expression for any section of a report.

Syntax

<oReport>:SetFilterExpression(cExpression, [nSection]) logic

Arguments

cExpression The new filter expression for the specified section.
nSection Optional section number. The default is the first section after the optional title section.

Description

To set an optional expression used as a filter. The filter determines which records are included in the primary section. The assigned value must be a valid expression or an empty string ("") to clear the filter expression.

If you use fields in the expression, it is necessary to call RpReport:Connect2Source() prior to setting the filter.

Example

// Set the filter expression in section 2

oReport:SetFilterExpression("MyTable.MyField > 1", 2)


RpReport:SetWhileExpression()

RpReport:SetWhileExpression() Method

Purpose

This method allows you to specify the while expression for any section of a report.

Syntax

<oReport>:SetWhileExpression(cExpression, [nSection]) logic

Arguments

cExpression The new while expression for the specified section.
nSection Optional section number. The default is the first section after the optional title section.

Description

To set an optional expression used to implement a print while condition. Records are included into a section until the while expression returns FALSE (or there is no more records to process). This must be a valid expression or an empty string ("") to clear the while condition.

If you use fields in the expression, it is necessary to call RpReport:Connect2Source() prior to setting the while expression..

Example

// Set the while expression in section 2

oReport:SetWhileExpression("MyTable.MyField > 1", 2)


RpReport:SetTableAttributes()

RpReport:SetTableAttributes() Method

Purpose

This method allows you to specify table attributes in the report..

Syntax

<oReport>:SetTableAttributes( cAlias,

[cDriver],

[cTableName],

[cIndexName],

[cIndexTag]) logic (Success)

Arguments

cAlias | The alias which ReportPro has assigned to the table. This character value can be found in the Setup Sections dialog. This is the key used to designate which table in the data set is being replaced so it must exactly match the ReportPro alias.
cDriver | (Optional) The driver to use with this table.
cTablename | (Optional) The complete path and file name of the substituted table.
cIndexName | (Optional) The index file to use in place of the index filename specified in the Setup Sections dialog.
cIndexTag | (Optional) The index tag used in conjunction with the Index File specified above. If the Index File is specified, you must specify a Tag for DBFCDX and DBFMDX RDDs.

Description

To set the table attributes for tables in a report. This function operates much the same way as the <aDbfSwap> parameter of the RpReport:Init() method making it easier to specify attributes at runtime.

Example

// Set the table attributes to change the driver

oReport:SetTableAttributes("Customer", "DBFCDX")


RpReport:SetSeekExpression()

RpReport:SetSeekExpression() Method

Purpose

This method allows you to specify the seek expression for any section of a report.

Syntax

<oReport>:SetSeekExpression(cExpression, [nSection]) logic

Arguments

cExpression The new seek expression for the specified section.
nSection Optional section number. The default is the first section after the optional title section.

Description

To set the seek expression of a rpRDDTable object. If a seek expression is specified, it is evaluated at the beginning of the report prior to printing. The value returned from the seek expression is used to perform a soft seek against the index of the primary table in the section. After the seek is performed, reporting starts. The assigned value must be a valid expression or an empty string ("") to clear the seek expression.

If you use fields in the expression, it is necessary to call RpReport:Connect2Source() prior to setting the seek expression.

Example

// Set the seek expression in section 2

oReport:SetSeekExpression("1", 2)


RpReport:SetStartRec()

RpReport:SetStartRec() Method

Purpose

This method allows you to specify the starting record for any section of a report.

Syntax

<oReport>:SetStartRec(nRecNo, [nSection]) nRecNo

Arguments

nRecNo The new starting record number.
nSection Optional section number. The default is the first section after the optional title section.

Description

This access/assign maps directly to the first table object in the primary section. It only applies if the first table object is a rpRDDTable.

Example

// Set the starting record in section 2

oReport:SetStartRec(500, 2)


RpReport:SetPaperSize()

RpReport:SetPaperSize() Method

Purpose

This method allows you to specify the paper size setting for any section of a report.

Syntax

<oReport>:SetPaperSize(nValue, [nSection]) nValue

Arguments

lValue The new paper size constant to use. For more information, see PtrDevice:PaperSize.
nSection Optional section number. The default is the first section after the optional title section.

Description

The paper size setting for a report section must be set in the section to be changed. Use this method instead of setting the value on the printer device directly which will not work.

Example

// Print section 2 on legal size paper

oReport:SetPaperSize(DMPAPER_LEGAL, 2)


RpReport:SetPaperLength()

RpReport:SetPaperLength() Method

Purpose

This method allows you to specify the paper length setting for any section of a report.

Syntax

<oReport>:SetPaperLength(nValue, [nSection]) nValue

Arguments

lValue The new paper length in inches to use. For more information, see PtrDevice:PaperLengthInches.
nSection Optional section number. The default is the first section after the optional title section.

Description

The paper length setting for a report section must be set in the section to be changed. Use this method instead of setting the value on the printer device directly which will not work.

Example

// Set the paper length to 11 inches in section 2

oReport:SetPaperLength(11.0, 2)


RpReport:SetPaperWidth()

RpReport:SetPaperWidth() Method

Purpose

This method allows you to specify the paper width setting for any section of a report.

Syntax

<oReport>:SetPaperWidth(nValue, [nSection]) nValue

Arguments

lValue The new paper width in inches to use. For more information, see PtrDevice:PaperWidthInches.
nSection Optional section number. The default is the first section after the optional title section.

Description

The paper width setting for a report section must be set in the section to be changed. Use this method instead of setting the value on the printer device directly which will not work.

Example

// Set the paper width to 8.5 inches in section 2

oReport:SetPaperWidth(8.5, 2)


RpReport:SetSQLConnection()

RpReport:SetSQLConnection() Method

Purpose

This method allows you to specify SQL connections for RP to use.

Syntax

<oReport>:SetSQLConneciton(oConnection) logic

Arguments

oConnection The connection to add to the list of available connections.

Description

This new method is available in the Rp2Sql32 and Rp2Dsn32 libraries. It allows you to specify a SQL connection for RP to use. You can specify more than one by repeated calls to this method. At runtime, RP checks the list of connections it has built to see if one exists with the same data source that is need by the rpSQLQuery class. If a connection is found, it uses that connection instead of opening a new one.

Example

// Set a connection

oReport:SetSQLConnection(oMyConnection)


RpReport:SetBottomMargin()

RpReport:SetBottomMargin() Method

Purpose

This method allows you to specify the bottom margin in any section of a report.

Syntax

<oReport>:SetBottomMargin(nValue, [nSection]) nValue

Arguments

nValue The new margin setting in inches
nSection Optional section number. The default is the first section after the optional title section.

Description

The bottom margin for a report must be set in the section to be changed. Use this method instead of setting the margin on the printer device directly which will not work.

Example

// Set the bottom margin in section 1 to 1.5 inches

oReport:SetBottomMargin(1.5, 1)


RpReport:SetTopMargin()

RpReport:SetTopMargin() Method

Purpose

This method allows you to specify the top margin in any section of a report.

Syntax

<oReport>:SetTopMargin(nValue, [nSection]) nValue

Arguments

nValue The new margin setting in inches
nSection Optional section number. The default is the first section after the optional title section.

Description

The top margin for a report must be set in the section to be changed. Use this method instead of setting the margin on the printer device directly which will not work.

Example

// Set the top margin in section 1 to 1.5 inches

oReport:SetTopMargin(1.5, 1)


RpReport:SetLeftMargin()

RpReport:SetLeftMargin() Method

Purpose

This method allows you to specify the left margin in any section of a report.

Syntax

<oReport>:SetLeftMargin(nValue, [nSection]) nValue

Arguments

nValue The new margin setting in inches
nSection Optional section number. The default is the first section after the optional title section.

Description

The left margin for a report must be set in the section to be changed. Use this method instead of setting the margin on the printer device directly which will not work.

Example

// Set the left margin in section 1 to 1.5 inches

oReport:SetLeftMargin(1.5, 1)


RpReport:SetRightMargin()

RpReport:SetRightMargin() Method

Purpose

This method allows you to specify the right margin in any section of a report.

Syntax

<oReport>:SetRightMargin(nValue, [nSection]) nValue

Arguments

nValue The new margin setting in inches
nSection Optional section number. The default is the first section after the optional title section.

Description

The right margin for a report must be set in the section to be changed. Use this method instead of setting the margin on the printer device directly which will not work.

Example

// Set the right margin in section 1 to 1.5 inches

oReport:SetRightMargin(1.5, 1)


RpReport:SetVariableValue()

RpReport:SetVariableValue() Method

Purpose

To set the value of a ReportPro user defined variable.

Syntax

<oRpReport>:SetVariableValue(cName, xValue, [nSection]) NIL

Arguments

cName | The name of the ReportPro variable.
xValue | The new variable value.
nSection | Optional section number. The default is the first section after the optional title section.

Example

// Change the variable used for the report title

oRpReport:SetVariableValue("ReportTitle", ;

"The New Report Title", 1)

Note: This method searches for the variable in the primary section of the report. It may be necessary to call RpReport:Connect2Source() before using this method. See the entry for Connect2Source() for more information.


RpReport:SetVarInitExpression()

RpReport:SetVarInitExpression() Method

Purpose

To set the expression that initializes a ReportPro variable.

Syntax

<oRpReport>:SetVarInitExpression(cName, xExpression, [nSection]) LOGIC

Arguments

cName | The name of the ReportPro variable.
xExpression | This parameter can either be a string representing the expression to be macro compiled or a codeblock.
nSection | Optional section number. The default is the first section after the optional title section.

Return

This method returns a TRUE if it is successful; otherwise, it returns false.

Description

The Init Expression of a variable is the expression that is evaluated to set the initial value of a ReportPro variable when the variable is reset.

Example

oRpReport:SetVarInitExpression("MyVar", "0")

oRpReport:SetVarInitExpression("MyVar2", " 'string value' ")

Note: This method searches for the variable in the primary section of the report. It may be necessary to call RpReport:Connect2Source() before using this method. See the entry for Connect2Source() for more information.


RpReport:SetVarUpdateExpression()

RpReport:SetVarUpdateExpression() Method

Purpose

To set the update expression of a ReportPro variable.

Syntax

<oRpReport>:SetVarUpdateExpression(cName, xExpression, [nSection]) LOGIC

Arguments

cName | The name of the ReportPro variable.
xExpression | This parameter can either be a string representing the expression to be macro compiled or a codeblock.
nSection | Optional section number. The default is the first section after the optional title section.

Description

The Update Expression of a variable is the expression that is evaluated to update a ReportPro variable before the Body Band is printed. This method returns a TRUE if it is successful; otherwise, it returns false.

Example

oRpReport:SetVarUpdateExpression("MyVar","0")

oRpReport:SetVarUpdateExpression("MyVar2", " 'string value' ")

Note: This method searches for the variable in the primary section of the report. It may be necessary to call RpReport:Connect2Source() before using this method. See the entry for Connect2Source() for more information.


RpReport:ShowPrintDlg()

RpReport:ShowPrintDlg() Method

Purpose

Display the Windows common print dialog which allows the user to specify print options.

Syntax

<oRpReport>:ShowPrintDlg() LOGIC

Description

This method displays the print dialog which allows various print options to be set such as Print Quality, Print Range, Number of Copies to Print, etc. This method returns TRUE if the user exited the dialog by clicking on the OK button; FALSE if the CANCEL button was pressed.

Example

// Display the print dialog

oRpReport:ShowPrintDlg()


RpReport:ShowSetupDlg()

RpReport:ShowSetupDlg() Method

Purpose

Display the Windows common print setup dialog which allows the user to specify printer configuration information as well as select a different printer.

Syntax

<oRpReport>:ShowSetupDlg() LOGIC

Description

This method returns TRUE if the user exited the dialog by clicking on the OK button; FALSE if the CANCEL button was pressed.

Example

// Display the printer setup dialog

oRpReport:ShowSetupDlg()


Callback Methods

The rpreport object expects to receive an owner in its constructor. This object needs to or may implement several callback methods:

The following methods are for both the runtime and the designer DLL:

FileExit

RemoveChild

RpReportEnded

The following methods are for the design environment only

CrossTabReportyWizard

NewCrossTabReport

LabelReportWizard

NewLabelReport

NewReport

OpenReport

StandardReportWizard


CrossTabReportWizard()

CrossTabReportWizard() Method callback

Purpose

To inform the shell window that the user wishes to create a report via the Cross-Tab Report Wizard.

Syntax

<oOwner>:CrossTabReportWizard()

Description

This callback method is invoked when the user selects the File, New, Cross-Tab Report Wizard menu option from the RpReport design window. If the CrossTabReportWizard() method does not exist on the design window owner object, the File, New, Cross-Tab Report Wizard menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.

See Also: LabelReportWizard() and CrossTabReportWizard()


FileExit()

FileExit() Method callback

Purpose

To inform the shell window that the user wishes to terminate the application.

Syntax

<oOwner>:FileExit()

Description

This callback method is invoked when the user selects the File, Exit menu option from the RpReport design window. If the FileExit() method does not exist on the design window owner object, the File, Exit menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


NewCrossTabReport()

NewCrossTabReport() Method callback

Purpose

To inform the shell window that the user wishes to create a new cross-tab report.

Syntax

<oOwner>:NewCrossTabReport()

Description

This callback method is invoked when the user selects the File, New Cross-Tab Report menu option from the RpReport design window. If the NewCrossTabReport() method does not exist on the design window owner object, the File, New Cross-Tab Report menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


LabelReportWizard()

LabelReportWizard() Method callback

Purpose

To inform the shell window that the user wishes to create a report via the Label Report Wizard.

Syntax

<oOwner>:LabelReportWizard()

Description

This callback method is invoked when the user selects the File, New, Label Report Wizard menu option from the RpReport design window. If the LabelReportWizard() method does not exist on the design window owner object, the File, New, Label Report Wizard menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.

See Also: StandardReportWizard() and CrossTabReportWizard()


NewLabelReport()

NewLabelReport() Method callback

Purpose

To inform the shell window that the user wishes to create a new label report.

Syntax

<oOwner>:NewLabelReport()

Description

This callback method is invoked when the user selects the File, New Label Report menu option from the RpReport design window. If the NewLabelReport() method does not exist on the design window owner object, the File, New Label Report menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


NewReport()

NewReport() Method callback

Purpose

To inform the shell window that the user wishes to create a new report.

Syntax

<oOwner>:NewReport()

Description

This callback method is invoked when the user selects the File, New, Standard Report menu option from the RpReport design window. If the NewReport() method does not exist on the design window owner object, the File, New, Standard Report menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


OpenReport()

OpenReport() Method callback

Purpose

To inform the shell window that the user wishes to open an existing report.

Syntax

<oOwner>:OpenReport()

Description

This callback method is invoked when the user selects the File, Open menu option from the RpReport design window. If the OpenReport() method does not exist on the design window owner object, the File, Open menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


RemoveChild()

RemoveChild() Method callback

Purpose

To inform the shell window that report design window is closing. The shell window should remove the report design window from its list of children in response to this method.

Syntax

<oOwner>:RemoveChild(oRpReport)

Arguments

<oRpReport>

The RpReport object which has initiated this callback method.

Description

This callback method is invoked when the user closes the report design window if the RemoveChild() method exists on the design window owner object. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.


RpReportEnded()

RpReportEnded() Method callback

Purpose

This callback method is invoked after a report completes.

Syntax

<oOwner>:RpReportEnded(oRpReport)

Arguments

<oRpReport>

The RpReport object which has initiated this callback method.

Description

This callback method is invoked if it exists as a method of the report owner object. The report owner object is specified in the <oOwner> parameter of the RpReport:Init. This method is called when the report terminates to inform the owner object that the report has finished. This callback is generally not used for modal printing. It is provided to aid in the management of modeless print preview windows.


StandardReportWizard()

StandardReportWizard() Method callback

Purpose

To inform the shell window that the user wishes to create a report via the Standard Report Wizard.

Syntax

<oOwner>:StandardReportWizard()

Description

This callback method is invoked when the user selects the File, New, Standard Report Wizard menu option from the RpReport design window. If the StandardReportWizard() method does not exist on the design window owner object, the File, New, Standard Report Wizard menu option is removed from the design window menu. The owner object is specified in the <oOwner> parameter of the RpReport:Init.

Note: This callback method is only used by the report designer.

See Also: LabelReportWizard() and CrossTabReportWizard()


Multiple-Section Reports

A report is a collection of one or more sections, each section owns one data source (rpDataSource) object. In turn, the rpDataSource owns and manages one or more table level (rpSQLQuery and rpRDDTable) objects. The rpSQLQuery object provides a wrapper for a SQL query which is sent to a server via an ODBC driver. The rpRDDTable object provides a class wrapper for RDD based tables.

Due to the complexity of this hierarchical structure, reports containing multiple-sections present a challenge when trying to set runtime options at the data source or table level. For example, to change the sort order of the third section of a multiple-section report, you must traverse the report's section list to find the proper section before you can set its sort order.

In most cases, the <aDbfSwap> parameter of the RpReport:Init() can be used to substitute tables and indexes at runtime, however, it may be necessary to traverse a report's section list to set other options. The following code demonstrates how to traverse the section list to access the data source and table level objects:

LOCAL aSections, aTables AS ARRAY

LOCAL oSection AS rpSection

LOCAL oDataSource AS rpDataSource

aSections := oRpReport:Sections

nLen := alen(aSections)

FOR nLp := 1 UPTO nLen

// get the next section so we can change some

// settings on it. See the rpSection class.

oSection := aSections[nLp]

// get the section's datasource so we can

// interrogate and change some settings

// on the tables it contains

oDataSource := oSection:DataSource

// Now, we want to loop through the tables of

// the data source to get/set the table

// filename

nLen2 := aLen(oDataSource:Tables)

FOR nLp2 := 1 UPTO nLen2

? oDataSource:aTables[nLp2]:cTable

NEXT Lp2

NEXT nLp

Generally, you should not modify rpSection, rpDataSource, rpSQLQuery or rpRDDTable object attributes after the RpReport:Connect2Source() method has been called. This method opens the RDD tables and executes the SQL Queries contained in a report. Making changes after the method is called will either have no effect or will cause unpredictable results. The Connect2Source() method is called automatically by other methods of the RpReport class including Print(), PrintPreview() and ExpressionBuilder(). If you need to modify section or data source attributes, you should do so immediately after instantiating the RpReport object. An exception to this rule is if you need to get the value of a ReportPro user defined variable. In this case, the data source must be connected to retrieve the proper value from the variable.


RpSection Class

Purpose

The purpose of this class is to provide access to settings of individual sections in a multi-section report.

Properties

DataSource Access/Assign

Methods

ExpressionBuilder()

GetVariableValue()

SetVariableValue()

SetVarInitExpression()

SetVarUpdateExpression()


RpSection:DataSource

RpSection:DataSource Access/Assign
Type rpDataSource

Purpose

Get/Set the data source that provides information to the section.

Example

oDataSource := oSection:DataSource


RpSection:ExpressionBuilder()

RpSection:ExpressionBuilder() Method

Purpose

Display the ReportPro Expression Builder within the context of a specific section.

Syntax

<oRpSection>:ExpressionBuilder(oOwner, cCaption, cExpression, lAllowEmpty, lForceLogic) cExpression

Arguments

oOwner | The window owner of the Expression Builder dialog window.
cCaption | The caption of the Expression Builder dialog window.
cExpression | The initial expression displayed in the Expression Builder.
LAllowEmpty | Logic indicating if the Expression Builder should allow the user to return an empty ("") expression.
lForceLogic | Logic indicating if the expression (when evaluated) must return a logical value.

Description

Returns the new expression or cExpression if the user presses cancel.

Example

// Display the expression builder so the user

// can specify a filter.

cExp:=oRpSection:ExpressionBuilder(self, "My Caption",;

"Customer.Name='Smith'", true, true)


RpSection:GetVariableValue()

RpSection:GetVariableValue() Method

Purpose

To get the value of a ReportPro user defined variable in a section.

Syntax

<oRpSection>:GetVariableValue(cName) xValue

Arguments

cName

The name of the ReportPro variable.

Description

Returns the ReportPro variable value as a usual.

Note: It may be necessary to call RpReport:Connect2Source() before using this method. See the entry for RpReport:Connect2Source() for more information.

Example

// Print the value of a ReportPro variable.

? oRpSection:GetVariableValue("SectionHDR")


RpSection:SetVariableValue()

RpSection:SetVariableValue() Method

Purpose

To set the value of a ReportPro user defined variable in a section.

Syntax

<oRpSection>:SetVariableValue(cName, xValue) NIL

Arguments

cName | The name of the ReportPro variable.
xValue | The new variable value.

Example

// Change the variable used for the section title

oRpSection:SetVariableValue("SectionTitle", ;

"The New Report Title")


RpSection:SetVarInitExpression()

RpSection:SetVarInitExpression() Method

Purpose

To set the expression that initializes a ReportPro variable.

Syntax

<oRpSection>:SetVarInitExpression(cName, xExpression) LOGIC

Arguments

cName | The name of the ReportPro variable.
xExpression | This parameter can either be a string representing the expression to be macro compiled or a codeblock.

Description

The Init Expression of a variable is the expression that is evaluated to set the initial value of a ReportPro variable when the variable is reset. This method returns a TRUE if it is successful; otherwise, it returns false.

Example

oRpSection:SetVarInitExpression("MyVar", "0")

oRpSection:SetVarInitExpression("MyVar2", " 'string value' ")


RpSection:SetVarUpdateExpression()

RpSection:SetVarUpdateExpression() Method

Purpose

To set the update expression of a ReportPro variable.

Syntax

<oRpSection>:SetVarUpdateExpression(cName, xExpression) LOGIC

Arguments

cName | The name of the ReportPro variable.
xExpression | This parameter can either be a string representing the expression to be macro compiled or a codeblock.

Description

The Update Expression of a variable is the expression that is evaluated to update a ReportPro variable before the Body Band is printed. This method returns a TRUE if it is successful; otherwise, it returns false.

Example

oRpSection:SetVarUpdateExpression("MyVar", "0")

oRpSection:SetVarUpdateExpression("MyVar2", " 'string value' ")


RpDataSource Class

Purpose

The purpose of this class is to manage table level objects contained in a report.

Properties

FilterExpression Access/Assign

Tables Access


RpDataSource:FilterExpression

RpDataSource:FilterExpression Access/Assign
Type String

Purpose

To get/set an optional expression used as a filter. The filter determines which records are included in the section. The assigned value must be a valid expression or an empty string ("") to clear the filter expression.

Example

// Set the filter to include only customers named Smith

oDataSource:FilterExpression := " Customer.Name = 'Smith' "

// Clear the current filter

oDataSource:FilterExpression := ""


RpDataSource:Tables

RpDataSource:Tables Access
Type Array

Purpose

Get the array of tables in the data source. Having the array of tables allows access to information about the tables in a section. The objects in this array can be of two types: rpRDDTable or rpSQLQuery.

Example

aTables := oDataSource:Tables


RpRDDTable Class

Purpose

The purpose of this class is to provide a wrapper for RDD based tables.

Properties

Driver Access/Assign

Filename Access/Assign

Index Access/Assign

IndexTag Access/Assign

SeekExpression Access/Assign

StartRecord Access/Assign

WhileExpression Access/Assign

Description

Care should be taken when using this class to directly modify table information. Changes made to this class may have an adverse effect if used after RpReport:Connect2Source() has been called. See the discussion of RpReport:Connect2Source() for more information.


RpRDDTable:Driver

RpRDDTable:Driver Access/Assign
Type String

Purpose

Get/set the driver used for the table.

Description

The access returns the name of the RDD used to open the table (e.g. DBXNTX, DBFCDX, DBFMDX, etc).

Example

// Set the RDD

oTable:Driver := "DBFCDX"


RpRDDTable:Filename

RpRDDTable:Filename Access/Assign
Type String

Purpose

Get/set the full path and name of the table.

Example

// Print the full filename of the table

? oTable:Filename


RpRDDTable:Index

RpRDDTable:Index Access/Assign
Type String

Purpose

Get/set the filename of the index to be used by the table.

Example

// Print the index name

? oTable:Index


RpRDDTable:IndexTag

RpRDDTable:IndexTag Access/Assign
Type String

Purpose

Get/set the index tag name.

Example

// Print the index tag

? oTable:IndexTag


RpRDDTable:SeekExpression

RpRDDTable:SeekExpression Access/Assign
Type String

Purpose

To get/set the table seek expression. If a seek expression is specified, it is evaluated at the beginning of the report prior to printing. The value returned from the seek expression is used to perform a soft seek against the index of the table. After the seek is performed, reporting starts. The assigned value must be a valid expression or an empty string ("") to clear the seek expression. This access/assign is only valid for the first table in a data source.

Example

// To force an inventory report to start at a

// certain part number

oTable:SeekExpression := " padr('3173081',20) "

// Clear the seek expression

oTable:SeekExpression := ""


RpRDDTable:StartRecord

RpRDDTable:StartRecord Access/Assign
Type Numeric

Purpose

Get/set the starting record number for the table. This access/assign is only valid for the first table in a data source.

Example

// Set the starting record to 3

oTable:StartRecord := 3


RpRDDTable:WhileExpression

RpRDDTable:WhileExpression Access/Assign
Type String

Purpose

To get/set an optional expression used to implement a print while condition. Records are included into the section until the while expression returns FALSE (or there is no more records to process). This must be a valid expression or an empty string ("") to clear the while condition. This access/assign is only valid for the first table in a data source.

Example

// keep producing the report until you find

// a name that begins with "H" or greater

oTable:WhileExpression := "Customer.Name < 'G' "


RpSQLQuery Class

Purpose

The purpose of this class is to provide a wrapper for SQL SELECT statements.

Properties

SQLColDelim Access/Assign RDD/SQL & Design Only

SQLDistinct Access/Assign RDD/SQL & Design Only

SQLFrom Access/Assign RDD/SQL & Design Only

SQLGroupBy Access/Assign RDD/SQL & Design Only

SQLHaving Access/Assign RDD/SQL & Design Only

SQLOrderBy Access/Assign RDD/SQL & Design Only

SQLUnion Access/Assign RDD/SQL & Design Only

SQLUserCols Access/Assign RDD/SQL & Design Only

SQLWhere Access/Assign RDD/SQL & Design Only

Description

Changes to this class may have an adverse effect if used after RpReport:Connect2Source() has been called. See the discussion of RpReport:Connect2Source() for more information.


RpSQLQuery:SQLColDelim

RpSQLQuery:SQLColDelim Access/Assign
Type String

Purpose

To get/set the delimiter used the rpSQLQuery object to delimit SQL identifiers. By setting this value, you can force the rpSQLQuery object to use a different identifier delimiter than that returned by the ODBC driver.

Example

// To force ReportPro to use ` as the delimiter

oQuery:SQLColDelim := "`"


RpSQLQuery:SQLDistinct

RpSQLQuery:SQLDistinct Access/Assign
Type Logic

Purpose

To determine or set whether or not the DISTINCT keyword is used in the SQL SELECT statement. Setting this assign to TRUE forces the rpSQLQuery object to include the DISTINCT keyword when a SQL SELECT statement is issued.

Example

// Force ReportPro to issue SELECT DISTINCT for this query

oQuery:SQLDistinct := TRUE


RpSQLQuery:SQLFrom

RpSQLQuery:SQLFrom Access/Assign
Type String

Purpose

To get/set the FROM clause in the SQL SELECT statement. Generally, the use of this assign should be avoided since the rpSQLQuery object automatically manages the FROM clause.


RpSQLQuery:SQLGroupBy

RpSQLQuery:SQLGroupBy Access/Assign
Type String

Purpose

To get/set the GROUP BY clause in the SQL SELECT statement. This assign allows you to set the grouping performed by the SQL server. Do not confuse this assign with ReportPro's grouping. ReportPro performs it's grouping locally, independent of any grouping performed by the SQL server.


RpSQLQuery:SQLHaving

RpSQLQuery:SQLHaving Access/Assign
Type String

Purpose

To get/set the HAVING clause in the SQL SELECT statement. This assign works with the SQLGroupBy assign and is passed directly to the SQL server.


RpSQLQuery:SQLOrderBy

RpSQLQuery:SQLOrderBy Access/Assign
Type String

Purpose

To get/set the ORDER BY clause in the SQL SELECT statement. This assign determines the sort order of the query and is passed directly to the SQL server.


RpSQLQuery:SQLUnion

RpSQLQuery:SQLUnion Access/Assign
Type String

Purpose

To get/set the UNION clause in the SQL SELECT statement. This assign allows you to specify unions to be performed by the SQL server.


RpSQLQuery:SQLUserCols

RpSQLQuery:SQLUserCols Access/Assign
Type String

Purpose

To get/set the user defined column section of the SQL SELECT statement. This assign allows you to request calculated columns from the SQL server.


RpSQLQuery:SQLWhere

RpSQLQuery:SQLWhere Access/Assign
Type String

Purpose

To get/set the optional filtering condition in the SQL SELECT statement. Internally, the rpSQLQuery object stores the select statement in distinct chunks. This allows sections of the SELECT statement to be manipulated without disrupting other sections which are automatically maintained by the rpSQLQuery object. The expression must be a valid expression to the ODBC driver and/or SQL server.

Example

// Set SQL filter to show customers in California

oQuery:SQLWhere := "customer.state = 'CA'"


RpPrinter & PtrDevice Class Overview

The PtrDevice (Printer Device) class is a complete low-level printing class. It is a base class built completely around the Windows API. As such, it contains many methods that allow you to manipulate Window's PRINTDLG, DEVMODE and DEVNAMES structures.

The PtrDevice class completely integrates the printing and print preview tasks. When you code for the printer class, you write the report once and use the same code for both printing and print preview. In fact, your code doesn't even have to know which activity is taking place.

The RpPrinter class subclasses the PtrDevice and provides additional functionality to simplify the task of hand coding reports. The RpPrinter class is designed to allow you to create reports in a manor similar to reports created with CA-Clipper.

The source code for both classes is included with ReportPro in the SDK directory. We have also provided the binary entities for both the print preview window and the printing in progress window. The code provided is line-for-line equivalent to what we use in the ReportPro design environment. You can even modify the code for the PrintPreview and have ReportPro use your modified PrintPreview class.

There are some not so obvious advantages to this approach. As developers we are always running up against the limitations of our tools. Report writers are no exception. In DOS, the solution was simple, you hand coded reports that could not be done with a report writer.

In Windows, printing is not so simple. Having access to our printer class provides an elegant solution to the problem. First, use the ReportPro reporting engine for the reports that naturally lend themselves to report writers and hand code the balance using our printer classes. Your users will not be able to tell the difference between reports created with ReportPro and your hand coded reports. After all, your hand coded reports will use the same print interface and print preview window as we do!


PtrDevice Class

Purpose

The purpose of this class is to provide access to the Windows printer facilities in an enhanced fashion.

Properties

AllPages

BottomMargin

CollateCopies

Color

Copies

CurrentPageNumber

DefaultPaperSource

DeviceContext

DeviceModeFields

DisablePrint2File

Duplex

ExportObject

FromPage

HidePrint2File

HPixelsPerInch

InPreview

InPrint

IsValid

Landscape

LeftMargin

LogPaperLength

LogPaperWidth

LogPixelsPerInchX

LogPixelsPerInchY

LogPrintAreaLength

LogPrintAreaWidth

MaxPage

Access/Assign

Access/Assign

Access/Assign

Access/Assign

Access/Assign

Access

Access/Assign

Access

Access

Assign

Access/Assign

Access

Access/Assign

Assign

Access

Access

Access

Access

Access/Assign

Access/Assign

Access

Access

Access/Assign

Access/Assign

Access

Access

Assign

MinPage

NoPageNums

NoSelection

PageNums

PaperLength

PaperLengthInches

PaperSize

PaperWidth

PaperWidthInches

Print2File

PrintDlgFlags

PrinterDeviceContext

PrinterDriver

PrinterName

PrinterPort

PrintQuality

PrintWindow

PromptForFile

PromptForPrintDlg

Quit

RightMargin

Selection

ToPage

TopMargin

VPixelsPerInch

XPrinterRes

YPrinterRes

Assign

Assign

Assign

Access/Assign

Access/Assign

Access

Access/Assign

Access/Assign

Access

Access/Assign

Access/Assign

Access

Access

Access

Access

Access/Assign

Access

Access/Assign

Access/Assign

Access

Access/Assign

Access/Assign

Access/Assign

Access/Assign

Access

Access/Assign

Access/Assign

Methods

CreatePrinterDC

CreatePrinterIC

GetPaperBins

GetPaperSizes

GetPrinters

Init

Print

PrintExport

PrintPreview

QuitPreview SetPrinterByName

SetPrinterByPort

SetPrinterToDefault

ShowExportDlg

ShowPrintDlg

ShowSetupDlg

Callback Methods

The following methods are automatically called by the PtrDevice object during printing if they exist as methods of the Report object. The Report object is the object which is specified in the second parameter of the PtrDevice:Init().

PrintEnd

PrintPageBody

PrintPageFooter

PrintPageHeader

PrintPostBody

PrintPreBody

PrintSetPage

PrintStart

Description

The PtrDevice class gives you access to the Windows printer system and guides the production of your output in an event driven manor. To use the PtrDevice class, you must instantiate a PtrDevice object, perform desired initialization and call the Print() or PrintPreview() method.

Once you call the Print() or PrintPreview() method, the PtrDevice gathers output for the report by calling the callback methods identified above. The callback methods are invoked only if they exist as part of the Report object (the object passed as the second parameter of the PtrDevice instantiation). The methods (if they exist) are called in the following order:

// called once to allow for initialization

PrintStart()

// called before PreBody

PrintSetPage()

// called once (useful for title page,

// table of contents, etc.)

PrintPreBody()

// loop for each page

// each of the below methods are called

// once for each page

PrintSetPage()

PrintPageHeader()

PrintPageBody()

PrintPageFooter()

// Loop ends when PRINT_NOMORE or

// PRINT_ERROR is returned

// from PrintPageBody()

// called once (useful for

// report totals, footnotes etc.)

PrintPostBody()

// called once to allow for clean up.

PrintEnd()

Example

The PTR_EX sample program is a good example of PtrDevice class usage. Even though the samples use the RpPrinter class, they illustrate the proper use of the callback methods.


PtrDevice:AllPages

PtrDevice:AllPages Access/Assign
Type Logic

Purpose

To get/set the ALLPAGES bit of the PRINTDLG.FLAGS member.

The access returns TRUE if the PRINTDLG structure FLAGS member has the ALLPAGES bit set. When queried after the Print Dialog Window is shown, it indicates that the user selected the All Pages radio button.

The assign sets (or clears) the ALLPAGES bit of the PRINTDLG.FLAGS member. TRUE forces the All Pages radio button to be initially selected when the Print Dialog Window is presented.

Example

// Force the All Pages radio button of the Print

// dialog window to be selected

oPtrDevice:AllPages := True


PtrDevice:BottomMargin

PtrDevice:BottomMargin Access/Assign
Type Float

Purpose

To get/set the bottom margin (in inches) of the PtrDevice.

Example

// Set the bottom margin to one inch

oPtrDevice:BottomMargin := 1.00


PtrDevice:CollateCopies

PtrDevice:CollateCopies Access/Assign
Type Logic

Purpose

To get/set the COLLATE bit of the PRINTDLG.FLAGS member.

The access returns TRUE if the PRINTDLG structure FLAGS member has the COLLATE bit set. When queried after the Print Dialog Window is shown, it indicates that the user selected the Collate Copies check box.

The assign sets (or clears) the COLLATE bit of the PRINTDLG.FLAGS member. It forces the Collate Copies check box to be selected when the Print Dialog Window is presented.

Example

// Set the Collate Copies checkbox

oPtrDevice:CollateCopies := True

oPtrDevice:ShowPrintDlg()

Note: Collation is handled automatically by the PtrDevice class


PtrDevice:Color

PtrDevice:Color Access/Assign
Type Logic

Purpose

To get/set the DEVMODE.dmCOLOR member.

The access returns TRUE if the DEVMODE structure dmCOLOR member indicates that the printer is commanded to print color.

The assign sets the DEVMODE.dmCOLOR structure member. If TRUE, the printer is set for color, otherwise, it is set for monochrome.

Example

// Check whether the printer is set for color

if oPtrDevice:Color

// use color when printing

else

// do not need to worry about color

endif


PtrDevice:Copies

PtrDevice:Copies Access/Assign
Type Word

Purpose

To get/set the DEVMODE.dmCOPIES member.

The access returns the DEVMODE structure dmCopies member. When queried after the Print Dialog Window has been shown, it indicates how many copies the user wants to print.

The assign sets the DEVMODE.dmCopies member. When set before the Print Dialog Window is displayed, it initialized the Copies edit.

Example

// How many copies does the user want?

oPtrDevice:ShowPrintDlg()

nNumberOfCopies := oPtrDevice:Copies

Note: The printing of multiple copies is automatically handled by the PtrDevice class if the CollatedCopies option is set; otherwise, it is handled by the printer driver.


PtrDevice:CurrentPageNumber

PtrDevice:CurrentPageNumber Access
Type Word

Purpose

To get the current page number during a Print() or PrintPreview().

Example

// What page are we on?

nPageNo := oPtrDevice:CurrentPageNumber


PtrDevice:DefaultPaperSource

PtrDevice:DefaultPaperSource Access/Assign
Type ShortInt

Purpose

To get/set the DEVMODE.dmDefaultSource member.

The access returns the DEVMODE.dmDefaultSource structure member which indicates the default paper source of the printer. WARNING: This access is not supported by all printers and can return 0.

The assign sets the default paper source for the selected printer. Supported values are:

DMBIN_AUTO | DMBIN_CASSETTE
DMBIN_ENVELOPE | DMBIN_ENVMANUAL
DMBIN_FIRST | DMBIN_LARGECAPACITY
DMBIN_LARGEFMT | DMBIN_LAST
DMBIN_LOWER | DMBIN_MANUAL
DMBIN_MIDDLE | DMBIN_ONLYONE
DMBIN_SMALLFMT | DMBIN_TRACTOR
DMBIN_UPPER | DMBIN_USER

These values are the same as those defined in the Windows SDK. Please refer to the Window's SDK for more information concerning these values.

Example

if oPtrDevice:DefaultPaperSource == DMBIN_ENVELOPE

// the printer is mainly used for envelopes

endif


PtrDevice:DeviceContext

PtrDevice:DeviceContext Access
Type HDC (16-bit: WORD, 32-bit: PTR)

Purpose

To retrieve the device context of the printer or print preview metafile context during a Print() or PrintPreview().

Example

// Print some text on the printer device

TextOut(oPtrDevice:DeviceContext,10,10,string2psz("Hello"),5)

Description

ReportPro uses metafile technology to produce the PrintPreview rather than a simple device context. Some Windows API functions behave differently in a metafile device context and some do not work at all. For more information, see the Windows API reference.

Note: Do not destroy this device context. It is automatically managed by the PtrDevice class.


PtrDevice:DeviceModeFields

PtrDevice:DeviceModeFields Access
Type DWORD

Purpose

This access returns the DEVMODE.dmFields member.


PtrDevice:DisablePrint2File

PtrDevice:DisablePrint2File Assign
Type Logic

Purpose

To set (TRUE) or clear (FALSE) the PRINTDLG.FLAGS member DISABLEPRINTTOFILE bit which disables/enables the print to file option in the Print Dialog Window.

Example

// Don't allow the user to select Print To File

oPtrDevice:DisablePrint2File := True

oPtrDevice:ShowPrintDlg()


PtrDevice:Duplex

PtrDevice:Duplex Access/Assign
Type ShortInt

Purpose

To get/set the DEVMODE.dmDUPLEX member. The access returns the duplex mode of the printer.

The assign sets the DEVMODE.dmDUPLEX structure member thus specifying duplex printing. Valid options are DMDUP_SIMPLEX, DMDUP_HORIZONTAL, and DMDUP_VERTICAL

Example

// Does the user want duplex printing?

if oPtrDevice:Duplex

...

endif


PtrDevice:ExportObject

PtrDevice:ExportObject Access
Type Object

Purpose

This access returns the export object created by the print export dialog. For more information, see the PtrDevice:ShowExportDlg() method.


PtrDevice:FromPage

PtrDevice:FromPage Access/Assign
Type Word

Purpose

To get/set the PRINTDLG.nFROMPAGE member.

The access returns the PRINTDLG structure nFROMPAGE member. When queried after the Print Dialog Window is shown, it indicates the first page the user wants to print.

This assign sets the PRINTDLG structure nFROMPAGE member. When set before the Print Dialog Window is presented, it sets the default Print From Page value.

Example

// What page does the user want to start on?

oPtrDevice:ShowPrintDlg()

nFromPage := oPtrDevice:FromPage

Note: Page range restricted printing is handled automatically by the PtrDevice class.


PtrDevice:HidePrint2File

PtrDevice:HidePrint2File Assign
Type Logic

Purpose

To set (TRUE) or clear (FALSE) the PRINTDLG.FLAGS structure member HIDEPRINTTOFILE bit which hides (TRUE) or shows (FALSE) the Print To File option in the Print Dialog Window.

Example

// Hide the Print To File check box from the user

oPrtDevice:HidePrint2File := True

oPtrDevice:ShowPrintDlg()


PtrDevice:HPixelsPerInch

PtrDevice:HPixelsPerInch Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns the horizontal resolution of the printer (pixels per inch). This value is generally the same as the PtrDevice:XPrinterRes except this access uses GetDeviceCaps(LOGPIXELSX) to get the printer resolution.

Example

// get the horizontal pixels per inch

? oPtrDevice:HPixelsPerInch


PtrDevice:InPreview

PtrDevice:InPreview Access
Type Logic

Purpose

Returns TRUE if the PtrDevice is currently in the PrintPreview() mode; FALSE, otherwise.

Example

// Is this PtrDevice currently in a Print Preview mode?

if oPtrDevice:InPreview

...

endif


PtrDevice:InPrint

PtrDevice:InPrint Access
Type Logic

Purpose

Returns TRUE if the PtrDevice is currently in Print() mode; FALSE, otherwise.

Example

// Is this PtrDevice object in print to printer mode

if oPtrDevice:InPrint

...

endif


PtrDevice:IsValid

PtrDevice:IsValid Access
Type Logic

Purpose

Returns TRUE if the PtrDevice object is valid. The printer device is invalid when there is no default printer device selected in the Windows Control Panel, or if the printer device cannot allocate enough memory.

Example

// Is this PtrDevice a valid printer object?

if oPtrDevice:IsValid

oPtrDevice:Print(...)

endif


PtrDevice:Landscape

PtrDevice:Landscape Access/Assign

Type Logic

Purpose

The access returns TRUE if the printer is set to print landscape.

The assign sets the DEVMODE.dmORIENTATION structure member. If TRUE, the printer is set for landscape printing, otherwise, it is set for portrait.

Example

// Is the printer set to landscape mode?

oPtrDevice:ShowPrintDlg()

if oPtrDevice:Landscape

...

endif


PtrDevice:LeftMargin

PtrDevice:LeftMargin Access/Assign
Type Float

Purpose

To get/set the left margin (in inches) of the PtrDevice. The left margin setting affects the origin of the device context. The device context origin is at the Top/Left margin.

Example

// Set the left margin

oPtrDevice:LeftMargin := 1.0


PtrDevice:LogPaperLength

PtrDevice:LogPaperLength Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

This access returns the number of logical vertical pixels on a given sheet of paper. This value is based on the number of vertical pixels per inch in the window that owns the printer device. This value is scaled to fill the actual print page.

Example

// Print the next line if I have room

if nCurrentLine < oPrtDevice:LogPaperLength

// print a line

endif


PtrDevice:LogPaperWidth

PtrDevice:LogPaperWidth Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

This access returns the number of logical horizontal pixels on a given sheet of paper. This value is based on the number of horizontal pixels per inch in the window that owns the printer device. This value is scaled to fill the actual print page.

Example

// How much horizontal room do I have for this line?

nHorizontalRoom := oPtrDevice:LogPaperWidth


PtrDevice:LogPixelsPerInchX

PtrDevice:LogPixelsPerInchX Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns the number of horizontal logical pixels per inch of the printer device.

Example

// How many horizontal pixels per inch?

? oPtrDevice:LogPixelsPerInchX


PtrDevice:LogPixelsPerInchY

PtrDevice:LogPixelsPerInchY Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns the number of vertical logical pixels per inch of the printer device.

Example

// How many vertical pixels per inch?

? oPtrDevice:LogPixelsPerInchY


PtrDevice:LogPrintAreaLength

PtrDevice:LogPrintAreaLength Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns PtrDevice:LogPaperLength minus the area occupied by the top and bottom margins.

Example

// How much room is there vertically between the margins?

nVerticalSpace := oPtrDevice:LogPrintAreaLength


PtrDevice:LogPrintAreaWidth

PtrDevice:LogPrintAreaWidth Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns PtrDevice:LogPaperWidth minus the area occupied by the left and right margins.

Example

// Get the horizontal space between the margins

nLineWidth := oPtrDevice:LogPrintAreaWidth


PtrDevice:MaxPage

PtrDevice:MaxPage Assign
Type Word

Purpose

This assign sets the PRINTDLG structure nMAXPAGE member value. When set before the Print Dialog Window is shown, it determines the maximum page number the user can enter in the Print To Page edit.

Example

// Do not let the user print beyond page 12

oPtrDevice:MaxPage := 12


PtrDevice:MinPage

PtrDevice:MinPage Assign
Type Word

Purpose

This assign sets the PRINTDLG structure nMINPAGE member value. When set before the Print Dialog Window is shown, it determines the minimum page number the user can enter in the Print From Page edit.

Example

// Do not let the user choose to print before page 5

oPtrDevice:MinPage := 5


PtrDevice:NoPageNums

PtrDevice:NoPageNums Assign
Type Logic

Purpose

This assign sets (TRUE) or clears (FALSE) the PRINTDLG.FLAGS member NOPAGENUMS bit which disables (TRUE) or enables (FALSE) the Pages radio button in the Print Dialog Window.

Example

// Do not let the user choose a page range to print

oPtrDevice:NoPageNums := True

self:ShowPrintDlg()


PtrDevice:NoSelection

PtrDevice:NoSelection Assign
Type Logic

Purpose

This assign sets (TRUE) or clears (FALSE) the PRINTDLG.FLAGS member NOSELECTION bit which disables (TRUE) or enables (FALSE) the Selection radio button in the Print Dialog Window.

Example

// Do not let the user choose to print

// the current selection

oPtrDevice:NoSelection := True


PtrDevice:PageNums

PtrDevice:PageNums Access/Assign
Type Logic

Purpose

The access returns TRUE if the PRINTDLG.FLAGS member has the PAGENUMS bit set. When queried after the Print Dialog Window is shown, it indicates that the user selected the Pages radio button.

The assign sets (TRUE) or clears (FALSE) the PAGENUMS bit of the PRINTDLG.FLAGS member which causes the Pages radio button to be selected by default when the Print Dialog Window is presented.

Example

// Set the Pages radio button as selected

oPtrDevice:PageNums := True

oPtrDevice:ShowPrintDlg()

Note: Page range restricted printing is handled automatically by the PtrDevice class.


PtrDevice:PaperLength

PtrDevice:PaperLength Access/Assign
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

The access returns the length of the selected paper in tenths of millimeters. WARNING: This access can return 0. Normally, you should use the PtrDevice:PaperLengthInches access.

The assign lets you specify the length of the paper in millimeters. WARNING: This assign is not supported by all printer drivers.

Example

// What is the paper length in millimeters?

nPaperLength := oPtrDevice:PaperLength

if nPaperLength > 0

// can use this value

endif


PtrDevice:PaperLengthInches

PtrDevice:PaperLengthInches Access
Type Float

Purpose

This access returns the length of the selected paper in inches.

Example

// What is the paper length in inches?

nPaperLengthInInches := oPtrDevice:PaperLengthInches


PtrDevice:PaperSize

PtrDevice:PaperSize Access/Assign
Type ShortInt

Purpose

The access returns the dmPAPERSIZE member of the DEVMODE structure. dmPAPERSIZE is defined by manifest constants which represent predetermined page sizes. WARNING: This access can return 0. In most cases you should use PtrDevice:PaperLengthInches or PtrDevice:PaperWidthInches.

The assign sets the dmPAPERSIZE member of the DEVMODE structure. WARNING: This assign is not supported by all printer drivers.

Supported values are:

DMPAPER_LETTER Letter, 8 1/2 x 11 in.

DMPAPER_LETTERSMALL Letter Small, 8 1/2 x 11 in.

DMPAPER_TABLOID Tabloid, 11 x 17 in.

DMPAPER_LEDGER Ledger, 17 x 11 in.

DMPAPER_LEGAL Legal, 8 1/2 x 14 in.

DMPAPER_STATEMENT Statement, 5 1/2 x 8 1/2 in.

DMPAPER_EXECUTIVE Executive, 7 1/2 x 10 1/2 in.

DMPAPER_A3 A3, 297 x 420 mm

DMPAPER_A4 A4, 210 x 297 mm

DMPAPER_A4SMALL A4 Small, 210 x 297 mm

DMPAPER_A5 A5, 148 x 210 mm

DMPAPER_B4 B4, 250 x 354 mm

DMPAPER_B5 B5, 182 x 257 mm

DMPAPER_FOLIO Folio, 8 1/2 x 13 in.

DMPAPER_QUARTO Quarto, 215 x 275 mm

DMPAPER_10X14 10 x 14 in.

DMPAPER_11X17 11 x 17 in.

DMPAPER_NOTE Note, 8 1/2 x 11 in.

DMPAPER_ENV_9 Envelope #9, 3 7/8 x 8 7/8 in.

DMPAPER_ENV_10 Envelope #10, 4 1/8 x 9 1/2 in.

DMPAPER_ENV_11 Envelope #11, 4 1/2 x 10 3/8 in.

DMPAPER_ENV_12 Envelope #12, 4 1/2 x 11 in.

DMPAPER_ENV_14 Envelope #14, 5 x 11 1/2 in.

DMPAPER_CSHEET C size sheet

DMPAPER_DSHEET D size sheet

DMPAPER_ESHEET E size sheet

DMPAPER_ENV_DL Envelope DL, 110 x 220 mm

DMPAPER_ENV_C3 Envelope C3, 324 x 458 mm

DMPAPER_ENV_C4 Envelope C4, 229 x 324 mm

DMPAPER_ENV_C5 Envelope C5, 162 x 229 mm

DMPAPER_ENV_C6 Envelope C6, 114 x 162 mm

DMPAPER_ENV_C65 Envelope C65, 114 x 229 mm

DMPAPER_ENV_B4 Envelope B4, 250 x 353 mm

DMPAPER_ENV_B5 Envelope B5, 176 x 250 mm

DMPAPER_ENV_B6 Envelope B6, 176 x 125 mm

DMPAPER_ENV_ITALY Envelope, 110 x 230 mm

DMPAPER_ENV_MONARCH Envelope Monarch, 3 7/8 x 7 1/2 in.

DMPAPER_ENV_PERSONAL Envelope, 3 5/8 x 6 1/2 in.

DMPAPER_FANFOLD_US U.S. Standard Fanfold, 14 7/8 x 11 in.

DMPAPER_FANFOLD_STD_GERMAN German Standard Fanfold, 8 1/2 x 12 in.

DMPAPER_FANFOLD_LGL_GERMAN German Legal Fanfold, 8 1/2 x 13 in.

Example

// Set the paper size to A4

oPtrDevice:PaperSize := DMPAPER_A4


PtrDevice:PaperWidth

PtrDevice:PaperWidth Access/Assign
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

The access returns the width of the selected paper in tenths of millimeters. WARNING: This access can return 0. Normally, you should use the PtrDevice:PaperWidthInches access.

The assign allows you specify the width of the paper in millimeters. WARNING: This assign is not supported by all printer drivers.

Example

// What is the paper length in millimeters?

nPaperWidth := oPtrDevice:PaperWidth

if nPaperWidth > 0

// can use this value

endif


PtrDevice:PaperWidthInches

PtrDevice:PaperWidthInches Access
Type Float

Purpose

This access returns the width of the selected paper in inches.

Example

// What is the paper width in inches?

nPaperWidthInInches := oPtrDevice:PaperWidthInches


PtrDevice:Print2File

PtrDevice:Print2File Access/Assign
Type Logic

Purpose

The access returns TRUE if the PRINTDLG.FLAGS member has the PRINTTOFILE bit set. When queried after the Print Dialog Window is shown, it indicates whether the user selected the Print To File check box.

The assign sets (TRUE) or clears (FALSE) the PRINTTOFILE bit of the PRINTDLG.FLAGS member. This causes the Print To File check box to be checked by default when the Print Dialog Window is shown.

Example

// Show the print dialog with the print to file box checked

oPtrDevice:Print2File := True

oPtrDevice:ShowPrintDlg()


PtrDevice:PrintDlgFlags

PtrDevice:PrintDlgFlags Access/Assign
Type DWord

Purpose

The access returns the PRINTDLG.FLAGS member.

The assign sets the PRINTDLG.FLAGS structure member which governs how the Print Dialog Window looks and behaves.

The PRINTDLG structure is a standard Windows common dialog structure. Please refer to the Windows SDK reference for more information about this structure.

Example

// Is the collate button checked?

if _and(oPtrDevice:PrintDlgFlags, PD_COLLATE)

// collate has been set

endif


PtrDevice:PrinterDeviceContext

PtrDevice:PrinterDeviceContext Access
Type HDC (16-bit: WORD, 32-bit PTR)

Purpose

To retrieve the printer device context during a Print() or PrintPreview(). At the beginning of a print preview, the PtrDevice creates a print preview memory context and a device context for the current printer. The printer device context is provided to allow you to retrieve font information from the printer driver so that text can be placed in the print preview window as it would appear on the printer. During a print operation, this access returns PtrDevice:DeviceContext.

Example

// Get font information from the printer driver

hDC      := oPtrDevice:PrinterDeviceContext

hOldFont := SelectObject(hDC, hNewFont)

GetTextMetrics(hDC, @sWinTextMetrics)

SelectObject(hDC, hOldFont)

Note: Do not destroy this device context. It is automatically managed by the PtrDevice class.


PtrDevice:PrinterDriver

PtrDevice:PrinterDriver Access
Type String

Purpose

This access returns the name of the currently selected printer driver.

Example

// Get the name of the printer driver

cDriverName := oPtrDevice:PrinterDriver


PtrDevice:PrinterName

PtrDevice:PrinterName Access
Type String

Purpose

This access returns the name of the currently selected printer.

Example

// What is the name of the printer (not the driver name)

cPrinterName := oPtrDevice:PrinterName


PtrDevice:PrinterPort

PtrDevice:PrinterPort Access
Type String

Purpose

This access returns the port that the currently selected printer driver is connected to.

Example

// What port are we printing to?

cPort := oPtrDevice:PrinterPort


PtrDevice:PrintQuality

PtrDevice:PrintQuality Access/Assign
Type ShortInt

Purpose

The access returns the DEVMODE.dmPRINTQUALITY member which indicates the quality of the printed output.

If the return value is positive, it indicates the dots per inch of the printer. If DEVMODE.dmYResolution is initialized, dmPrintQuality represents the x-resolution otherwise it represents both the x and y resolutions.

If the member is negative, it represents a device independent resolution.

The assign sets the DEVMODE.dmPRINTQUALITY structure member which indicates the quality of the printed output.

If the value is positive, it indicates the pixels per inch of the printer. If the DEVMODE.dmYResolution is initialized, this affects the x-resolution; otherwise, it affects both the x and y resolutions.

If the value is negative, it represents a device independent resolution.

Example

// Set the print quality to 300 dpi

oPtrDevice:PrintQuality := 300


PtrDevice:PrintWindow

PtrDevice:PrintWindow Access
Type Window

Purpose

This access returns the Print Preview window if the PtrDevice is in Print Preview mode or the Print Message dialog window if it is in the Print mode. Otherwise, this access returns NULL_OBJECT.

Example

// Get the print preview window

oWnd := oPtrDevice:PrintWindow


PtrDevice:PromptForFile

PtrDevice:PromptForFile Access/Assign
Type Logic

Purpose

This access/assign determines whether the user will be prompted for a file name when printing to file. If set TRUE, a dialog window is displayed when printing is initiated and the PtrDevice:PrintToFile option is set to true. The default value is TRUE.

Example

// If the user chooses to print to file, don't prompt

// for a file name

oPtrDevice:PromptForFile := False


PtrDevice:PromptForPrintDlg

PtrDevice:PromptForPrintDlg Access/Assign
Type Logic

Purpose

This access/assign determines whether the Print Dialog is displayed when the user selects the print button from the Print Preview window. The default is TRUE.

Example

// Do not show the print dialog when the user press

// Print from Preview

oPtrDevice:PromptForPrintDlg := False


PtrDevice:Quit

PtrDevice:Quit Access
Type Logic

Purpose

This access returns TRUE if the PtrDevice object is in the Print() or PrintPreview() mode and the user has selected the CANCEL button on the displayed dialog window. You should regularly check this access while in the PtrDevice callback functions. If this access returns TRUE, you should return immediately so the PtrDevice can terminate the print/preview operation in a timely manor.

Example

// Regularly check if the user pressed

// the Cancel button

method PrintPageBody(oPtrDevice) class MyReport

  do while ...

     if oPtrDevice:Quit

        // stop printing

        return PRINT_NOMORE

     endif

  enddo


PtrDevice:RightMargin

PtrDevice:RightMargin Access/Assign
Type Float

Purpose

To set/get the right margin (in inches) of the PtrDevice.

Example

// Set the right margin to one inch

oPtrDevice:RightMargin := 1.0


PtrDevice:Selection

PtrDevice:Selection Access/Assign
Type Logic

Purpose

The access returns TRUE if the PRINTDLG.FLAGS member has the SELECTION bit set. When queried after the Print Dialog Window is shown, it indicates that the user chose the selection radio button.

The assign sets (TRUE) or clears (FALSE) the PRINTDLG.FLAGS member SELECTION bit. Setting this to TRUE causes the Selection radio button to be selected by default when the Print Dialog Window is shown.

Example

// Did the user click the Selection radio button in the

// print dialog?

if oPtrDevice:Selection

// print only the currently selected text

endif


PtrDevice:ToPage

PtrDevice:ToPage Access/Assign
Type ShortInt

Purpose

The access returns the PRINTDLG.nTOPAGE member. When queried after the Print Dialog Window is shown, it indicates the last page the user wants to print.

The assign sets the PRINTDLG.nTOPAGE member. When set before the Print Window is presented, it sets the default Print To Page edit value.

Example

// To what page does the user want to print?

nLastPage := oPtrDevice:ToPage


PtrDevice:TopMargin

PtrDevice:TopMargin Access/Assign
Type Float

Purpose

To set/get the top margin (in inches) of the PtrDevice. The top margin affects the origin of the device context. The device context origin is at the Top/Left margin.

Example

// Set the top margin to one inch

oPtrDevice:TopMargin := 1.0


PtrDevice:VPixelsPerInch

PtrDevice:VPixelsPerInch Access
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

Returns the vertical resolution of the printer (pixels per inch).

Example

? oPtrDevice:VPixelsPerInch


PtrDevice:XPrinterRes

PtrDevice:XPrinterRes Access/Assign
Type ShortInt

Purpose

The access returns the DEVMODE.dmPRINTQUALITY member which indicates the quality of the printed output.

If the return value is positive, it indicates the dots per inch of the printer. If DEVMODE.dmYRESOLUTION is initialized, dmPRINTQUALITY represents the x-resolution otherwise it represents both the x and y resolutions.

If the member is negative, it represents a device independent resolution.

The assign sets the DEVMODE.dmPRINTQUALITY structure member which indicates the quality of the printed output.

If the value is positive, it indicates the dots per inch of the printer. If the DEVMODE.dmYRESOLUTION is initialized, this affects the x-resolution; otherwise, it affects both the x and y resolutions.

If the value is negative, it represents a device independent resolution.

Example

// Is the X printer resolution device independent?

if oPtrDevice:XPrinterRes < 0

// yes, it is

endif


PtrDevice:YPrinterRes

PtrDevice:YPrinterRes Access/Assign
Type ShortInt

Purpose

The access returns the DEVMODE.dmYRESOLUTION member which represents the printer's vertical resolution. WARNING: This option is not supported by all printer drivers and can return 0.

The assign sets the number of vertical dots per inch on the printer. WARNING: The assign is not supported by all printer drivers.

Example

? oPtrDevice:YPrinterRes


PtrDevice:CreatePrinterDC()

PtrDevice:CreatePrinterDC() Method

Purpose

To create a printer device context for use with Windows printing functions.

Syntax

<oPtrDevice>:CreatePrinterDC() hDC (16-bit: WORD, 32-bit: PTR)

Description

This method creates a printer device context based on information contained in the PtrDevice internal structures. Use this method if you need to create a printer device context when printing is not in progress. If printing or preview is in progress, the <oPtrDevice>:PrinterDeviceContext access will return the current printer device context.

You are responsible for calling the Windows function DeleteDC(hDC) when you are finished with this device context.

Example

// Create a printer device context

hDC := oPtrDevice:CreatePrinterDC()

... // go something with it

DeleteDC(hDC)


PtrDevice:CreatePrinterIC()

PtrDevice:CreatePrinterIC() Method

Purpose

To create a printer information context for use with Windows functions.

Syntax

<oPtrDevice>:CreatePrinterIC() → hIC (16-bit: WORD; 32-bit: PTR)

Description

This method creates a printer information context based on information contained in the PtrDevice internal structures. Use this function only when you need a printer information context.

You are responsible for calling the Windows function DeleteDC(hIC) when you are finished with this information context.

Example

// Create a printer information context

hDC := oPtrDevice:CreatePrinterIC()

... // go something with it

DeleteDC(hDC)


PtrDevice:GetPaperBins()

PtrDevice:GetPaperBins() Method

Purpose

To retrieve a list of paper bins supported by the printer.

Syntax

<oPtrDevice>:GetPaperBins() → aBins (ARRAY)

Description

This method returns a two dimensional array that contains the bins supported by the current printer. The array has the following format:

aBins[x,1] = name of the bin ("Auto")

aBins[x,2] = constant that Windows uses to identify the bin

See oPtrDevice:DefaultPaperSource for a listing of the Windows constants.

If the method fails, an empty array is returned.

Example

// ? the supported paper bins

aBins := oPtrDevice:GetPaperBins()

for nLp := 1 to alen(aBins)

? aBins[nLp,1]

next nLp


PtrDevice:GetPaperSizes()

PtrDevice:GetPaperSizes() Method

Purpose

To retrieve a list of paper sizes supported by the printer.

Syntax

<oPtrDevice>:GetPaperSizes() → aPapers (ARRAY)

Description

This method returns a two dimensional array that contains the paper sizes supported by the current printer. The array has the following format:

aPapers[x,1] = name of the paper ("Legal")

aPapers[x,2] = constant that Windows uses to identify the paper

See oPtrDevice:PaperSize for a listing of the Windows constants.

If the method fails, an empty array is returned.

Example

// ? the supported paper sizes

aPapers := oPtrDevice:GetPaperSizes()

for nLp := 1 to alen(aPapers)

? aPapers[nLp,1]

next nLp


PtrDevice:GetPrinters()

PtrDevice:GetPrinters() Method

Purpose

To retrieve a list of installed printers.

Syntax

<oPtrDevice>:GetPrinters() → aPrinters (ARRAY)

Description

This method retrieves the installed printers. The printers are returned in a two dimensional array structured as follows:

aPrinters[x,1] = Printer Name ("HP LaserJet II")

aPrinters[x,2] = Device Driver ("HPPCL")

aPrinters[x,3] = Port ("LPT1:")

If the method fails, an empty array is returned.

Example

// ? the installed printers

aPrinters := oPtrDevice:GetPrinters()

for nLp := 1 to alen(aPrinters)

? aPrinters[nLp,1]

next nLp


PtrDevice:Init()

PtrDevice:Init() Method

Purpose

To create a printer device object.

Syntax

PtrDevice{oWindowOwner, oReport} → SELF

Init(oWindowOwner, oReport) → SELF

Arguments

oWindowOwner The window which will own the PrintPreview and PrintMsg dialog windows.

oReport The object that has the callback methods used to create the report or printed output (this can be the same as oWindowOwner).

Description

The PtrDevice object is initialized by retrieving the default Windows printer. You should check the IsValid access of the returned object to make sure the PtrDevice object was able to initialize correctly.

Example

// Instantiate a PtrDevice object

oPtrDevice := PtrDevice{oMyWindow, oReport1}


PtrDevice:Print()

PtrDevice:Print() Method

Purpose

Initiate the printing process.

Syntax

<oPtrDevice>:Print(cName, cFile, cCaption, cMessage, [lPreBody], [lPostBody])

Arguments

cName | The name used for the print job. This is the name that will be displayed in the Windows Print Manager.
cFile | The filename used when the "Print To File" option is selected.
cCaption | The caption of the dialog window displayed during printing.
cMessage | The message of the dialog window displayed during printing.
lPreBody | Logical indicating if a pre-body page is to be printed. (You must provide a PrintPreBody() callback method to actually perform the printing). Default: FALSE
lPostBody | Logical indicating if a post-body page is to be printed. (You must provide a PrintPostBody() callback method to actually perform the printing). Default: FALSE

Description

For a complete description of the printing process, please see the discussion in the PtrDevice introduction.

Example

// Begin printing

oPtrDevice:Print("App Name","PRINT.PRN","Print","Printing...")


PtrDevice:PrintPreview()

PtrDevice:PrintPreview() Method

Purpose

Initiate the printing process and display the results in the print preview dialog window.

Syntax

<oPtrDevice>:PrintPreview(cJobName, cPrint2File, cCaption, cMessage, [lModal], [lPreBody], [lPostBody], [nShowState], [lZoomed], [symPPWindow])

Arguments

cJobName

The name used for the print job. This is the name that will be displayed in the Windows Print Manager. This parameter is only used if the user selects the print option from the preview window.

cPrint2File

The filename used when the Print To File option is selected. This parameter is only used if the user selects the print option from the preview window.

cCaption

The caption displayed on the Print Preview window.

cMessage

The message string displayed on the dialog window presented to the user during printing. This parameter is only used if the user selects the print option from the preview window.

lModal

Optional parameter which if TRUE creates the Print Preview as a modal dialog window; FALSE produces a modeless one. The default is TRUE.

lPreBody

Logical indicating if a pre-body page is to be printed. (You must provide a PrintPreBody() callback method to actually perform the printing). Default: FALSE

lPostBody

Logical indicating if a post-body page is to be printed. (You must provide a PrintPostBody() callback method to actually perform the printing). Default: FALSE

nShowState

Optional parameter to set the preview window show state. Valid options are:

SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED

nZoomed

Optional parameter which specifies the initial zoom level of the Print Preview window. Valid options are:ZOOM_WHOLE_PAGE, ZOOM_PAGE_WIDTH and ZOOM_100

symPPWindow

Optional parameter to specify a symbol representing a class to instantiate for use as the Print Preview window. The class specified must provide certain callback methods for ReportPro. The code for ReportPro's PrintPreview windows is provided as an example of what methods the window needs to provide.

There are two Print Preview window types provided with ReportPro:

#rpPrintPreviewMDI: this symbol will produce a Print Preview window that is built on an MDI child window. The owner must be an MDI shell type window.

#rpPrintPreviewDLG: this symbol will produce a Print Preview window that is built on a modal or modeless dialog window.

Description

For a complete description of the printing process, please see the discussion in the PtrDevice introduction.

Example

// Begin printing in a modeless preview window

oPtrDevice:PrintPreview("App Name", ;

"PRINT.PRN","Print","Printing...",False)


PtrDevice:PrintExport()

PtrDevice:PrintExport() Method

Purpose

Initiate the printing process and export the results to an export format.

Syntax

<oPtrDevice>:PrintExport(xExport, [cFile], cCaption, [cMessage], [lPreBody], [lPostBody])

Arguments

xExport | Optional parameter to specify a specific export type to use. If this is not specified, the user is prompted for an export format to use. If this parameter is specified, the <cFile> parameter is required as well. Currently supported types are: #RP_RTF_WORD95 (creates rich text format compatible with Microsoft Office 6) #RP_RTF_WORD97 (creates rich text format compatible with Microsoft Office 97) #RP_HTML (creates hypertext markup language output) #RP_ASCII (creates vanilla text output) #RP_PDF (creates a simple PDF format) #RP_EXCEL (creates a simple Excel format)
cFile | File name to which to export. This parameter is optional unless the <xExport> is specified.
cCaption | The caption displayed on the Print Export window.
cMessage | The optional message string displayed on the dialog window presented to the user during printing. The default is taken from the language string tables (please wait).
lPreBody | Logical indicating if a pre-body page is to be printed. (You must provide a PrintPreBody() callback method to actually perform the printing). Default: FALSE
lPostBody | Logical indicating if a post-body page is to be printed. (You must provide a PrintPostBody() callback method to actually perform the printing). Default: FALSE

Description

For a complete description of the printing process, please see the discussion in the PtrDevice introduction.

Example

// Begin printing in an RTF output report

oPtrDevice:PrintExport(#RP_RTF_WORD95, "c:\myfile.rtf", "Exporting", "Export in Progress…")


PtrDevice:QuitPreview()

PtrDevice:QuitPreview() Method

Purpose

To instruct the PtrDevice to terminate the preview operation.

Syntax

<oPtrDevice>:QuitPreview([lPrint]) → lSuccess (LOGIC)

Arguments

lPrint

Optional parameter which if TRUE instructs the PtrDevice to start the printing process after the preview is terminated.

Description

This method is used primarily when the preview window is displayed modeless and you wish to terminate the preview process under program control. If the PtrDevice can terminate the preview process it returns TRUE, otherwise, it returns FALSE. The PtrDevice may not be able to terminate the preview process if it is executing a callback method. In this case, it will set oPtrDevice:Quit to TRUE instructing the callback function to immediately return.

Example

// terminate the print preview process

oPtrDevice:QuitPreview()


PtrDevice:SetPrinterByName()

PtrDevice:SetPrinterByName() Method

Purpose

To select a printer by name.

Syntax

<oPtrDevice>:SetPrinterByName(cPrinter, [cPort]) → lSuccess (LOGIC)

Arguments

cPrinter | Name of printer to select.
cPort | Optional parameter to allow the selection of a printer and a port.

Description

This method attempts to select a printer based on the name you specify. If it is successful, it returns TRUE, otherwise it returns FALSE.

Example

// Print to the HP LJet II

oPtrDevice:SetPrinterByName("HP LaserJet II")


PtrDevice:SetPrinterByPort()

PtrDevice:SetPrinterByPort() Method

Purpose

To select a printer by port.

Syntax

<oPtrDevice>:SetPrinterByPort(cPort, [cPrinter]) → lSuccess (LOGIC)

Arguments

cPort | The port you wish to print to.
cPrinter | Optional printer name to allow the selection of a port and a printer.

Description

This method attempts to select a printer based on the port you specify. If it is successful, it returns TRUE, otherwise it returns FALSE.

Example

// print to LPT1 regardless of the attached printer

oPtrDevice:SetPrinterByPort("LPT1:")


PtrDevice:SetPrinterToDefault()

PtrDevice:SetPrinterToDefault() Method

Purpose

To select the default Windows printer.

Syntax

<oPtrDevice>:SetPrinterToDefault() → lSuccess (LOGIC)

Description

This method selects the default Windows printer and returns TRUE if successful.

Example

// Select the default printer

oPtrDevice:SetPrinterToDefault()


PtrDevice:ShowExportDlg()

PtrDevice:ShowExportDlg() Method

Purpose

To display the print export dialog window.

Syntax

<oPtrDevicet>:ShowExportDlg() → lSuccess (LOGIC)

Description

This method displays the Print Export Dialog Window which allows the user to select the type of export to use.. This method returns TRUE if the user exited the dialog by clicking the OK button; FALSE if the CANCEL button is clicked.

If the result is TRUE, the PtrDevice:ExportObject access contains an rpExport object that can be passed as the first parameter of the PtrDevice:PrintExport() method.

Example

// Show the print export dialog box

oPtrDevice:ShowExportDlg()


PtrDevice:ShowPrintDlg()

PtrDevice:ShowPrintDlg() Method

Purpose

To display the Print Dialog Window.

Syntax

<oPtrDevicet>:ShowPrintDlg() → lSuccess (LOGIC)

Description

This method displays the Print Dialog Window which allows various printing related options to be set such as Print Quality, Print Range, Number of Copies, etc. This method returns TRUE if the user exited the dialog by clicking the OK button; FALSE if the CANCEL button is clicked.

Example

// Show the print dialog box

oPtrDevice:ShowPrintDlg()


PtrDevice:ShowSetupDlg()

PtrDevice:ShowSetupDlg() Method

Purpose

To Display the Printer Setup Dialog Window for the current printer.

Syntax

<oPtrDevice>:ShowSetupDlg() → lSuccess (LOGIC)

Description

This method displays the Printer Setup Dialog Window which allows various options to be set such as the selected Printer, Page Orientation, Paper Size, etc. This method returns TRUE if the user exited the dialog by clicking the OK button; FALSE if the CANCEL button is clicked.

Example

// Show the print setup dialog

oPtrDevice:ShowSetupDlg()


Callback Methods

The printer device object expects to receive an object in its constructor. This object needs to implement several callback methods:

PrintEnd

PrintPageBody

PrintPageFooter

PrintPageHeader

PrintPostBody

PrintPreBody

PrintSetPage

PrintStart


PrintEnd()

PrintEnd() Method callback

Purpose

This callback method is invoked upon completion of the printing process.

Syntax

<oReport>:PrintEnd(oPtrDevice)

Arguments

<oPtrDevice> The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK Printing terminated successfully

PRINT_ERROR An error was encountered

Description

This callback method is called if it exists as a method of the report object. The report is specified in the <oReport> parameter of the PtrDevice:Init. This is the last callback method called during a print job and is where clean-up should be performed.


PrintPageBody()

PrintPageBody() Method callback

Purpose

This callback method is invoked during the printing process to allow the report object to print the body portion of the report.

Syntax

<oReport>:PrintPageBody(oPtrDevice)

Arguments

<oPtrDevice>

The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; continue printing.
PRINT_NOMORE Indicates there are no more pages to process; printing should terminate after the current page.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This callback method is the workhorse of a print job and must exist in the report object. The report object is specified in the <oReport> parameter of the PtrDevice:Init.


PrintPageFooter()

PrintPageFooter() Method callback

Purpose

This callback method is invoked during the printing process to allow the report object to print the page footer portion of the report.

Syntax

<oReport>:PrintPageFooter(oPtrDevice)

Arguments

<oPtrDevice>

The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; continue printing.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This callback method is called if it exists as a method of the report object. The report object is specified in the <oReport> parameter of the PtrDevice:Init. This method is called once per page after the PrintPageBody() method has been called.


PrintPageHeader()

PrintPageHeader() Method callback

Purpose

This callback method is invoked during the printing process to allow the report object to print the page header portion of the report.

Syntax

<oReport>:PrintPageHeader(oPtrDevice)

Arguments

<oPtrDevice>

The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; continue printing.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This callback method is called if it exists as a method of the report object. The report object is specified in the <oReport> parameter of the PtrDevice:Init. This method is called once per page before the PrintPageBody() method has been called.


PrintPostBody()

PrintPostBody() Method callback

Purpose

This callback method is invoked at the end of the printing process to allow the report object to print summary information or report totals.

Syntax

<oReport>:PrintPostBody(oPtrDevice)

Arguments

<oPtrDevice>

The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; continue printing (in which case PrintPostBody() will be called again).
PRINT_ERROR Indicates an error occurred and printing should terminate.
PRINT_NOMORE Indicates there are no more pages to process; printing should terminate after the current page.

Description

This callback method is called if it exists as a method of the report object and the <lPostBody> parameter of either Print() or PrintPreview() was set to TRUE. The report object is specified in the <oReport> parameter of the PtrDevice:Init. This method is called after the main printing loop.


PrintPreBody()

PrintPreBody() Method callback

Purpose

This callback method is invoked at the beginning of the printing process to allow the report object to print a title page.

Syntax

<oReport>:PrintPreBody(oPtrDevice)

Arguments

<oPtrDevice>

The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; continue printing.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This callback method is called if it exists as a method of the report object and if the <lPreBody> parameter of either Print() or PrintPreview() was set to TRUE. The report object is specified in the <oReport> parameter of the PtrDevice:Init. This method is called once before the main printing loop and is useful for printing title pages.


PrintSetPage()

PrintSetPage() Method callback

Purpose

This callback method is invoked during the printing process to instruct the report object to prepare to print a certain page.

Syntax

<oReport>:PrintSetPage(oPtrDevice, nNextPageNo)

Arguments

oPtrDevice The PtrDevice which has initiated the call to this callback function.
nNextPageNo The page number to be printed next.

Return Values

nPageNo The page number that the report object moved to and is prepared to print. This value can be less than nNextPageNo if nNextPageNo does not exist.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This method is called to allow the report object to initialize itself for the printing of a specific page. Initialization can include moving record pointers or updating report total information.

This callback method is called if it exists as a method of the report object. The report object is specified in the <oReport> parameter of the PtrDevice:Init.

To calculate the number of pages being moved you must query the PtrDevice:CurrentPageNumber access. This number can be negative.

Example

// Calc the number of pages moved.

nPages := nNextPageNo - oPtrDevice:CurrentPageNumber


PrintStart()

PrintStart() Method callback

Purpose

This callback method is called prior to printing and is where you perform initialization.

Syntax

<oReport>:PrintStart(oPtrDevice)

Arguments

<oPtrDevice> The PtrDevice which has initiated the call to this callback method.

Return Values

The appropriate return values are:

PRINT_OK All is OK; start printing.
PRINT_ERROR Indicates an error occurred and printing should terminate.

Description

This callback method is called if it exists as a method of the report object. The report object is specified in the <oReport> parameter of the PtrDevice:Init. This is the first callback method called during a print job.


RpPrinter Class

Purpose

This class is an enhanced sub-class of the PtrDevice class. It provides an object wrapper around the most used Windows text output and drawing functions.

Class

CLASS RpPrinter inherit PtrDevice

Properties

AvgCharHeight Access

AvgCharWidth Access

BottomMargin Access/Assign

LeftMargin Access/Assign

NextPRow Access

PCOL Access/Assign

PrintAreaLength Access

PrintAreaWidth Access

PROW Access/Assign

RightMargin Access/Assign

TopMargin Access/Assign

UnitOfMeasure Assign

Methods

_DrawBMP

_DrawRTF

_xLateHLogical2UnitofMeasure

_xLateHUnitofMeasure2Logical

_xLateVLogical2UnitofMeasure

_xLateVUnitofMeasure2Logical

DrawBmp

DrawEllipse

DrawLine

DrawRectangle

DrawRTF

DrawText

GetTextFace

GetTextLength

Init

SetFont

TextOut


RpPrinter:AvgCharHeight

RpPrinter:AvgCharHeight Access
Type Float

Purpose

This access returns the average character height of the current font in the current unit of measure.

Example

// Retrieve the average char height

nAvgCharHeight := oRpPrinter:AvgCharHeight


RpPrinter:AvgCharWidth

RpPrinter:AvgCharWidth Access
Type Float

Purpose

This access returns the average character width of the current font in the current unit of measure.

Example

// Retrieve the average char width

nAvgCharWidth := oRpPrinter:AvgCharWidth


RpPrinter:BottomMargin

RpPrinter:BottomMargin Access/Assign
Type Float

Purpose

Gets/sets the bottom margin in the current unit of measure.

Example

// Set the bottom margin to 10 CM

oRpPrinter:UnitOfMeasure := UNIT_CM

oRpPrinter:BottomMargin := 10.0


RpPrinter:LeftMargin

RpPrinter:LeftMargin Access/Assign
Type Float

Purpose

Gets/sets the left margin in the current unit of measure.

Example

// Set the left margin to 10 CM

oRpPrinter:UnitOfMeasure := UNIT_CM

oRpPrinter:LeftMargin := 10.0


RpPrinter:NextPRow

RpPrinter:NextPRow Access
Type Float

Purpose

Returns the next printer row in the current unit of measure. This value is calculated as the current PRow value plus the AvgCharHeight value.

Example

// Don't go off the end of the page

if oRpPrinter:NextPRow > oRpPrinter:PrintAreaLength

return PRINT_OK

else

// print next row

endif


RpPrinter:PCOL

RpPrinter:PCOL Access/Assign
Type Float

Purpose

Gets/sets the printer column position in the current unit of measure.

Example

// Print some text

oRpPrinter:TextOut(oRpPrinter:PRow, oRpPrinter:PCol,;

"Hello World!")


RpPrinter:PrintAreaLength

RpPrinter:PrintAreaLength Access
Type Float

Purpose

Returns the length of the print area in the current unit of measure. The formula is paper length - top margin - bottom margin.

Example

// Don't go off the end of the page

if oRpPrinter:NextPRow > oRpPrinter:PrintAreaLength

return PRINT_OK

else

// print next row

endif


RpPrinter:PrintAreaWidth

RpPrinter:PrintAreaWidth Access
Type Float

Purpose

Returns the width of the print area in the current unit of measure. The formula is paper width - left margin - right margin.

Example

// Don't go off the end of the page

if oRpPrinter:GetTextLength("Hello World!") > ;

oRpPrinter:PrintAreaWidth

  // try a smaller font

endif


RpPrinter:PROW

RpPrinter:PROW Access/Assign
Type Float

Purpose

Gets/sets the printer row position in the current unit of measure.

Example

// Print some text

oRpPrinter:TextOut(oRpPrinter:PRow, oRpPrinter:PCol, ;

"Hello World!")


RpPrinter:RightMargin

RpPrinter:RightMargin Access/Assign
Type Float

Purpose

Gets/sets the right margin in the current unit of measure.

Example

// Set the right margin to 10 CM

oRpPrinter:UnitOfMeasure := UNIT_CM

oRpPrinter:RightMargin := 10.0


RpPrinter:TopMargin

RpPrinter:TopMargin Access/Assign
Type Float

Purpose

Gets/sets the top margin in the current unit of measure.

Example

// Set the top margin to 10 CM

oRpPrinter:UnitOfMeasure := UNIT_CM

oRpPrinter:TopMargin := 10.0


RpPrinter:UnitOfMeasure

RpPrinter:UnitOfMeasure Assign
Type 16-bit: ShortInt, 32-bit: LongInt

Purpose

This assign allows you to set the unit of measurement used by the RpPrinter. Valid settings are:

UNIT_CHARS | Characters. This sets the unit of measure to character mode. The character size is based on the AvgCharWidth and AvgCharHeight accesses.
UNIT_CM | Centimeters.
UNIT_INCHES | Inches.
UNIT_MM | Millimeters.
UNIT_PIXELS | Logical Pixels.

Example

// Set the unit of measure to centimeters

oRpPrinter:UnitOfMeasure := UNIT_CM


RpPrinter:_DrawBmp()

RpPrinter:_DrawBmp() Method

Purpose

To draw a bitmap on the printer or print preview window using an already initialized DIBMP object.

Syntax

<oRpPrinter>:_DrawBmp([nY], [nX], oDIBMP, [nHeight], [nWidth], [nStartRow], [nStartCol], [lStretch])

Arguments

nY | Optional. The row to start printing the bitmap. The default is the current PROW setting.
nX | Optional. The column to start printing the bitmap. The default is the current PCOL setting.
oDIBMP | The DIBMP object which was previously initialized.
nHeight | Optional. The height of the bitmap. The default is the full height of the bitmap.
nWidth | Optional. The width of the bitmap. The default is the full width of the bitmap.
nStartRow | Optional. The first row of pixels in the bitmap to print. The default is the first row.
nStartCol | Optional. The first column of pixels in the bitmap to print. The default is the first column.
lStretch | Optional. Determines if the bitmap is stretched or clipped if nHeight and nWidth don't equal the full height and width.

Description

This low-level method prints a bitmap on the printer or print preview window. The DIBMP object, which contains the bitmap, must be initialized prior to calling this method. In general, you should use the RpPrinter:DrawBMP method as it automatically handles loading and unloading the bitmap from a file. This method is provided for when you wish to avoid the overhead of repeatedly loading the same bitmap over and over again or for when you want to load the bitmap from a resource or field. For more information on the DIBMP class, please see the discussion later in this manual.

Example

// Draw a bitmap from a DIBMP object

oRpPrinter:_DrawBmp(, , oDIBMP)


RpPrinter:_DrawRTF()

RpPrinter:_DrawRTF() Method

Purpose

To draw a RTF stream on the printer or print preview window using an already initialized RTF object.

Syntax

<oRpPrinter>:_DrawRTF([nY], [nX], oRTF, [nHeight], [nWidth], [nStartChar], [lPrint])

Arguments

nY | Optional. The row to start printing the RTF stream. The default is the current PROW setting.
nX | Optional. The column to start printing the RTF stream. The default is the current PCOL setting.
oRTF | The RTF object which was previously initialized.
nHeight | Optional. The height of the rectangle bounding the RTF text. The default is the remaining space on the current page.
nWidth | Optional. The width of the rectangle bounding the RTF text. The default is the remaining space on the current page.
nStartChar | Optional. The character in the RTF text to start printing at. The default is the first character.
lPrint | Optional. Determines if the RTF text is actually printed. If FALSE, the RTF text is not printed but the height of the text is calculated. The default is TRUE.

Description

This low-level method prints a RTF stream on the printer or print preview window. The RTF object, which contains the parsed RTF stream, must be initialized prior to calling this method. In general, you should use the RpPrinter:DrawRTF method as it automatically handles loading and unloading the RTF stream from a file. This method is provided for when you wish to avoid the overhead of repeatedly loading and parsing the same RTF stream over and over again or for when you what to span RTF printing across multiple pages. For more information, see the discussion of the RTF class.

Example

// Draw an RTF stream from a RTF object

oRpPrinter:_DrawRTF(, , oRTF)


RpPrinter:_xLateHLogical2UnitofMeasure()

RpPrinter:_xLateHLogical2UnitofMeasure() Method

Purpose

To translate a x-axis value from logical pixels into the unit of measure used by the RpPrinter class.

Syntax

<oRpPrinter>:_xLateHLogical2UnitofMeasure(nValue) → Float

Arguments

nValue

Logical pixel value to convert.

Description

This low-level method translates a x-axis value from logical pixels into the unit of measure used by the RpPrinter class. This method is not normally required, but is provided to allow you to easily mix Windows API functions and RpPrinter methods.

Example

// Convert 100 pixels into inches

oRpPrinter:UnitOfMeasure := UNIT_INCHES

? oRpPrinter:_xLateHLogical2UnitofMeasure( 100 )


RpPrinter:_xLateHUnitofMeasure2Logical()

RpPrinter:_xLateHUnitofMeasure2Logical() Method

Purpose

To translate a x-axis value from the unit of measure used by the RpPrinter class into logical pixels.

Syntax

<oRpPrinter>:_xLateHUnitofMeasure2 Logical(nValue) → ShortInt

Arguments

nValue

Unit of measure value to convert.

Description

This low-level method translates a x-axis value from the unit of measure used by the RpPrinter class into logical pixels. This method is not normally required, but is provided to allow you to easily mix Windows API functions and RpPrinter methods.

Example

// Convert 1.5 inches into pixels

oRpPrinter:UnitOfMeasure := UNIT_INCHES

? oRpPrinter:_xLateHUnitofMeasure2Logical( 1.5 )


RpPrinter:_xLateVLogical2UnitofMeasure()

RpPrinter:_xLateVLogical2UnitofMeasure() Method

Purpose

To translate a y-axis value from logical pixels into the unit of measure used by the RpPrinter class.

Syntax

<oRpPrinter>:_xLateVLogical2UnitofMeasure(nValue) → Float

Arguments

nValue

Logical pixel value to convert.

Description

This low-level method translates a y-axis value from logical pixels into the unit of measure used by the RpPrinter class. This method is not normally required, but is provided to allow you to easily mix Windows API functions and RpPrinter methods.

Example

// Convert 100 pixels into inches

oRpPrinter:UnitOfMeasure := UNIT_INCHES

? oRpPrinter:_xLateVLogical2UnitofMeasure( 100 )


RpPrinter:_xLateVUnitofMeasure2Logical()

RpPrinter:_xLateVUnitofMeasure2Logical() Method

Purpose

To translate a y-axis value from the unit of measure used by the RpPrinter class into logical pixels.

Syntax

<oRpPrinter>:_xLateVUnitofMeasure2 Logical(nValue) → ShortInt

Arguments

nValue

Unit of measure value to convert.

Description

This low-level method translates a y-axis value from the unit of measure used by the RpPrinter class into logical pixels. This method is not normally required, but is provided to allow you to easily mix Windows API functions and RpPrinter methods.

Example

// Convert 1.5 inches into pixels

oRpPrinter:UnitOfMeasure := UNIT_INCHES

? oRpPrinter:_xLateVUnitofMeasure2Logical( 1.5 )


RpPrinter:DrawBmp()

RpPrinter:DrawBmp() Method

Purpose

Draw a bitmap on the printer or print preview window.

Syntax

<oRpPrinter>:DrawBmp([nY], [nX], cFilename, [nHeight], [nWidth], [nStartRow], [nStartCol], [lStretch])

Arguments

nY | Optional. The row to start printing the bitmap. The default is the current PROW setting.
nX | Optional. The column to start printing bitmap. The default is the current PCOL setting.
cFilename | The file name (including path) of the bitmap.
nHeight | Optional. The height of the bitmap. The default is the full height of the bitmap.
nWidth | Optional. The width of the bitmap. The default is the full width of the bitmap.
nStartRow | Optional. The first row of pixels in the bitmap to print. The default is the first row.
nStartCol | Optional. The first column of pixels in the bitmap to print. The default is the first column.
lStretch | Optional. Determines if the bitmap is stretched or clipped if nHeight and nWidth don't equal the full height and width.

Description

This method prints a bitmap on the printer or print preview window. The memory management associated with loading the file, displaying the bitmap, and cleanup are all handled by this method. The bitmap may be larger than 64K and have 256 colors.

Example

// Draw a bitmap

oRpPrinter:DrawBmp(, , "C:\WINDOWS\REDBRICK.BMP")


RpPrinter:DrawEllipse()

RpPrinter:DrawEllipse() Method

Purpose

To draw an ellipse on the printer or print preview window.

Syntax

<oRpPrinter>:DrawEllipse([nFromY], [nFromX], [nToY], [nToX], [nLineThickness], [nLineStyle], [oLineColor], [nBkGndStyle],

[oBkGndColor] )

Arguments

nFromY | Optional. The top edge of the ellipse. The default is the current PROW setting.
nFromX | Optional. The left edge of the ellipse. The default is the current PCOL setting.
nToY | Optional. The bottom edge of the ellipse. The default is the current PROW setting.
nToX | Optional. The right edge of the ellipse. The default is the current PCOL setting.
nLineThickness | Optional. The thickness of the line used to draw the ellipse (in pixels). The default is 1.
nLineStyle | Optional. The style of the line used to draw the ellipse. Valid settings are the same as the Windows pen styles: PS_SOLID, PS_DASH, PS_DASHDOT, PS_DASHDOTDOT, PS_DOT. The default is PS_SOLID.
oLineColor | Optional. Color object for setting the line color. The default is Color{COLORBLACK}.
oBkGndStyle | Optional. A manifest which represents the background style. Valid styles are listed below
oBkGndColor | Optional. Color object for setting the background color. The default is Color{COLORWHITE}

Valid Line Styles

HS_SOLID | Solid color
HS_HOLLOW | Hollow brush (transparent) - default
HS_BDIAGONAL | -degree upward hatch (left to right)
HS_CROSS | Horizontal and vertical cross-hatch
HS_DIAGCROSS | -degree cross-hatch
HS_FDIAGONAL | -degree downward hatch (left to right)
HS_HORIZONTAL | Horizontal hatch
HS_VERTICAL | Vertical hatch

Example

// Draw an ellipse of 2,2 at the current position

nPRow := oRpPrinter:PRow

nPCol := oRpPrinter:PCol

oRpPrinter:DrawEllipse(, , nPRow+2, nPCol+2)


RpPrinter:DrawLine()

RpPrinter:DrawLine() Method

Purpose

To draw a line on the printer or print preview window.

Syntax

<oRpPrinter>:DrawLine([nFromY], [nFromX], [nToY], [nToX],

[nLineThickness], [nLineStyle], [oColor])

Arguments

nFromY | Optional. The starting row of the line. The default is the current PROW setting.
nFromX | Optional. The starting column of the line. The default is the current PCOL setting.
nToY | Optional. The ending row of the line. The default is the current PROW setting.
nToX | Optional. The ending column of the line. The default is the current PCOL setting.
nLineThickness | Optional. The thickness of the line (in pixels). The default is 1.
nLineStyle | Optional. The style of the line. Valid settings are the same as the Windows pen styles: PS_SOLID, PS_DASH, PS_DASHDOT, PS_DASHDOTDOT, PS_DOT. The default is PS_SOLID.
oColor | Optional. Color object for setting the line color. The default is Color{COLORBLACK}.

Example

// Draw a line 5 units lone

nPCol := oRpPrinter:PCol

oRpPrinter:DrawLine(, , , nPCol+5)


RpPrinter:DrawRectangle()

RpPrinter:DrawRectangle() Method

Purpose

To draw a rectangle on the printer or print preview window.

Syntax

<oRpPrinter>:DrawRectangle([nFromY], [nFromX], [nToY], [nToX],

[nLineThickness], [nLineStyle], [oLineColor] , [nBkGndStyle],

[oBkGndColor])

Arguments

nFromY | Optional. The top row of the rectangle. The default is the current PROW setting.
nFromX | Optional. The left column of the rectangle. The default is the current PCOL setting.
nToY | Optional. The bottom row of the rectangle. The default is the current PROW setting.
nToX | Optional. The right column of the rectangle. The default is the current PCOL setting.
nLineThickness | Optional. The thickness of the line used to draw the rectangle (in pixels). The default is 1.
nLineStyle | Optional. The style of the line used to draw the rectangle. Valid settings are the same as the Windows pen styles: PS_SOLID, PS_DASH, PS_DASHDOT, PS_DASHDOTDOT, PS_DOT. The default is PS_SOLID.
oLineColor | Optional. Color object for setting the line color. The default is Color{COLORBLACK}.
oBkGndStyle | Optional. A manifest which represents the background style. Valid styles are listed below.
oBkGndColor | Optional. Color object for setting the background color. The default is Color{COLORWHITE}

Valid BkGndStyle Values

HS_SOLID | Solid color
HS_HOLLOW | Hollow brush (transparent) - default
HS_BDIAGONAL | -degree upward hatch (left to right)
HS_CROSS | Horizontal and vertical cross-hatch
HS_DIAGCROSS | -degree cross-hatch
HS_FDIAGONAL | -degree downward hatch (left to right)
HS_HORIZONTAL | Horizontal hatch
HS_VERTICAL | Vertical hatch

Example

// Draw a rectangle of 10,10 at the current position

nPRow := oRpPrinter:PRow

nPCol := oRpPrinter:PCol

oRpPrinter:DrawRectangle(, , nPRow+10, nPCol+10)


RpPrinter:DrawRTF()

RpPrinter:DrawRTF() Method

Purpose

To draw a file based RTF stream on the printer or print preview window.

Syntax

<oRpPrinter>:DrawRTF([nY], [nX], cFileName, [nHeight], [nWidth], [nStartChar])

Arguments

nY | Optional. The row to start printing the RTF stream. The default is the current PROW setting.
nX | Optional. The column to start printing the RTF stream. The default is the current PCOL setting.
cFileName | The full name (including path) of the file containing the RTF stream.
nHeight | Optional. The height of the rectangle bounding the RTF text. The default is the remaining space on the current page.
nWidth | Optional. The width of the rectangle bounding the RTF text. The default is the remaining space on the current page.
nStartChar | Optional. The character in the RTF text to start printing at. The default is the first character.

Description

This method prints an RTF stream on the printer or print preview window. It automatically handles loading and parsing the RTF stream from a file. Currently, ReportPro only supports a subset of the RTF standard. For more information on RTF support, see the RTF class discussion.

Example

// Draw an RTF stream from a file

oRpPrinter:DrawRTF(, , "C:\MYAPP\TEXT.RTF")


RpPrinter:DrawText()

RpPrinter:DrawText() Method

Purpose

To draw text on the printer or print preview window. DrawText supports multi-line text and automatically clips text that does not fit within it's drawing rectangle.

Syntax

<oRpPrinter>:DrawText([nY], [nX], cText, [nHeight], [nWidth],

[nAlignment], [oTextColor], [oBkGndColor], [lNoClip])

Arguments

nY | Optional. The top row of the text cell. The default is the current PROW setting.
nX | Optional. The left column of the text cell. The default is the current PCOL setting.
cText | The text to draw.
nHeight | Optional. The height of the text cell. The default is the AvgCharHeight setting.
nWidth | Optional. The width of the text cell. The default is the AvgCharWidth setting times the length of cText.
nAlignment | Optional. The alignment of the text within the text cell. Valid settings are ALIGN_RIGHT, ALIGN_CENTER, ALIGN_LEFT, or ALIGN_FULL The default is ALIGN_LEFT.
oTextColor | Optional. Color object for setting the text color. The default is Color{COLORBLACK}.
oBkGndColor | Optional. Color object for setting the background color. The default is Color{COLORWHITE}.
lNoClip | Optional. If TRUE prevents DrawText from clipping the text that doesn't fit in the drawing rectangle. The default is FALSE

Description

This method draws text on the printer or print preview window. Unless lNoClip is TRUE, a clipping rectangle is created using the parameters passed to this method. DrawText() clips the text so it will not be drawn outside the clipping region. In most cases you should use RpPrinter:TextOut() instead of DrawText. TextOut is slightly faster.

Example

// Draw some text

oRpPrinter:DrawText(, , "Hello World!")


RpPrinter:GetTextFace()

RpPrinter:GetTextFace() Method

Purpose

To get the name of the current font.

Syntax

<oRpPrinter>:GetTextFace() → String

Example

// Save the current text face

cTextFace := oRpPrinter:GetTextFace()


RpPrinter:GetTextLength()

RpPrinter:GetTextLength() Method

Purpose

To get the length of a string based on the current font.

Syntax

<oRpPrinter>:GetTextLength(cText) → Float

Arguments

cText

The text to measure.

Description

This method returns the length of <cText> based on the current font. The value is returned in the current unit of measure. The length returned is not the string length; it is the amount of area the text consumes when it is printed.

Example

// Don't go off the end of the page

if oRpPrinter:GetTextLength("Hello, World!") >; oRpPrinter:PrintAreaWidth

// try a smaller font

endif


RpPrinter:Init()

RpPrinter:Init() Method

Purpose

To create a RpPrinter object.

Syntax

RpPrinter{oWindowOwner, oReport} → SELF

Init(oWindowOwner, oReport) → SELF

Arguments

oWindowOwner The window which will own the PrintPreview and PrintMsg dialog windows.
oReport The object that has the callback methods used to create the report or printed output.

Description

The RpPrinter object is initialized by retrieving the default printer from the WIN.INI file. You should check the IsValid access of the returned object to make sure the RpPrinter object was able to initialize correctly.

Example

// Instantiate an RpPrinter Object

oRpPrinter := RpPrinter{oWindow, oReport}


RpPrinter:SetFont()

RpPrinter:SetFont() Method

Purpose

To create a font and set it as the current font for the RpPrinter object.

Syntax

<oRpPrinter>:SetFont(cFaceName, nPointSize, [lBold], [lItalic],

[lUnderline], [nRotation], [nEscapement])

Arguments

cFaceName | The name of the font. For example, "Arial"
nPointSize | The height of the font in points (1/72 of an inch).
lBold | Optional. TRUE = bold. The default is FALSE.
lItalic | Optional. TRUE = italic. The default is FALSE.
lUnderline | Optional. TRUE = underlined. The default is FALSE.
nRotation | Optional. Specifies the angle, in tenths of degrees, between the base line of a character and the x-axis. The angle is measured in a counterclockwise direction from the x-axis. The default is 0.
nEscapement | Optional. Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the screen surface. The escapement vector is the line through the origins of the first and last characters on a line. The angle is measured counterclockwise from the x-axis. The default is 0.

Description

This method sets the font that RpPrinter uses for DrawText and TextOut. The font is automatically created and destroyed by the RpPrinter object.

Example

// Set the font to a 12 point bold Arial

oRpPrinter:SetFont("Arial", 12, True)


RpPrinter:TextOut()

RpPrinter:TextOut() Method

Purpose

To print text on the printer or print preview window.

Syntax

<oRpPrinter>:TextOut([nY], [nX], cText, [nAlignment], [oTextColor],

[oBkGndColor])

Arguments

nY | Optional. The row on which to print the text. The default is the current PROW setting.
nX | Optional. The column on which to print the text. The default is the current PCOL setting.
cText | The text to print.
nAlignment | Optional. The text alignment. Valid settings are: ALIGN_RIGHT, ALIGN_CENTER, ALIGN_LEFT. The default is ALIGN_LEFT.
oTextColor | Optional. Color object for setting the text color. The default is Color{COLORBLACK}.
oBkGndColor | Optional. Color object for setting the background color. The default is Color{COLORWHITE}.

Description

This method provides a wrapper around the Windows API TextOut() function. It provides a quick, simple way to print text.

Example

// Print some text

oRpPrinter:TextOut(, , "Hello World!")


DiBMP Class

Purpose

To provide access to Windows device independent bitmap (DIB) functionality. Windows provides several API functions to display and manipulate bitmaps. The DIBMP class not only provides a wrapper around some of these functions, it also simplifies the tasks associated with bitmap loading and memory management. The DIBMP class can handle bitmaps larger than 64K and containing up to 256 colors.

Class

CLASS DIBMP

Properties

Colors Access

Height Access

IsResource Access

IsValid Access

Width Access

Methods

Destroy

DrawDIB

Init

LoadDIBFromCodeBlock

LoadDIBFromDynaString

LoadDIBFromField

LoadDIBFromFile

LoadDIBFromResource


DIBMP:Colors

DIBMP:Colors Access
Type ShortInt

Purpose

This access returns the number of colors stored in the currently loaded bitmap. If a bitmap is not loaded, it returns 0.

Example

// Retrieve the number of colors

nColors := oDIBMP:Colors


DIBMP:Height

DIBMP:Height Access
Type LongInt

Purpose

This access returns the height (in pixels) of the currently loaded bitmap. If a bitmap is not loaded, it returns zero.

Example

// Retrieve the bitmap height

nHeight := oDIBMP:Height


DIBMP:IsResource

DIBMP:IsResource Access
Type Logic

Purpose

This access returns TRUE if the bitmap was loaded from a resource; otherwise, it returns FALSE.

Example

if oDIBMP:IsResource

? "BMP was loaded from a DLL or EXE resource"

endif


DIBMP:IsValid

DIBMP:IsValid Access
Type Logic

Purpose

This access returns TRUE when a bitmap has been successfully loaded into memory; otherwise, it returns FALSE.

Example

// Load the bitmap and make sure it is valid

oDIBMP:LoadDIBFromFile("C:\WINDOWS\CASTLE.BMP")

if oDIBMP:IsValid

oDIBMP:DrawDIB(...)

endif


DIBMP:Width

DIBMP:Width Access
Type LongInt

Purpose

This access returns the width (in pixels) of the currently loaded bitmap. If a bitmap is not loaded, it returns zero.

Example

// Retrieve the bitmap width

nWidth := oDIBMP:Width


DIBMP:Destroy()

DIBMP:Destroy() Method

Purpose

To free the memory allocated to hold the bitmap.

Syntax

<oDIBMP>:Destroy()

Description

This method frees the memory allocated to hold the bitmap. After the memory is freed, the DIBMP object is invalid. It cannot be used again until a bitmap is loaded via a DIBMP:LoadDIBFrom... method.

Example

// Free some memory

oDIBBMP:Destroy()


DIBMP:DrawDIB()

DIBMP:DrawDIB() Method

Purpose

To draw a previously loaded bitmap on a Windows device context.

Syntax

<oDIBMP>:DrawDIB(hDC, [nY], [nX], [nHeight], [nWidth], [nStartRow], [nStartCol], [lStretch], [lRetainAspect])

Arguments

hDC | Windows device context to draw the bitmap on.
nY | Optional. The top row (in logical pixels) of the bitmap. The default is 0.
nX | Optional. The left column (in logical pixels) of the bitmap. The default is 0.
nHeight | Optional. The height of the bitmap. The default is the height stored in the bitmap (the actual height of the bitmap).
nWidth | Optional. The width of the bitmap. The default is the width stored in the bitmap (the actual width of the bitmap).
nStartRow | Optional. The row in the bitmap where drawing will start. The default is the first row.
nStartCol | Optional. The column in the bitmap where drawing will start. The default is the first column.
lStretch | Optional. If TRUE, the bitmap is stretched (or shrunk) to fit into nHeight and nWidth. If FALSE, the bitmap is clipped to nHeight and nWidth.
lRetainAspect | Optional. If TRUE, when the bitmap is stretched (or shrunk) to fit into the nHeight and nWidth, the original aspect ratio of the bitmap will be preserved. The default is FALSE.

Example

// Draw a DIB on a window.

// NOTE: This approach will not work

// on a shell window

oDIBMP:LoadDIBFromFile("C:\WINDOWS\CASTLE.BMP")

if oDIBMP:IsValid

hDC:=GetDC(self:Handle(0))

SaveDC(hDC)

SetMapMode(hDC, MM_TEXT)

SetWindowOrg(hDC, 0, 0)

SetViewPortOrg(hDC, 0, 0)

oDIBMP:DrawDIB(hDC)

RestoreDC(hDC, -1)

ReleaseDC(self:Handle(0), hDC)

endif

oDIBMP:Destroy()


DIBMP:Init()

DIBMP:Init() Method

Purpose

To create a DIBMP object.

Syntax

DIBMP{} → SELF

Init() → SELF

Description

This method creates a DIBMP object but it does not load a bitmap into memory. You must load a bitmap via one of the DIBMP:LoadDIBFrom... methods before you can do anything useful with the DIBMP object.


DIBMP:LoadDIBFromCodeBlock()

DIBMP:LoadDIBFromCodeBlock() Method

Purpose

To load a bitmap from the return value of a codeblock.

Syntax

<oDIBMP>:LoadDIBFromCodeBlock(bCodeBlock) → lSuccess (LOGIC)

Arguments

bCodeBlock

Codeblock who's return value is a bitmap.

Description

This method loads a bitmap from the return value of a codeblock. The codeblock return value must be a string that contains a valid bitmap. The bitmap returned from the codeblock must also contain a BITMAPFILEHEADER structure or it is ignored.

The BITMAPFILEHEADER structure is a standard Windows structure. Please refer to the Windows SDK reference for more information.

Due to the 64K size limit of strings in a 16 bit application, the size of a bitmap loaded via this method must be less than 64K when using the RP2/16 runtime.

Example

// Load a bitmap from a codeblock

// that references a DBF field

bCodeBlock:={|| mytable->bmpfield}

oDIBMP:LoadDIBFromCodeBlock(bCodeBlock)


DIBMP:LoadDIBFromDynaString()

DIBMP:LoadDIBFromDynaString() Method

Purpose

To load a bitmap from a string.

Syntax

<oDIBMP>:LoadDIBFromDynaString(cString) → lSuccess (LOGIC)

Arguments

cString

String which contains a bitmap.

Description

This method loads a bitmap from a string. The string must contain a BITMAPFILEHEADER structure or it is ignored.

The BITMAPFILEHEADER structure is a standard Windows structure. Please refer to the Windows SDK reference for more information.

Due to the 64K size limit of strings in a 16 bit application, the size of a bitmap loaded via this method must be less than 64K when using the RP2/16 runtime.

Example

// Load a bitmap from a string

cSting:=fieldget(3)

oDIBMP:LoadDIBFromDynaString(cString)


DIBMP:LoadDIBFromField()

DIBMP:LoadDIBFromField() Method

Purpose

To load a bitmap from a DBF field.

Syntax

<oDIBMP>:LoadDIBFromField(xField, [xAlias]) → lSuccess (LOGIC)

Arguments

xField | The field containing the bitmap (character name or numeric position).
xAlias | Optional. The alias where the field is located (character, numeric or DBServer). The default is the current area.

Description

This method loads a bitmap from a DBF field. The field must contain a BITMAPFILEHEADER structure or it is ignored.

The BITMAPFILEHEADER structure is a standard Windows structure. Please refer to the Windows SDK reference for more information.

Due to the 64K size limit of strings in a 16 bit application, the size of a bitmap loaded via this method must be less than 64K when using the RP2/16 runtime.

Example

// Load a bitmap from a field

oDIBMP:LoadDIBFromField("BMPField")


DIBMP:LoadDIBFromFile()

DIBMP:LoadDIBFromFile() Method

Purpose

To load a bitmap from an external file.

Syntax

<oDIBMP>:LoadDIBFromFile(cFileName) → lSuccess (LOGIC)

Arguments

cFileName

The file name (including path) of the bitmap file.

Description

This method loads a bitmap from an external file. The file must be a valid Windows bitmap file that contains a BITMAPFILEHEADER structure or it is ignored.

The BITMAPFILEHEADER structure is a standard Windows structure. Please refer to the Windows SDK reference for more information.

There is no 64K size limitation when loading a bitmap from an external file.

Example

// Load a bitmap from a file

oDIBMP:LoadDIBFromFile("C:\WINDOWS\CASTLE.BMP")


DIBMP:LoadDIBFromResource()

DIBMP:LoadDIBFromResource() Method

Purpose

To load a bitmap from a resource.

Syntax

<oDIBMP>:LoadDIBFromResource(cName, hInst) → lSuccess (LOGIC)

Arguments

cName | The string name of the resource.
hInst | The instance of the application or DLL containing the resource.

Description

This method loads a bitmap from a compiled resource. It allows you to load bitmaps stored in Windows executables and dynamic link libraries.

Example

// Load a bitmap named "MYDIB" from the application's exe file.

oDIBMP:LoadDIBFromResource("MYDIB", _getinst())


RTF Class

Purpose

To provide support for printing text stored in Rich Text Format (RTF). This class provides methods for loading RTF from various sources, automatically parses the RTF into a usable format and provides the capability to print the RTF text on ReportPro's PtrDevice and RpPrinter classes.

Currently, the RTF class only supports a subset of the RTF standard. Supported features include: mixed fonts, text colors and paragraph formatting.

Class

CLASS RTF

Properties

Error Access

IsValid Access

LastPrintedChar Access

LastPrintedRow Access

TextBufferLength Access

Methods

Destroy

DrawText

Init

LoadRTFFromDynaString

LoadRTFFromField

LoadRTFFromFile


RTF:Error

RTF:Error Access
Type ShortInt

Purpose

This access returns an error code which identifies the error encountered while parsing the RTF stream. The error codes are:

RTF_ERRORASSERTION | Assertion failure
RTF_ERRORBADTABLE | RTF table (sym or prop) invalid
RTF_ERROREOF | End of file reached while reading RTF
RTF_ERRORINVALIDHEX | Invalid hex character found in data
RTF_ERRORSTACKOVERFLOW | Too many '{' or memory exhausted
RTF_ERRORSTACKUNDERFLOW | Unmatched '}'
RTF_ERRORUNMATCHBRACE | RTF ended during an open group.
RTF_INVALID | Failed to initialize correctly
RTF_OK | Everything's fine

Example

// If not valid, find out why

if !oRTF:IsValid

? oRTF:Error

endif


RTF:IsValid

RTF:IsValid Access
Type Logic

Purpose

This access returns TRUE if the RTF object has successfully loaded and parsed a RTF stream.

Example

// Is the RTF object valid?

if !oRTF:IsValid

? "Load failed"

endif


RTF:LastPrintedChar

RTF:LastPrintedChar Access
Type LongInt

Purpose

If called after RTF:DrawText(), it returns the last printed character. This value is useful for spanning a large RTF stream across multiple pages.

Example

// Show the last character we printed in the rectangle

oRTF:DrawText(oRpPrinter, 0, 0, 100, 100, TRUE)

? oRTF:LastPrintedChar


RTF:LastPrintedRow

RTF:LastPrintedRow Access
Type ShortInt

Purpose

If called after RTF:DrawText(), it returns the last row printed. This value is useful for printing additional information below the RTF text. This value is in logical pixels. To use this value with the RpPrinter class you must translate it to RpPrinter units.

Example

// Draw a line right below the text

oRTF:DrawText(oPtr, 0, 0, 100, 100, TRUE)

nRow:=oPtr:_xLateVLogical2UnitofMeasure(oRTF:LastPrintedRow)+1

oPtr:DrawLine(nRow, 0, nRow, 100)


RTF:TextBufferLength

RTF:TextBufferLength Access
Type LongInt

Purpose

To determine how may characters are contained in the parsed RTF buffer.

Example

oRTF:DrawText(oRpPrinter, 0, 0, 100, 100, TRUE)

if oRTF:LastPrintedChar = oRTF:TextBufferLength

// We are done...

endif


RTF:Destroy()

RTF:Destroy() Method

Purpose

To free the memory allocated to hold the parsed RTF text.

Syntax

<oRTF>:Destroy()

Description

This method frees the memory allocated to hold the parsed RTF text. After the memory is freed, the RTF object is invalid. It cannot be used again until another RTF stream is loaded via a RTF:LoadRTFFrom... method.

Example

// Free some memory

oRTF:Destroy()


RTF:DrawText()

RTF:DrawText() Method

Purpose

To draw a previously loaded RTF stream on a PtrDevice or RpPrinter. Note: The PtrDevice or RpPrinter must be in the preview or print mode before this method is called.

Syntax

<oRTF>:DrawText(oPtrDevice, [nY], [nX], [nHeight], [nWidth], [nStartChar], [lPrint])

Arguments

oPtrDevice | PtrDevice or RpPrinter to draw the RTF text onto.
nY | Optional. The top row (in logical pixels) of the text. The default is 0.
nX | Optional. The left column (in logical pixels) of the text. The default is 0.
nHeight | Optional. The height (in logical pixels) of the rectangle bounding the text. The default is oPtrDevice:LogPrintAreaLength-nY.
nWidth | Optional. The width (in logical pixels) of the rectangle bounding the text. The default is oPtrDevice:LogPrintAreaWidth-nX.
nStartChar | Optional. The character to start printing at. The default is the first character.
lPrint | Optional. TRUE to actually print the text. FALSE to calculate the area used by the text. If FALSE, the RTF class will calculate the vertical area consumed by the text given a fixed nWidth. It also will calculate the last character printed. Retrieve these values via LastPrintedRow and LastPrintedChar accesses.

Example

// Draw RTF on a RpPrinter.

if oRTF:LoadRTFFromFile("C:\RP2\RPWP.RTF")

oRTF:DrawText(oRpPrinter)

endif

oRTF:Destroy()


RTF:Init()

RTF:Init() Method

Purpose

To create a RTF object.

Syntax

RTF{} → SELF

Init() → SELF

Description

This method creates a RTF object but it does not load the RTF stream into memory. You must load the RTF stream via one of the RTF:LoadRTFFrom... methods before you can do anything useful with the RTF object.


RTF:LoadRTFFromDynaString()

RTF:LoadRTFFromDynaString() Method

Purpose

To load and parse a RTF stream from a string.

Syntax

<oRTF>:LoadRTFFromDynaString(cString) → lSuccess (LOGIC)

Arguments

cString

String which contains the RTF stream.

Description

This method loads and parses a RTF stream from a string. The string must contain a valid RTF stream or it is ignored. This method returns TRUE if successful, or FALSE if an error is encountered. If this method executes successfully, you can display the RTF on a RpPrinter or PtrDevice via the RTF:DrawText() method.

Due to the 64K size limit of strings in a 16 bit application, the size of the RTF stream must be less than 64K when using the RP2/16 runtime.

Example

// Load a RTF stream

cString:=fieldget(3)

oRTF:LoadRTFFromDynaString(cString)


RTF:LoadRTFFromField()

RTF:LoadRTFFromField() Method

Purpose

To load and parse a RTF stream from a DBF field.

Syntax

<oRTF>:LoadRTFFromField(xField, [xAlias]) → lSuccess (LOGIC)

Arguments

xField | The field containing the RTF stream (character name or numeric position).
xAlias | Optional. The alias where the field is located (character, numeric or DBServer). The default is the current area.

Description

This method loads and parses a RTF stream from a DBF field. The field must contain a valid RTF stream or it is ignored. This method returns TRUE if successful, or FALSE if an error is encountered. If this method executes successfully, you can display the RTF on a RpPrinter or PtrDevice via the RTF:DrawText() method.

Due to the 64K size limit of strings in a 16 bit application, the size of the RTF stream must be less than 64K when using the RP2/16 runtime.

Example

// Load a RTF stream from a field

oRTF:LoadRTFFromField("RTFField")


RTF:LoadRTFFromFile()

RTF:LoadRTFFromFile() Method

Purpose

To load and parse a RTF stream from an external file.

Syntax

<oRTF>:LoadRTFFromFile(cFileName) → lSuccess (LOGIC)

Arguments

cFileName

The file name (including path) of the RTF file.

Description

This method loads and parses a RTF stream from an external file. The file must contain a valid RTF stream or it is ignored. This method returns TRUE if successful, or FALSE if an error is encountered. If this method executes successfully, you can display the RTF on a RpPrinter or PtrDevice via the RTF:DrawText() method.

There is no 64K size limitation when loading a RTF stream from an external file.

Example

// Load a RTF stream from a file

oRTF:LoadRTFFromFile("C:\RP2\RPWP.RTF")


Examples

ReportPro comes with several example files that demonstrate the proper use of the ReportPro runtime libraries.

CA-Visual Objects Examples

The following examples require that the proper runtime library is installed in the CA-VO repository before they can be imported and compiled.

RDD Only Runtime

Version | Example Application File
16-bit | RP2R_16.AEF
32-bit | RP2R_32.AEF

RDD & SQL Runtime

Version | Example Application File
16-bit | RP2S_16.AEF
32-bit | RP2S_32.AEF

Linkable Designer

Version | Example Application File
16-bit | RP2D_16.AEF
32-bit | RP2D_32.AEF


External Function Libraries

External Function Libraries (EFLs) can be used to expand the functionality available to ReportPro's Expression Builder. EFLs work with the ReportPro runtime libraries as well as the stand-alone designer. Function prototypes can also be displayed in the Functions list box of the Expression Builder.

The function libraries must reside in a DLL created with CA-Visual Objects 2 and follow certain guidelines explained below. This feature is only available for the 32-bit version of ReportPro.

Creating Function Library DLLs

To create an EFL, use CA-VO 2 to create a DLL that contains the functions you wish to call from ReportPro. The functions must be macro-compilable; they must be un-typed and follow the Clipper calling convention. Other functions in the EFL that are not called directly by ReportPro can be typed if desired.

Example

function ThisFunctionWillWork

return "Hello, World!"

function ThisWillWorkAlso

return ctod("5/4/96")

function ThisFunctionWillNotWork as string

return "Because it is strong typed"

function ThisWillNotWorkEither (cString as string)

return "Since cString is strong typed"

Registering your Functions with the Expression Builder

When ReportPro loads an EFL, it calls the function rpFunctionList() if it exists in the EFL DLL. ReportPro expects that this function will return a one-dimensional array containing the function prototypes to include in the Expression Builder function list. All of the functions available in the EFL need not be listed in the array, only those you wish to be displayed in the Expression Builder.

Example

function rpFunctionList as array

local aArray as array

aArray :={}

aadd(aArray, "MyFunction(n)")

aadd(aArray, "MyOtherFunction(c)")

return aArray

Installing an EFL in ReportPro

EFLs must be identified in the RPWIN.INI file. The Function Library section of the INI file must contain the file name of each EFL you wish to integrate into ReportPro. This of course, means that you must distribute the RPWIN.INI file with your application if you use an EFL.

Example

[FunctionLibs]

LIB1=MyLib.DLL

LIB2=MyOther.DLL

External Function Library Registration Program

The ReportPro External Function Library Registration Program was created to aid the developer in creating EFLs that work with ReportPro. You can register your EFL with DataPro to ensure that the names of EFLs are unique and will not conflict with other EFLs from other developers.

DataPro strongly recommends that all developers participate in the ReportPro External Function Library Registration Program. Contact DataPro for more information and a registration application.


Internationalization

Providing support for different languages is an important issue in today's software development. ReportPro addresses this need by placing all displayable text strings in a separate DLL. The text strings used by the RpReport, PtrDevice and RpPrinter classes are completely customizable.

ReportPro's installation contains the code used to produce the ENGLISH language libraries. By translating the character strings in the string table, you can create your own custom language library.

ReportPro 16-Bit Internationalization

All libraries of the 16-Bit version of RP2 utilize the RP2ENG16.DLL language translation library. RP2ENG16.AEF contains the code used to produce the ENGLISH language DLL.

Use the following steps to create your own language DLL:

• Import RP2ENG16.AEF into your CA-VO 1 repository.
• Change the name of the RP2ENG16 application and DLL so you will not overwrite the existing DLL.
• The character strings are located in three string table entries in the application:
• ENGLISH - contains strings used by the runtime libraries.
• ENGLISHEXE - contains strings used by the stand alone and linkable designers.
• ENGLISHMENU - contains menu strings used by the stand alone and linkable designers.

Translate the character strings as required but do not change the string DEFINES.

• Compile the new language DLL and generate the VO-type DLL file.
• Follow the instructions below in "Setting the Active Language DLL" to tell ReportPro about your new language DLL.

ReportPro 32-Bit Internationalization

All libraries of the 32-Bit version of RP2 utilize the RP2ENG32 language library. RP2ENG32.AEF contains the code used to produce the 32-bit ENGLISH language library.

Use the following steps to create your own language DLL:

• Import RP2ENG32.AEF into your CA-VO 2 repository.
• Change the name of the RP2ENG32 application and DLL so you will not overwrite the existing DLL.
• The character strings are located in three string table entries in the application:
• ENGLISH - contains strings used by the runtime libraries.
• ENGLISHEXE - contains strings used by the stand alone and linkable designers.
• ENGLISHMENU - contains menu strings used by the stand alone and linkable designers.

Translate the character strings as required but do not change the string DEFINES.

• Compile the new language DLL and generate the DLL file.
• Follow the instructions below in "Setting the Active Language DLL" to tell ReportPro about your new translation DLL.

Setting the Active Language DLL

The SetRpLangDLL() function allows you to specify which language DLL ReportPro uses.


SetRpLangDLL()

SetRpLangDLL() Function

Purpose

To specify the language DLL which ReportPro uses.

Syntax

SetRpLangDLL(cDLL) → NIL

Arguments

cDLL The file name of the language DLL.

Description

This function sets the language DLL for the RpReport, RpPrinter and PtrDevice classes. The <cDLL> argument can contain the full path to the DLL.

Example

SetRpLangDLL("C:\RP2\RP2GER32.DLL")


Distributing RP2 with Your Application

Distributing ReportPro with Your CA-VO 2 Application

The files you must distribution with your CA-VO 2 application depend on which runtime library you are using in the application. These files are listed in the following table. All ReportPro runtime DLLs should be installed in the same directory as your application's executable.

Runtime Library | Necessary Files | Description
RDD | Rp2Rdd32.DLL Rp2Eng32.DLL RpExport.DLL | RDD-Only runtime DLL.-bit English Language DLL Export to file DLL
RDD/SQL | Rp2Sql32.DLL Rp2Eng32.DLL RpExport.DLL | RDD/SQL runtime DLL-bit English Language DLL Export to file DLL
Designer | Rp2Dsn32.DLL Rp2Eng32.DLL Rp2s32.DLL Rp2.CHM Labels.SYS RpExport.DLL | Linkable designer DLL 32-bit English Language DLL External 32-bit Support Library Linkable designer help file Label definition table Export to file DLL

Export DLL

If you do not intend to use the export to file feature, you do not need to distribute the RPEXPORT.DLL file with the RDD Runtime Library or the RDD/SQL runtime library. The RPEXPORT.DLL is necessary for the linkable designer since users choose to whether to use the export feature.

Imaging DLLs

If you use pictures in your report, you must also distribute the LLO32 and LLI32 DLLs.

Graphing DLLs

If you use graphs in your report, you must distribute the LLO32, LLI32 and LLB32 DLLs.

Files that May Not Be Distributed

You ARE NOT authorized to distribute the following files:

Rp2_16.EXE

Rp2Engl16.AEF

Rp2_Hook.MEF

Rp2Rdd16.AEF

Rp2Sql16.AEF

RpWp.RTF

Rp2Dsn16.AEF

Preview.ICO

Zoom.CUR

Rp2.HLP

Rp2Dev.HLP

Rp2_32.EXE

Rp2Engl32.AEF

Rp2Rdd32.AEF

Rp2Sql32.AEF

Rp2Dsn32.AEF

Any other RP2 file not explicitly listed as distributable.


Customer Support

The following Customer Support information is provided to help you obtain additional information on DataPro products and services.

Sales and general information

DataPro Direct Sales (912) 923-3793

DataPro Main Fax (912) 329-1838

DataPro Sales Email sales@dproinc.com

WWW www.dproinc.com

(Monday through Friday 9 a.m. to 4 p.m. EST; Fax available 24 hours)

Technical Support

DataPro Technical Support Hotline (912) 988-8316

(Monday through Friday 9 a.m. to 4 p.m. EST)

When you call DataPro Technical Support, please have your serial number handy and call from a phone next to your computer where ReportPro is installed. Assisting you often requires access to ReportPro and/or your application that uses ReportPro.

Email Technical Support

DataPro Email Support help@dproinc.com

When you email DataPro Technical Support, please include your serial number.

Technical Support for Your Customers

If you distribute an application that uses a ReportPro runtime library, please note that DataPro does not provide technical support for your customers. Only registered users of ReportPro are entitled to technical support. If one of your customers is having a ReportPro related problem, you must act as a liaison. Please don't instruct your customer to contact us directly.

Mailing Address

DataPro, Inc.

PO Box 6663

Warner Robins, GA 31095-6663

United States of America