Basic Concept / Printing


Install TFORMer Designer (the graphical layout editor) and TFORMer SDK (the reporting and label printing core) using the setup applications. TFORMer SDK is available as DLL, as COM component, as .NET assembly, as JAVA class and as stand-alone application (TFPrint). Both the COM component and the .NET assembly of TFORMer SDK are registered automatically. The .NET assembly is automatically placed in the GAC and in the Bin directory of the installation folder. The Java package JTFORMer8.jar (which is compatible with the Java Runtime Edition - JRE version 1.5 or higher) is copied into the Bin directory: It includes all classes that you need to create a TFORMer application with the Java language.

Design a FormLayout

Use TFORMer Designer to create a FormLayout graphically. Most likely a FormLayout contains dynamic data which will be provided by your application during print-time (e.g. an article number for a product label or a ticket number for an e-ticket). TFORMer uses DataFields as place-holders for such dynamic data. These DataFields are declared as well as used within the FormLayout.

Check out the following paragraphs to learn how to print or export a FormLayout with data provided by your application!

Create a .NET Project

Create a new .NET based project. In Visual Studio right-click on your project in the Solution Explorer and select Add Reference. Open the .NET tab and select TFORMer 8 SDK. Alternatively open the Browse tab and select the TFORMer .NET assembly called TECIT.TFORMer.dll.

Add the namespace TECIT.TFORMer in each source file that uses TFORMer SDK:

License and Initialize TFORMer SDK

Licensing is not required for evaluation purposes. For production, apply a license key to TFORMer SDK before using any other properties or methods of TFORMer. This needs to be done only once, for example when initializing the application.

// License TFORMer SDK (the license key is only for demonstration purposes)
TFORMer.License("John Doe", LicenseKind.Workstation, 1, "00000000000000000000000000000000");
Provides methods to query status information and to license TFORMer SDK.
Definition: TFormer.cs:81
static void License(string licensee, LicenseKind kind, int numberOfLicenses, string key)
Applies a license to this instance of the TFORMer SDK.
Definition: TFormer.cs:119
The license types for the TFORMer SDK.
Definition: TFormer.cs:24

Select the FormLayout to be Used

Printing is done with the help of a print Job. Create a Job and select the FormLayout by setting the appropriate properties.

// Create a new Job instance
Job printJob = new Job();
// Select the stand-alone FormLayout
printJob.RepositoryName = "C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff";
This is the main class of TFORMer SDK for generating output.
Definition: Job.cs:266
TFORMer Designer supports so-called stand-alone FormLayouts (which are created by default by TFORMer Designer) and Repository based FormLayouts (which enable you to organize a large number of FormLayouts in a structured way). Check out Repository / FormLayout for details.

Whenever properties or methods are requesting input files (e.g. FormLayouts, or file-based DataSources like XML or CSV files), these may be passed as usual via the filename or by using BASE64 encoded strings. In addition, files and BASE64 strings may be zipped to save bandwidth. Refer to Passing Files for details.

Provide JobData

As mentioned above a FormLayout usually contains DataFields which are used as place holders for dynamic data. Before printing a FormLayout you need to provide data for these DataFields by assigning suitable JobData to the Job. Various methods are available for providing JobData.

The field names available in the JobData (e.g. the column names returned by a SQL-SELECT statement or the column names in a CSV file) must match the names of the DataFields used in a FormLayout. When using user-defined data sources (see user-defined data source below) the mapping between fields in the DataSource to DataFields in the FormLayout can be adjusted freely.

Provide JobData via Program Code

This is the most direct method to pass data to TFORMer SDK. In this case the names and values of the DataFields used in a FormLayout are provided directly. The example below sets the values for the DataFields ArticleNo, ArticleName and ArticlePrice.

