Output Options
Use print options to adjust a job's output, for example its image resolution, paper size or ZPL compression. The available options depend on the output type; restrictions are stated with the option or its group.
TFORMer.xml provides shared defaults. Print options can override relevant settings for an output operation and provide additional controls; not every XML setting has a matching print option. See Output Configuration.
Common Tasks
- Set image resolution: resolution, with a .NET PNG example.
- Change paper size, position or rotation: Page Setup.
- Control copies, collation and duplex printing: Copies and Duplex.
- Choose a filename for each exported page: eval-file-name-per-page.
- Attach ZUGFeRD invoice XML: zugferd-xml.
- Set PDF passwords and permissions: PDF passwords and the permissions options that follow.
- Adjust ZPL compression and printer commands: Zebra (ZPL) Printers, with a rewind-mode example.
- Format month and weekday names and numeric separators: locale.
- Handle unknown data fields: ignore-undefined-fields and data-field handling.
- Choose the encoding for imported text data: text-file-encoding.
- Control whether persistent serial numbers are saved: SavePersistentSerials.
Copy Order
Collation determines the page order when printing multiple copies. For two copies of a three-page document:
- Collated: print each complete set in turn:
1, 2, 3, 1, 2, 3. - Uncollated: print all copies of each page together:
1, 1, 2, 2, 3, 3.
Whether this order can be selected depends on the output type and how copies are produced. See collate and simulatecopies for the applicable settings and restrictions.
Set Options for a Job
Pass an option string through the entry point for your interface before generating output:
These fragments assume an existing job or TFPrint command and an output type that supports the option. Check errors as shown in the corresponding interface guide. The C API has a distinct description for ignore-undefined-fields; the job-based APIs use their respective print methods.
For the native C API's earlier field-assignment timing, see ignore-undefined-fields.
Option String Syntax
An option string contains one or more name=value pairs separated by spaces. Do not put a space between = and the value. For example:
resolution=300 media=A4
The examples below show the option string received by TFORMer SDK, not a programming-language string literal or a complete command-line invocation.
Boolean options
Boolean values are true, yes or 1 (enabled), and false, no or 0 (disabled), regardless of case. You can also omit the assignment:
collatemeanscollate=true.nocollatemeanscollate=false.
The no prefix is joined directly to the option name. Options requiring another value, such as resolution=300, still need an explicit assignment. Check each option's supported output types below.
Values containing spaces
Enclose the whole value in double quotes (") or single quotes ('). The surrounding quotes are not part of the value:
document-title="Annual report" document-author='Alex Smith'
Quotes and backslashes within values
Use a backslash to escape a literal quote or backslash:
| Character in the value | Write in the option string |
|---|---|
Double quote (") |
\" |
Single quote (') |
\' |
Backslash (\) |
\\ |
For PDF document metadata, the following option string illustrates all three. Line breaks may separate options as well as spaces:
document-title="Report \"North\""
document-author='O\'Brien'
document-subject="Archive C:\\Reports"
The resulting metadata values are:
- Title:
Report "North" - Author:
O'Brien - Subject:
Archive C:\Reports(text only; no file is read or written).
Your programming language or shell may require additional escaping to pass this exact string to the SDK. For example, \" above belongs to the SDK option syntax; it is not yet escaped for a C# or Java string literal. See Set Options for a Job for the entry point used by each interface.