TFORMer SDK - DLL/Library  7.0
Typedefs | Enumerations | Functions
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...

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.

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

Workflow

The basic steps to generate output are as follows:
- Create a \ref page_concepts_job "Job" \n
The Job class is the main class for printing a \ref page_concepts_formlayout "".
- Create JobData \n
\ref page_concepts_jobdata "" is used to pass data to a \ref page_concepts_job "Job".
- Provide data for the \ref page_concepts_jobdata "" \n
Provide data programmatically or connect the \ref page_concepts_jobdata "" with a file or a database. The \ref page_concepts_jobdata "" is responsible to provide values for the data fields required for the \ref page_concepts_formlayout "" to be printed.
- Connect the \ref page_concepts_job "Job" with the \ref page_concepts_jobdata "" \n
If no \ref page_concepts_jobdata "" is provided for \ref page_concepts_job "Job" the default data for the \ref page_concepts_formlayout "" is used. This default data is identical to the data-set which was used for printing or previewing the \ref page_concepts_formlayout "" in the last <em>TFORMer Designer</em> session.
- Adjust the properties of the \ref page_concepts_job "Job" \n
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 \ref page_concepts_job "Job" \n
To generate the \ref page_concepts_job "Job" based on the \ref page_concepts_formlayout "" and \ref page_concepts_jobdata "" in the required output format use one of the print-methods (#TFormer_Print, #TFormer_PrintToStream, #TFormer_PrintToStream) provided by a \ref page_concepts_job "Job".

More Information


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:
pDataThe buffer holds either the stream name (UTF-8), or the stream data (see EWriteCallBack)
nSizeDataNumber of valid bytes
eWriteCallbackThe type of the callback event (open, data, close) - see EWriteCallBack
lParamUser data provided by a call to TFormer_PrintToStream
See also:
TFormer_PrintToStream, EWriteCallBack.

Enumeration Type Documentation

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

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:
pInstanceThe 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_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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
fnWriteCallback function called for stream events (stream is opened, stream is closed, data is available)
lParamUser 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszFilenamePath 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszFormNameThe 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszTrayControlNameName 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
nCopiesNumber 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszOutputNameThe 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
nPageFromStarting page of print-job (all pages with smaller page numbers are not printed, default is 1)
nPageToEnding 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszPrinterNamePrinter name as defined in Windows (see Control Panel). Use NULL or an empty string ("") to use the default printer of the logged-on user.
pDevModeSpecial device-mode settings for Windows printers, usually NULL to use the default settings. Can be used for modifying printer driver behavior directly.
pszCupsOptionsCUPS 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
ePrinterTypeSpecifies 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszOptionsNamed 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_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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszProjectNameThe 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
pszFileNameFilename 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:
pInstanceThe TFORMer instance provided by a previous call to TFormer_Init
nStartColOnly useful for Label-printing. Specifies the row-number of the first label to be printed (topmost row = 0).
nStartRowOnly useful for Label-printing. Specifies the column-number of the first label to be printed (leftmost column = 0).
See also:
TFormer_Print

© 2006-2012 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Tue Oct 23 2012 16:33:19 for TFORMer SDK - DLL/Library with doxygen 1.8.0