// Create a new JobData instance.
// Here we are using the JobDataRecordSet which accepts Records containing name/value pairs
// Create a new Record
Record record = new Record();
// Add some name/value pairs for the DataField values to the Record
record.Data.Add("ArticleName", "Speaker System HF1");
record.Data.Add("ArticleNo", "12001234");
record.Data.Add("ArticlePrice", "498.98");
// Add the Record to the JobData
// Create a second Record
record = new Record();
// This Record should be printed two times
record.NumberOfCopies = 2;
record.Data.Add("ArticleName", "Record Box 12 CDs");
record.Data.Add("ArticleNo", "12021231");
record.Data.Add("ArticlePrice", "8.85");
// Assign the JobData to the Job
printJob.JobData = jobData;
Provides access to JobDataRecordSet (a set of in-memory Record objects which serves as JobData for a ...
Definition: JobDataRecordSet.cs:18
List< Record > Records
Gets/Sets the list of Records.
Definition: JobDataRecordSet.cs:31
Provides access to a Record.
Definition: JobDataRecordSet.cs:66
Dictionary< string, string > Data
Gets/Sets the values for the Record.
Definition: JobDataRecordSet.cs:92

Load JobData From CSV Files <br>

See also JobDataCsv

// Create a new JobData instance.
// Here we import a CSV and specify separator and qualifier character
JobDataCsv jobData = new JobDataCsv("path/data.csv", ',', '"');
// Assign the JobData to the Job
printJob.JobData = jobData;
Provides access to JobDataCsv (a CSV-file that serves as JobData for a Job).
Definition: JobDataCsv.cs:20

Load JobData From XML Files

See also JobDataXml

// Create a new JobData instance.
// Here we import a XML file (must comply with the supported XML schemes)
JobDataXml jobData = new JobDataXml("path/data.xml");
// Assign the JobData to the Job
printJob.JobData = jobData;
Provides access to JobDataXml (a XML file that serves as JobData for a Job).
Definition: JobDataXml.cs:20

Load JobData From a Database <br>

See also JobDataOdbc

// Create a new JobData instance
// Here we import data from an ODBC connection using the specified SQL SELECT statement
JobDataOdbc jobData = new JobDataOdbc (
"", // Username
"", // Password
"SELECT * FROM tbl_Example"
// Assign the JobData to the Job
printJob.JobData = jobData;
Provides access to JobDataOdbc (an ODBC connection that serves as JobData for a Job).
Definition: JobDataOdbc.cs:20

Load JobData From a User-Defined Data Source <br>

See also JobDataDataSource

Last but not least TFORMer Designer offers the possibility to specify a "user-defined" DataSource as part of a FormLayout. Such a DataSource defines how data is retrieved (e.g. from an ODBC database) and it specifies the mappings between fields in the DataSource and DataFields in the FormLayout. If you want to use such a user-defined DataSource for JobData retrieval, select the DataSource by name as shown below. Use optional DataSourceParameters to control certain aspects (like the filename, SQL SELECT statement or DSN) of the DataSource during runtime.

// Create a new JobDataDataSource instance
// The DataSource named myTextDataSource must be defined in the FormLayout or Repository
JobDataDataSource jobData = new JobDataDataSource ("myTextDataSource");
// Set the DataSourceParameter named parFile
jobData.ParameterValues.Add ("parFile", "/YourPath/InputData.txt");
// Assign the JobData to the Job
printJob.JobData = jobData;
Provides access to a user-defined DataSource, which is defined in the FormLayout or a Repository.
Definition: JobDataDataSource.cs:18

Generate Output

Print on a Printer

Use PrinterName to specify the target printer. Provide an empty string, if you want to send the output to the default printer.

// Select the printer name on Windows or Linux (CUPS printer name), use null for the default printer
printJob.PrinterName = null;
// Print
void Print()
Prints the Job using the selected FormLayout and the current JobData.
Definition: Job.cs:886

Export as PDF, PostScript, HTML, ZPL-II or as an Image

Instead of printing on a printer, you can export the output as a PDF, PostScript, HTML, ASCII or image file. ZPL-II (the ZEBRA printer language) generation is supported too. Instead of setting a printer name, set the name and type of the output file.

// Select PDF output to /temp/out.pdf
printJob.OutputName = "/temp/out.pdf";
printJob.PrinterType = TECIT.TFORMer.PrinterType.PdfFile;
// Generate PDF

Generate Output as an In-Memory Stream

Starting with TFORMer version 7 it is possible to generate the output as an in-memory stream. No output or temporary files are required, the performance for creating the output is dramatically improved. Currently PDF- and image-output (excluding multi-page TIFF) are generated completely in-memory.
If the output results in a single stream (this is true for Postscript, PDF, multi-page TIFF and ZPL output) use PrintToStream. If the generated output results in several streams (e.g. generating multiple labels as single PNG images) use PrintToStreams.

Use a Single Stream

// Select PDF output
printJob.PrinterType = PrinterType.PdfFile;
// Generate output using the streaming API (no temporary files will be needed on the file-system)
// For demonstration purposes we provide a FileStream, a PDF file named /temp/out.pdf will be generated
// In real life you will most likely use the stream to generate the response for some web-client
using (FileStream streamOut = new FileStream("/temp/out.pdf", FileMode.Create))
// Generate PDF
printJob.PrintToStream (streamOut);
This enumeration specifies the type of output generated by TFORMer SDK.
Definition: Job.cs:26

Use Multiple Streams

// Delegate to create a new stream
// This delegate will be called for each requested stream before any output is generated
// You may use this delegate to open files or to reserve memory
Stream CreateStream (string sName)
// For demonstration purposes we create a file stream
Stream stream = new FileStream (sName, FileMode.Create);
return stream;
// Delegate to close a stream
// This delegate will be called for each requested stream if it is no longer used
// You may use this delegate for cleanup purposes
void CloseStream(Stream stream)
stream.Close ();
// Generate a PNG image named StreamToFileExample.png
// The provided OutputName is passed to CreateStream
// If multiple pages are generated page numbers will get appended (e.g. StreamToFileExample_002.png)
printJob.OutputName = "StreamToFileExample.png";
printJob.PrinterType = PrinterType.ImagePng;
// Generate output with the streaming API using the specified delegates
printJob.PrintToStreams (CreateStream, CloseStream);

Clean Up

Although not required, you may call dispose.

// Free resources used by TFORMer SDK
printJob.Dispose ();
// To invalid the object internally set the variable to null
printJob = null;

More Information

© 2006-2023 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Thu Dec 28 2023 18:45:19 for TFORMer SDK - NET with doxygen 1.9.4