Concepts - Printing

Installation

Install TFORMer Designer and TFORMer Runtime using the setup application. Besides TFORMer Designer (the graphical layout editor) the setup-application installs TFORMer Runtime. TFORMer Runtime is available as DLL, as COM component, as .NET assembly and as stand-alone application (TFPrint). Both the COM component and the .NET assembly of TFORMer Runtime are registered automatically. The .NET assembly is automatically placed in the GAC.

Design and Test a Form Layout

Use TFORMer Designer to create a FormLayout graphically.

In most cases your FormLayout contains dynamic data which is provided by your application during print-time (e.g. an article number for a product label or a ticket-number for an eTicket). TFORMer uses DataFields as place-holders for such dynamic data. These DataFields are declared as well as used within the FormLayout.

For testing purposes TFORMer Designer allows you to provide values for such DataFields manually or to import them from files or data-bases. Testing a FormLayout can therefore be done without any line of code.

Depending on your application choose between stand-alone FormLayouts or Repository-based FormLayouts:

• Stand-Alone Form Layouts
  TFORMer Designer creates stand-alone FormLayouts by default (file extension *.tff). A stand-alone FormLayout can be used on its own. Such a FormLayout contains all the necessary information which is required for printing (layout information, DataField definitions, JobTrayControl, DataSource definitions).
• Repository-based Form Layouts
  If you prefer to organize your FormLayouts and DataFields in a structured way or if you plan to create multiple FormLayouts which use the same data basis (e.g. same DataField definitions), the use of a so-called Repository is recommended. A Repository is a central database for FormLayouts, DataField definitions, JobTrayControl-settings and DataSource definitions. Form layouts, DataField- and DataSource- definitions are stored within a Repository on a per “Project” base. A Project defines DataFields, DataSources and holds (better: refers) FormLayouts. Each of the DataFields defined in a Project is accessible within every FormLayout contained in that Project. A Repository can contain multiple Projects and one special Global Project. DataFields defined within the Global Project may be used by all FormLayouts in all Projects. A Repository uses the file extension *.tfr.

Embed TFORMer Runtime into your Application

Create a new C or C++ project (or choose any programming language which is able to use DLLs or shared libraries).

• Microsoft Windows based operating systems
  At least you need to include the file TFormer6.h and to define the preprocessor variable TECIT_DLLIMPORT:

   #define TECIT_DLLIMPORT
   #include "TFormer6.h"
   #undef  TECIT_DLLIMPORT
  

  
  Link your application with TFormer60.lib.
  
  
• Linux/UNIX based operating systems
  When working on Linux or UNIX some additional lines of code are required: To use TFORMer Runtime include the files TECITStd.h and TFormer6.h into your source code. Make sure to define TECIT_DLLIMPORT, _TEC_UNIX and TEC_UNIX_BUILD before including the files.

   #define TECIT_DLLIMPORT    
   #define _TEC_UNIX
   #define TEC_UNIX_BUILD
   #include <TECITStd/TECITStd.h>
   #include <TFormer6.h>
   #undef   TECIT_DLLIMPORT
   #undef TECIT_DLLIMPORT
   #undef _TEC_UNIX
   #undef TEC_UNIX_BUILD
  

  
  Link your application with the parameter -lTFORMerDLL:

   $ gcc TFORMerSimpleX.c -o TFORMerSimpleX -ldl -lTFormer6 -L/usr/local/lib -I/usr/local/include
  

Note:

Complete sample programs are available here:

• Complete C Program (Microsoft Windows)
• Complete C Program (Linux/UNIX)

License and Initialize TFORMer Runtime

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

 TFormer_License ("John Doe", LICKIND_WORKSTATION, 1, "LicenseKey"); /* Pass license key */

Now initialize TFORMer Runtime:

  HTFORM hTForm = TFormer_Init (NULL); /* Allocate memory and retrieve TFORMer handle (pointer) */
  if (!hTForm)
    return;

Select the Form Layout to be used

When you want to use a Repository based FormLayout (*.tfr), you have to specify the Repository, the Project and the name of the FormLayout:

 eCode = TFormer_SetRepositoryName   (hTForm, "C:/ProgramData/TEC-IT/TFormer6/Samples/Demo Repository/Demos.tfr");
 eCode = TFormer_SetProjectName      (hTForm, "TFORMer_Runtime_Examples");
 eCode = TFormer_SetFormName         (hTForm, "BarcodeLabels");

When using a stand-alone FormLayout (.tff) only one function call is required:

 eCode = TFormer_SetRepositoryName   (hTForm, "C:/SomePath/BarcodeLabels.tff");

Note:

See Methods for Passing Files Additional methods for passing a FormLayout or a Repository to TFORMer Runtime.

