Printing and Output

Adjust output options, print (or generate PDF, PostScript, HTML and ASCII) a Repository based or stand-alone FormLayout. More...

Typedefs
typedef ERRCODE(*	TFN_StreamWriteCallback )(BYTE *pData, INT nSizeData, DWORD eWriteCallback, LPARAM lParam)
	Callback function for streamed output.
Enumerations
enum	EWriteCallBack { eWriteCallBack_Open = 1, eWriteCallBack_Data = 2, eWriteCallBack_Close = 3 }
	Enumerations used in the TFN_StreamWriteCallback function. More...
enum	ETFPrintResultType { eTFPrintResultType_None = 0, eTFPrintResultType_Basic, eTFPrintResultType_Medium, eTFPrintResultType_Full }
	Describes the data that should be stored while generating the output. More...
Functions
ERRCODE	TFormer_SetRepositoryName (HTFORM pInstance, LPCSTR pszFileName)
	Sets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.
ERRCODE	TFormer_SetPrinterType (HTFORM pInstance, EPrinterType ePrinterType)
	Sets the type of the generated output.
ERRCODE	TFormer_SetPrinterName (HTFORM pInstance, LPCSTR pszPrinterName, DEVMODE *pDevMode)
	Sets the name of the output device (file or printer) and the type of the printer (e.g.
ERRCODE	TFormer_SetJobTrayControlName (HTFORM pInstance, LPCSTR pszTrayControlName)
	Sets the name of the JobTrayControl to be used for this Job.
ERRCODE	TFormer_SetProjectName (HTFORM pInstance, LPCSTR pszProjectName)
	Specifies the Project-name for printing a Repository-based FormLayout.
ERRCODE	TFormer_SetFormName (HTFORM pInstance, LPCSTR pszFormName)
	Specifies the name of the Repository-based FormLayout.
ERRCODE	TFormer_SetNumberOfCopies (HTFORM pInstance, INT nCopies)
	Sets the number of document copies to be printed.
ERRCODE	TFormer_SetStartRowColumn (HTFORM pInstance, INT nStartCol, INT nStartRow)
	Selects the starting cell of the first label to be printed.
ERRCODE	TFormer_SetOutputName (HTFORM pInstance, LPCSTR pszOutputName)
	This method is used for adjusting the output filename or the name of the spool-job (on Microsoft Windows printers).
ERRCODE	TFormer_SetPageFromTo (HTFORM pInstance, UINT nPageFrom, UINT nPageTo)
	Sets the range of page-numbers to be the printed.
ERRCODE	TFormer_SetPrintOptions (HTFORM pInstance, LPCSTR pszOptions)
	Sets additional options for printing and output generation.
ERRCODE	TFormer_SetConfigFile (HTFORM pInstance, LPCSTR pszFilename)
	Sets the configuration file for TFORMer SDK.
ERRCODE	TFormer_Print (HTFORM pInstance)
	Prints the current FormLayout using the adjusted DataSource.
ERRCODE	TFormer_PrintToStream (HTFORM pInstance, TFN_StreamWriteCallback fnWrite, LPARAM lParam)
	Generates output as in-memory stream using the current FormLayout with the adjusted DataSource.
ERRCODE	TFormer_SetPrintResultType (HTFORM pInstance, ETFPrintResultType ePrintResultType)
	Set the type of data that should be gathered, while printing.
LPCSTR	TFormer_GetPrintResult (HTFORM pInstance, ETFDataFormat eTFDataFormat, ERRCODE *peCode)
	Gets the data of the last print operation in specified format.

---

Detailed Description

Adjust output options, print (or generate PDF, PostScript, HTML and ASCII) a Repository based or stand-alone FormLayout.

This is the main class of TFORMer SDK for generating output.

Overview

Printing (or more general: producing output) is done with the help of a so-called Job. A Job prints a stand-alone or Repository based FormLayout with dynamic data provided by JobData.

A Job provides various methods for controlling the output behavior. Among other functions it is possible

• to select the target device and the required output format (Output Format Prefixes),
• set Job options (Print Options),
• and to select a specific configuration file (TFORMer.XML Configuration File).

Workflow

The basic steps to generate output are as follows:

• Create a Job
  The Job class is the main class for printing a FormLayout.
• Create JobData
  JobData is used to pass data to a Job.
• Provide data for the JobData
  Provide data programmatically or connect the JobData with a file or a database. The JobData is responsible to provide values for the data fields required for the FormLayout to be printed.
• Connect the Job with the JobData
  If no JobData is provided for Job the default data for the FormLayout is used. This default data is identical to the data-set which was used for printing or previewing the FormLayout in the last TFORMer Designer session.
• Adjust the properties of the Job
  The most important properties are the output-type and the name of the target device (TFormer_SetOutputName, TFormer_SetPrinterType or TFormer_SetPrinterName). The order in which the properties are set is irrelevant.
• Print the Job
  To generate the Job based on the FormLayout and JobData in the required output format use one of the print-methods (TFormer_Print, TFormer_PrintToStream, TFormer_PrintToStream) provided by a Job.

More Information

• JobData
  Base class for JobData

---

Typedef Documentation

typedef ERRCODE( * TFN_StreamWriteCallback)(BYTE *pData, INT nSizeData, DWORD eWriteCallback, LPARAM lParam)

Callback function for streamed output.

If output is generated to an in-memory stream this function is required. It is called multiple times during the lifetime of a stream.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pData	The buffer holds either the stream name (UTF-8), or the stream data (see EWriteCallBack)
nSizeData	Number of valid bytes
eWriteCallback	The type of the callback event (open, data, close) - see EWriteCallBack
lParam	User data provided by a call to TFormer_PrintToStream

See also:

TFormer_PrintToStream, EWriteCallBack.

---

Enumeration Type Documentation

enum ETFPrintResultType

Describes the data that should be stored while generating the output.

After the output has been generated the data can be retrieved by a call to TFormer_GetPrintResult.

See also:

TFormer_SetPrintResultType, TFormer_GetPrintResult

Enumerator:

eTFPrintResultType_None	No data should be generated.
eTFPrintResultType_Basic	Only basic information should be generated.
eTFPrintResultType_Medium	Additional data will be stored.
eTFPrintResultType_Full	All information possible will be stored and is available after output generation.

enum EWriteCallBack

Enumerations used in the TFN_StreamWriteCallback function.

The TFN_StreamWriteCallback is required only when generating output as in-memory stream(s).

See also:

TFormer_PrintToStream, TFN_StreamWriteCallback.

Enumerator:

eWriteCallBack_Open	Event for opening a stream. pData points to the name of the stream which is an UTF-8 encoded string
eWriteCallBack_Data	Event for new stream-data. pData points to the available data.
eWriteCallBack_Close	Event for closing a stream. pData is NULL

---

Function Documentation

LPCSTR TFormer_GetPrintResult	(	HTFORM	pInstance,
		ETFDataFormat	eTFDataFormat,
		ERRCODE *	peCode
	)

Gets the data of the last print operation in specified format.

Call this function after TFormer_Print or TFormer_PrintToStream to get the data that has been gathered while printing. Specify the data to be gathered by a call to TFormer_SetPrintResultType before TFormer_Print or TFormer_PrintToStream.

Returns:

The data that has been gathered while printing. This returned value is only valid if peCode is ErrOk (0).

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
eTFDataFormat	Specifies the format of the data to be returned
peCode	Error code, ErrOk (0) in case of success

See also:

TFormer_SetPrintResultType, TFormer_Print, TFormer_PrintToStream

ERRCODE TFormer_Print

(

HTFORM

pInstance

)

Prints the current FormLayout using the adjusted DataSource.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance

The TFORMer instance provided by a previous call to TFormer_Init

Remarks:

• For Repository based FormLayouts:
  Starts the output based on the selected Repository, Project, FormLayout name and data (see TFormer_SetXXXDataFile or TFormer_NewRecord, TFormer_SetVarValue).
• For stand-alone FormLayouts:
  Starts the output based on the selected stand-alone FormLayout and the input data (see TFormer_SetXXXDataFile or TFormer_NewRecord, TFormer_SetVarValue).

Note:

Behavior if no input data was supplied: If no DataSource was specified (either by TFormer_SetXXXDataFile, TFormer_SetODBCData or via TFormer_NewRecord and TFormer_SetVarValue) the default data-file (located in the same directory as the FormLayout itself and generated by the last TFORMer Designer session) is used. If this default data-file does not exists no output will be produced. The name of the default data-file is path/FormName.xml.

TFORMer uses a configuration file named TFORMer.xml for adjusting PostScript, PDF and HTML output options like form sizes, color mode and so on. Check out TFormer_SetConfigFile or refer to the TFORMer Developer Manual for more information.

See also:

TFormer_SetRepositoryName, TFormer_SetProjectName, TFormer_SetFormName, TFormer_SetPrinterName, TFormer_SetTxtDataFile, TFormer_SetXmlDataFile, TFormer_SetODBCData, TFormer_SetConfigFile

ERRCODE TFormer_PrintToStream	(	HTFORM	pInstance,
		TFN_StreamWriteCallback	fnWrite,
		LPARAM	lParam
	)

Generates output as in-memory stream using the current FormLayout with the adjusted DataSource.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
fnWrite	Callback function called for stream events (stream is opened, stream is closed, data is available)
lParam	User data that will be passed unmodified to the callback function specified in fnWrite

Remarks:

This function is similar to TFormer_Print. Instead of generating output files or sending the output directly to a printer, the data will be streamed to the callback function. For all output formats which are generating a single output file (PDF, PostScript, Multipage TIFF, ZPL) it is guaranteed that only one open and close event is triggered per output request. For all other output formats (e.g. JPG output with multiple output pages) this function may trigger multiple open and close events. The data event may be triggered multiple times in each case.

Currently for PDF and image printer output (excluding multi-page TIFF), no temporary files are required on the file-system. All other output formats may require read/write file-system access for temporary files.

// Define the call-back function for streaming
ERRCODE __stdcall StreamCallback (BYTE* pBuffer, INT nSizeBuffer, DWORD dwFlags, LPARAM lParam)
{
  ERRCODE eCode = ErrOk;
  if      (dwFlags == eWriteCallBack_Data)
  { 
    // Process data (copy or write the data to the stream)
  }    
  else if (dwFlags == eWriteCallBack_Close)
  {
    // Close the current stream
  }    
  else if (dwFlags == eWriteCallBack_Open)
  {
    // Open a new stream, the name which is set in TFormer_SetOutputName is provided via pBuffer (UTF8 encoded)
  }

  return eCode;
}

Instead of TFormer_Print use TFormer_PrintToStream and provide the callback function.

  // Generate a PNG image named StreamToFileExample.png
  // The provided OutputName is passed to call-back function
  // If multiple pages are generated page numbers will get appended (e.g. StreamToFileExample_002.png)
  eCode = TFormer_SetOutputName   (hTForm, "StreamToFileExample.png");
  eCode = TFormer_SetPrinterType  (hTForm, ePrinterType_ImagePng);

  // Generate PDF
  // Instead of #TFormer_Print use #TFormer_PrintToStream and provide the callback function.
  eCode = TFormer_PrintToStream   (hTForm, StreamCallback, (LPARAM)0);

See also:

TFormer_Print, TFN_StreamWriteCallback, EWriteCallBack

ERRCODE TFormer_SetConfigFile	(	HTFORM	pInstance,
		LPCSTR	pszFilename
	)

Sets the configuration file for TFORMer SDK.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszFilename	Path and filename of a TFORMer configuration file

See also:

TFORMer.XML Configuration File

Remarks:

If no file is specified using this function, TFormer_Print will use the default configuration file.

Note:

The configuration file may be passed as file or as BASE64 stream to TFORMer SDK. Refer to Passing Files for details.

See also:

TFormer_Print

ERRCODE TFormer_SetFormName	(	HTFORM	pInstance,
		LPCSTR	pszFormName
	)

Specifies the name of the Repository-based FormLayout.

Use this function to specify the name of the FormLayout which is referenced from within a Project of a Repository. Do not use this property for a stand-alone FormLayout.

Returns:

- ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszFormName	The name of the FormLayout as defined using TFORMer Designer.

Note:

Must be called before TFormer_Print. This call is mandatory if used with a Repository. Cached data (set with TFormer_NewRecord and TFormer_SetVarValue or by importing data-files) as well as the already loaded FormLayout are discarded.

See also:

TFormer_SetRepositoryName, TFormer_SetProjectName.

ERRCODE TFormer_SetJobTrayControlName	(	HTFORM	pInstance,
		LPCSTR	pszTrayControlName
	)

Sets the name of the JobTrayControl to be used for this Job.

Specify the JobTrayControl for the current Job. If this property is not set then the Job is generated with the JobTrayControl named _Default_.

This function must be called before TFormer_Print.

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszTrayControlName	Name of the JobTrayControl as defined with TFORMer Designer - use NULL or "" to use the _Default_ JobTrayControl

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Note:

TFORMer uses a configuration file named TFORMer.xml for adjusting output options and paper format names. Since paper format names are also used in JobTrayControl please check out TFormer_SetConfigFile too.

See also:

JobTrayControl

ERRCODE TFormer_SetNumberOfCopies	(	HTFORM	pInstance,
		INT	nCopies
	)

Sets the number of document copies to be printed.

The default value is 1. This function must be called before TFormer_Print to instruct TFORMer SDK to produce multiple copies (using the same data and FormLayout) of one print job.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
nCopies	Number of document copies

See also:

TFormer_Print

ERRCODE TFormer_SetOutputName	(	HTFORM	pInstance,
		LPCSTR	pszOutputName
	)

This method is used for adjusting the output filename or the name of the spool-job (on Microsoft Windows printers).

Sets the filename or the name of the spool-job used for printing (as displayed in the spooler). Call before TFormer_Print is invoked - otherwise the default values will be used. To reset this value to default call TFormer_SetOutputName (pInstance, NULL).

Use this function in conjunction with TFormer_SetPrinterType to specify the type and the target of the generated output. Alternatively you can use TFormer_SetPrinterName - this function specifies output type and target device within one string.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszOutputName	The output filename or the name of the spool-job (on Microsoft Windows printers).

See also:

TFormer_Print

ERRCODE TFormer_SetPageFromTo	(	HTFORM	pInstance,
		UINT	nPageFrom,
		UINT	nPageTo
	)

Sets the range of page-numbers to be the printed.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
nPageFrom	Starting page of print-job (all pages with smaller page numbers are not printed, default is 1)
nPageTo	Ending page of print-job (all pages with higher page numbers are not printed, default is UINT_MAX, or 0xffffffff)

Remarks:

If required this function must be called before TFormer_Print. To restore this setting (printing of all pages of the job), call the following command:

  TFormer_SetPageFromTo (pInstance, 0, 0);

See also:

TFormer_Print

ERRCODE TFormer_SetPrinterName	(	HTFORM	pInstance,
		LPCSTR	pszPrinterName,
		DEVMODE *	pDevMode
	)

Sets the name of the output device (file or printer) and the type of the printer (e.g.

normal printer, PDF, JPG,....).

The function specifies the output format as well as the target device or target filename. Refer to Output Format Prefixes for a description of the supported output formats.

On Windows platforms the parameter pDevMode may be used to modify default GDI printer settings. All valid fields passed via pDevMode are merged with the default settings of the printer question. For more information check out the Win32 SDK documentation.

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszPrinterName	Printer name as defined in Windows (see Control Panel). Use NULL or an empty string ("") to use the default printer of the logged-on user.
pDevMode	Special device-mode settings for Windows printers, usually NULL to use the default settings. Can be used for modifying printer driver behavior directly.
pszCupsOptions	CUPS options string which is passed directly to CUPS (Linux/UNIX only). Use NULL for default settings.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Note:

This function must be called prior generating output (see TFormer_Print, TFormer_PrintToStream or TFormer_PrintToStream).

Usually this function is used instead of TFormer_SetPrinterType and TFormer_SetOutputName. If you print to a Windows printer you can use TFormer_SetOutputName to specify the name of the spool job.

See also:

Output Format Prefixes, TFormer_SetOutputName, TFormer_SetPrinterType, TFormer_SetPrinterName

ERRCODE TFormer_SetPrinterType	(	HTFORM	pInstance,
		EPrinterType	ePrinterType
	)

Sets the type of the generated output.

Use TFormer_SetOutputName in conjunction with TFormer_SetPrinterType to specify the type and the target of the generated output. TFormer_SetPrinterName overrides the settings of TFormer_SetOutputName and TFormer_SetPrinterType. Refer to Output Format Prefixes for a description of the supported output formats.

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
ePrinterType	Specifies the type of output to be generated, see EPrinterType.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Note:

Call this function prior to TFormer_SetOutputName.

See also:

Output Format Prefixes, TFormer_SetOutputName, TFormer_SetPrinterType, TFormer_SetPrinterName

ERRCODE TFormer_SetPrintOptions	(	HTFORM	pInstance,
		LPCSTR	pszOptions
	)

Sets additional options for printing and output generation.

If required this function must be called before TFormer_Print. The options are applied to internal structures inside TFormer_Print, and are restored afterwards.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszOptions	Named values delimited by white-spaces in the form of [OptionName]=[value] [OptionName] without an additional value is treated as if [OptionName]=true is provided no[OptionName] is treated as if [OptionName]=false is provided

See also:

Print Options

TFormer_Print

ERRCODE TFormer_SetPrintResultType	(	HTFORM	pInstance,
		ETFPrintResultType	ePrintResultType
	)

Set the type of data that should be gathered, while printing.

Call this function before TFormer_Print or TFormer_PrintToStream to specify the data that should be gathered while printing. After the output has been generated the data can retrieved by a call to TFormer_GetPrintResult.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
dwLevel	Specifies the data that should be gathered while printing ( Currently 0 (Default) and 1 Basic is supported ).

See also:

TFormer_GetPrintResult, TFormer_Print, TFormer_PrintToStream

ERRCODE TFormer_SetProjectName	(	HTFORM	pInstance,
		LPCSTR	pszProjectName
	)

Specifies the Project-name for printing a Repository-based FormLayout.

When using a Repository-based FormLayout use this function to provide the Project name. In addition the name of the FormLayout must be set using TFormer_SetFormName.

Do not use this property for a stand-alone FormLayout.

Returns:

- ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The Project name as defined using TFORMer Designer.

Note:

Call this function before TFormer_SetFormName. Cached data (set with TFormer_NewRecord and TFormer_SetVarValue or by importing data-files) as well as the actual FormLayout are discarded.

See also:

TFormer_SetRepositoryName, TFormer_SetFormName.

ERRCODE TFormer_SetRepositoryName	(	HTFORM	pInstance,
		LPCSTR	pszFileName
	)

Sets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszFileName	Filename of the Repository or the stand-alone FormLayout

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Use this method to provide either the filename of the Repository (*.tfr file) or the stand-alone FormLayout (*.tff file). If you are using a Repository you need to specify the Project (TFormer_SetProjectName) and the FormLayout (TFormer_SetFormName) as well.

See also:

Repository / FormLayout, FormLayout, Passing Files

Note:

When changing the Repository, the Project or the FormLayout all internal cached data is discarded.

ERRCODE TFormer_SetStartRowColumn	(	HTFORM	pInstance,
		INT	nStartCol,
		INT	nStartRow
	)

Selects the starting cell of the first label to be printed.

This functions sets the row- and column number of the first label to be printed. Usually TFORMer prints the first label of a label-style report at the first available position of a page (this is the top / left label). Numbering starts with 0 (leftmost column = 0/topmost row = 0). Call this function before TFormer_Print otherwise the default will be used (the label in the upper left corner of the page (0, 0)).

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
nStartCol	Only useful for Label-printing. Specifies the row-number of the first label to be printed (topmost row = 0).
nStartRow	Only useful for Label-printing. Specifies the column-number of the first label to be printed (leftmost column = 0).

See also:

TFormer_Print