Provide Dynamic Data

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. The required data can be passed to TFORMer using different methods:

Pass Data via Program Code

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

 eCode = TFormer_ResetData           (hTForm);                                           /* Clear the data cache */
 eCode = TFormer_NewRecord           (hTForm);                                           /* Add one record */
 eCode = TFormer_SetVarValue         (hTForm, "ArticleNo",  "20021001");                 /* Set the value of the DataField ArticleNo */
 eCode = TFormer_SetVarValue         (hTForm, "ArticleName",  "Sound Blaster Audigy 2"); /* Set the value of the DataField ArticleName */   
 eCode = TFormer_SetVarValue         (hTForm, "ArticlePrice",  "175");                   /* Set the value of the DataField ArticlePrice */

Load Data from Files or Databases

TFORMer Runtime is able to import data from text-/XML-files or from a database (ODBC). The filenames, DSNs or SQL-SELECT statements are specified directly. Take care, that the field-names available in the DataSource (e.g. the column names returned by a SQL-SELECT statement) are equal to the names of the DataFields used in a FormLayout.

 /* Use the XML file InputData.XML as DataSource */
 eCode = TFormer_SetXmlDataFile      (hTForm, "/YourPath/InputData.XML"); 

 /* Use the txt file InputData.txt as DataSource, using ';' as column separator, and '"' as text qualifier */
 eCode = TFormer_SetTxtDataFile      (hTForm, "/YourPath/InputData.txt", ';', '"');

 /* retrieve data from myDSN */
 eCode = TFormer_SetODBCData         (hTForm, "myDSN", "user", "password", "SELECT * FROM myTable");

Note:

See Methods for Passing Files Methods for additional methods for passing a file to TFORMer Runtime.

Load Data from a User-Defined DataSource

DataSources can also be defined by the user with TFORMer Designer as part of a FormLayout. Such a DataSource defines how data is retrieved (e.g. from an ODBC database), the field-mappings and optional DataSource parameters. If you want to use such a DataSource, select it by name as shown below. Use optional DataSource parameters to control certain aspects during runtime (e.g. filenames, SQL statement or an ODBC-DSN).

 /* retrieve data using the predefined datasource myTextDataSource */
 eCode = TFormer_SetDatasourceName   (hTForm, "myTextDataSource");                    
 /* set the value of the user-defined DataSource-Parameter parFile (defined in myTextDataSource) */
 eCode = TFormer_SetDSParameterValue (hTForm, "parFile", "/YourPath/InputData.txt");  

Methods for Passing Files

If functions are requesting filenames (e.g. TFormer_SetRepositoryName, TFormer_SetTxtDataFile, TFormer_SetXmlDataFile, TFormer_SetConfigFile), these may be passed in the following ways:

• Specify the filename directly.
• Specify the filename of a ZIP-file (e.g. with WinZip) containing the required file. When zipping a Repository take care to zip all subdirectories as well. When zipping a stand-alone FormLayout take care to include required image files.
• BASE64-encode the content of the required file (e.g.: see Convert class of .NET) and use this string instead of a filename. When using this method to pass a stand-alone FormLayout this FormLayout must not use embedded images.
• BASE64-encode the content of a ZIP-file (see Convert class of .NET) containing the required file(s). Use this string instead of a filename. When zipping a Repository take care to zip all subdirectories as well. When zipping a stand-alone FormLayout take care to include required image files.

Note:

BASE64 encoded strings must start with the sequence BASE64:. When passing a zipped file TFORMer expects a real WinZip compatible format. A zipped stream is not suitable! For more details please refer to TFORMer Developer Manual and ZIP and BASE64 Handling.

Print or Export the FormLayout (Printer, PDF, PostScript, HTML, ...)

Print the FormLayout

To use the default printer of the current user specify NULL as printer name.

 eCode = TFormer_SetPrinterName  (hTForm, NULL, NULL);              /* select the default printer of the system */
 eCode = TFormer_Print           (hTForm);                          /* print ! */

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

Instead of sending the form to a printer, you can export the output as a PDF, PostScript, HTML, ASCII or image file. ZPL-II is supported too (the ZEBRA printer language). The procedure is the same as printing the form – but instead of setting a printer name, set the name and type of the output file:

 eCode = TFormer_SetPrinterType  (hTForm, ePrinterType_PDFFile ));  /* set the printer type to pdf */
 eCode = TFormer_SetOutputName   (hTForm, "TFORMer.pdf" ));         /* write to the file TFORMer.pdf */
 eCode = TFormer_Print           (hTForm);                          /* print ! */

Clean Up Resources

Clean up all resources allocated by TFORMer Runtime:

 TFormer_Exit (hTForm) /* Free the TFORMer handle */